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. 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.
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., 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 an example, see the command Command Set to Always Newest Version.
If the library is not encoded (*.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.

The following section provides 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 a project contains several modules or variables with the same name, access to a module component must be unambiguous, otherwise compiler errors occur. This applies to local project modules or variables as well as modules or variables that are available in integrated libraries and libraries referenced by them. In such cases uniqueness is achieved by adding the library namespace before the module name.
The default setting for the namespace of a library is the library title. Alternatively, a different namespace can be defined explicitly, either generally for the library in the project properties during library generation, or in the Properties window of the library reference for local use of the library in a project.
The namespace of the library must be used as prefix of the identifier, in order to enable unambiguous access to a module that is used several times in a project.
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.
Call of the application function    nResult := F_Sample(nInput := nVar);
Call of 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 libraries or library modules, late binding

In contrast to an internal library (TwinCAT 3 PLC library project), an "external library" is a library file with firmware functions: it must exist on the target system and is not bound until the application runs there.
Additional information
Recommendations and notes
Library creation
Library installation
Library management
Library placeholders
Library documentation
Other commands and dialogs