Releasing Libraries

Besides the (system) libraries delivered with PLCnext Engineer by default, you can release your own libraries containing user-defined elements and objects. Such libraries can be distributed and used in other PLCnext Engineer projects.

PLCnext Engineer supports mixed user libraries which can contain a combination of IEC 61131-3 code (local standard and/or safety-related POUs), local devices, local HMI symbols and images. It is also possible to release only one element type as library, for example only code or only devices.

The selection of the project parts (items) to be released is to be done by clicking category icons in the 'Release As Libraries' dialog (see step-by-step procedure below).

General notes

When releasing a library, observe the following:

To protect your know-how when distributing IEC code libraries, you can define the visibility of each released user-defined POU/data type and specify the degree of library redistributility.
If the project to be released contains already referenced libraries which shall also be included in the newly released library, the resulting library still contains its library reference. This is called a cascaded reference. See the topic "Cascaded References: Referenced Libraries in Released IEC Libraries" for further details.
Note that the signature checksum is different from the library ID (see step 7 in the following procedure): when releasing a IEC code library as described here, PLCnext Engineer calculates checksums over the contained components which are used as signature. By means of this signature, the library can be identified uniquely. If included in a project, the signature is verified each time the project is loaded. This way, any modifications (new version?) or data corruptions are recognized. See topic "Tamper Protection of Libraries" for details.
PLCnext Engineer allows you to add your own user-defined documentation to user POUs contained in the released library. This way you can provide documentation on the library POUs that will help, for example, other users to understand how the POUs have to be used (see the topic "Providing Help Files" for details).

When including safety-related POUs in a released library, additionally observe the following:

If the project contains safety-related C function block POUs with loadable C function code, a code signing certificate with a private key is required. Details are described in the section "Loadable C Functions as Released Library" below.
A safety-related FB POU can only be released in an IEC library if it is instantiated in the safety-related S_Main program.

How to release a library

Note
The following steps are only possible in programming mode. If the debug mode is active, first detach PLCnext Engineer (via the context menu of controller node or in the 'Cockpit').

Open the project from which you want to release parts as a library.
Select 'File > Release As Library...'.

In the 'Release As Library' dialog, select the project parts (items) to be included by clicking the corresponding icons in the dialog toolbar.

After activating an icon, the corresponding types are displayed in the field below. For some items, further selections or settings are possible.

Category icon Meaning

Programming: user-defined standard POUs and data types used in your project.
By selecting this category, all local POUs will be added to the released library. In the current version, it is not possible to include or exclude particular POUs.

Devices you have imported into the project via device description files (*.GSDML). These devices are available in the 'Local' folder of the 'Network' category (COMPONENTS area).
Device templates with already configured devices (available in the 'Local > Device Templates' folder of the 'Network' category in the COMPONENTS area).
You can include/exclude particular devices from the library, by activating/deactivating the 'Selection' checkbox of the corresponding device in the tree below.

HMI objects: user-defined HMI symbols and HMI images you have created and added to your project are available in the 'Local' folder of the 'HMI' category (COMPONENTS area).
You can include/exclude particular symbols/images from the library, by activating/deactivating the 'Selection' checkbox of the corresponding item in the tree below.

Safety-related user-defined POUs.
By selecting this category, all local safety-related POUs will be added to the released library. In the current version, it is not possible, to include or exclude particular POUs.

Enter a meaningful library name.
If you do not enter/select a directory path for the new library file, the entered library name is automatically completed with the path to the default library directory. (This default path can be changed under 'Extras > Options', dialog area 'Tool | Directories'.)
Optionally, you can define a version number and enter a description.
Only for IEC code ('Programming' and/or 'Safety' selected in the toolbar):
Optionally, you can add help files (in *.chm or HTML5 format) that provide help information on the library POUs to be released.
If the POU help descriptions are provided in a CHM file, click the 'Add file(s)' button in the 'Help file(s)' area and select the chm file to be added (the button is disabled if the 'Use HMTL5 help system' checkbox is activated). If you have created HTML5 help files using the POU's 'Description' editor, activate the 'Use HMTL5 help system' button. (The HTML5 help files created for the POUs are automatically integrated when generating the library.)
Furthermore, you can add language description files which contain tooltip texts and folder names provided for the library POUs.
See the topic "Providing Help Files" for details.
Only for IEC code ('Programming' and/or 'Safety' selected in the toolbar):
To protect your know-how when distributing POUs in libraries, you can define the visibility of each user-defined POU and data type.
For that purpose, the tree in the dialog lists provides a drop-down list in the 'Visibility' column. Refer to the topic "Knowledge Protection for Libraries" for details.
By default, each standard POU/data type is set to 'Visible'. Safety-related POUs, devices, and HMI objects are always 'Visible'.
Only if 'Safety' is selected in the toolbar and the project contains safety-related C function block POUs with loadable C function code:
The 'Private key file' text box is shown in the 'Release As Libraries' dialog. Here, you must select the private key file (.pfx file) which relates to the code signing certificate that is specified in the Trust Store (see corresponding table row in the 'Options' dialog description) of PLCnext Engineer. Further details can also be found in the topic "Loadable C Functions as Released Library" below.
1. Click the browse button right of the 'Private key file' text box to open the file selection dialog.
2. In the file selection dialog, select your .pfx file and click 'OK'. The private key file authentication mask appears.
3. In the authentication mask, enter the private key file password and press <Enter>.
  If the authentication to the selected private key file fails, the text box is shown with a red border. A tooltip on the text box shows a corresponding message.
Set the distributability of your library by selecting an entry from the 'Redistribution' drop-down list. This way you specify whether a user of your library will be able to release his project as library if your library is included in it.
If the same project has already been released as library, the checkbox 'Create new library ID' is active. If checked, the library ID will be overwritten by a new ID.

Note
When releasing a library again, always a new signature (checksum) is calculated for the new library version, independently of the checkbox setting.
Finally,
- save the current settings to keep them for future releases by pressing the 'Save & Close' button
  or
- press the 'Release' button to create the library.
  The selected project parts are then exported into a *.pcwlx library file in the directory specified above.

Category icon	Meaning
	Programming: user-defined standard POUs and data types used in your project. By selecting this category, all local POUs will be added to the released library. In the current version, it is not possible to include or exclude particular POUs.
	Devices you have imported into the project via device description files (*.GSDML). These devices are available in the 'Local' folder of the 'Network' category (COMPONENTS area). Device templates with already configured devices (available in the 'Local > Device Templates' folder of the 'Network' category in the COMPONENTS area). You can include/exclude particular devices from the library, by activating/deactivating the 'Selection' checkbox of the corresponding device in the tree below.
	HMI objects: user-defined HMI symbols and HMI images you have created and added to your project are available in the 'Local' folder of the 'HMI' category (COMPONENTS area). You can include/exclude particular symbols/images from the library, by activating/deactivating the 'Selection' checkbox of the corresponding item in the tree below.
	Safety-related user-defined POUs. By selecting this category, all local safety-related POUs will be added to the released library. In the current version, it is not possible, to include or exclude particular POUs.

For safety-related POUs, a checksum is calculated which is used to seal the library file. When inserting the library in a project, the compiler checks the integrity of the library by means of this seal.

Note
Keep the engineering project sources for later changes.

Once you have created the released libraries from your user-defined elements, you can add them to another PLCnext Engineer project and use their content in the project (see the topic "Adding Libraries" for details).