Using libraries

Libraries are collections of reusable objects such as:

POUs such as function blocks or functions
Interfaces and their methods and properties
Data types such as enumerations, structures, aliases, unions
Global variable, constants, parameter lists
Text lists, image pools, visualizations, visualization elements
External files (e.g. documentation)

Integration of a library in a project enables the library modules to be used in a project in the same way as the other function blocks and variables, which are defined directly in the project.

	Recommendations and notes In addition to the library use descriptions, see the application notes in Recommendations and notes.

The following steps are relevant for the application of libraries. Creation, installation and management of libraries.

If a library was already created and installed (this is the case for system libraries, for example), only the library management or integration step is required. Some libraries have to be created and installed first.

Library creation

A choice of two library types is available when a library is created: *.library (source library) and *.compiled-library (compiled library with source code protection).
Prerequisites and further information can be found in section Library creation.

Library installation

Before a library can be used in a project, the library first hast to be installed on the system. Libraries are managed on the local system in different "repositories" (directories, storage locations). Before a library can be integrated in a project, it has to be installed in such a repository with a defined version number on the local system.

Exception: projects referenced as library.
See Use PLC project as referenced library.

If a library version is used that is not installed in the repository, this is flagged up at the reference in the project tree.
Libraries are installed in the Library Repository.

Library management

The Library Manager offers a good overview of the PLC library references used in the project and can be used to integrate libraries or placeholders in a project. The integration makes the library reference elements available for use in the project.
Library references, which are referenced as sub-libraries in another library, are also shown in the Library Manager. In addition, there are “hidden libraries” (see section Command Properties).
Whenever a library is used, a unique library version is referenced. This version is specified as the effective version. If the library was attached with a fixed version (e.g. 3.3.0.0), the project will always use this library version, even if a more recent version is or becomes available. Alternatively, the setting "Always newest"/"*" can be used to automatically ensure that the latest library version is used at all times. In this case, TwinCAT always uses the latest version of the library found in the library repository. For more information and a sample, see the Command Set to Always Newest Version.
It is not possible to add the same version of the same library more than once to a library manager. A version of a library can be referenced in a library manager either as a library or as a placeholder.
If the library is not compiled (*.compiled-library) but is instead available as a *.library file, the library elements listed in the Library Manager can be opened by double-clicking on the respective entry.
You can add library references in the form of a library or a placeholder to the Library Manager and include them in your application (see section Command Add library). Placeholders should be used whenever possible. Further information can be found in section Library placeholders.
When a library module is addressed in the project, the libraries and repositories are searched in the order in which they are listed in the Library Repository. Further information can be found in section Unambiguous access to library modules or variables.

Library documentation

TwinCAT offers a wide range of library documentation options. Further information can be found in section Library documentation.

Refer also to the following for information on these topics:

Referenced libraries
Library versions
Unambiguous access to library modules and variables
TwinCAT 2.x PLC Control libraries
External and internal libraries or library modules, late binding

Referenced libraries

A library can integrate other libraries (referenced libraries), whereby the nesting can be as deep as required. If such a "father" library is then itself integrated in a project, the libraries referenced in it are available there too.
Library references should always be defined via library placeholders, in order to avoid problems that may arise through version dependencies or the need to use manufacturer-specific libraries.
In the properties for each referenced library you can specify how it should behave later, when it is integrated in a project via the "father" library, e.g. whether it should be "hidden" in the Library Manager.

Library versions

Several versions of a library can be installed on the system at the same time.
Several versions of a library can be integrated in the project at the same time. However, this is not advisable. In this case, a unique namespace must be assigned to each of the libraries, and access to the symbols must be qualified. Examples: V1.Send, V2.Send
The version or resolution of libraries or placeholders can be configured in the Properties window. The resolution of placeholders can also be adapted in the Placeholder dialog.
It is strongly recommended to use placeholders, if other libraries are referenced in a library, but also in order to make a project compatible. In this way it is possible to avoid problems arising from version dependencies or the need to use manufacturer-specific libraries.

Unambiguous access to library modules or variables

If several modules or variables with the same name are available in the project and in libraries, access to a module component should be unambiguous. Related to libraries, uniqueness is achieved by adding the namespace of the library before the module name.
The default setting for the namespace of a library is the library title. On the other hand, a different namespace can also be explicitly defined for a library: either generally for the library when creating the library in the project properties or for local use of the library in a project in the properties window of the library reference.
The namespace of the library must be used as a prefix of the identifier so that unique access is possible to a module that exists multiple times in the project.
Sample:

The library Lib1 is integrated in an application project.
The function F_Sample is declared both in library Lib1 and in the application.
In order to implement access to the two functions, the namespace of the library is added before the library function is called. This makes reference to the function of library Lib1 unambiguous.
Calling the application function nResult := F_Sample(nInput := nVar);
Calling the library function nResult := Lib1.F_Sample(nInput := nVar);

TwinCAT 2.x PLC Control libraries

Libraries that were created with TwinCAT 2.x PLC Control (*.lib) continue to be supported.
An "old" library project (*.lib) can be used in TwinCAT 3 PLC and converted to a "new library" (*.library/*.compiled-library).
If an existing project that references old libraries is opened, the user can select whether these references should be retained, replaced by others, or deleted. If they are to be retained, the respective libraries are converted to the new format and automatically installed in the “System” library repository. If they do not contain the required project information, it can be added directly. The procedure, based on which a particular old library was handled during conversion of an old project, can be stored in the project options. If the same library then reappears in the conversion of another old project, the procedure does not have to be defined again, but is executed automatically.
Section Add New Item... describes the procedure for opening and converting projects and libraries.

External and internal library modules, late binding

External library modules are firmware functions whose implementation is not included in the PLC library. For libraries with firmware functions, the firmware must be available on the target system; it is not bound until the application runs there.

Further Information