Library Types

In CODESYS, a differentiation is made between the following types of libraries:

For each type, there is a characteristic set of rules for implementing the specific functionalities. Markers are defined, allowing CODESYS to recognize the library type. By knowing the type, CODESYS can apply rules automatically (for example, to add interface libraries correctly) or monitor the compliance of libraries (for example, Check all Pool Objects).

Common Libraries

In most cases, this is the standard type of a library.

  • A common library should be referenced by other libraries by using a placeholder.

  • A common library has been marked with the property Placeholder (Text) := <Placeholder name>.

  • A common library should be decorated with the property LanguageModelAttribute(Text) := 'qualified-access-only'.

  • A common library has been assigned a prefix or namespace.

  • The file name contains no type specific suffix.

Container Libraries

A container library is a tool for conveniently including a set of libraries in the current project. A container library publishes all symbols of its referenced libraries at its top-level.

  • A container library should be referenced by other libraries with a fix version.

  • A container library has been marked with IsContainerLibrary (Bool) := True.

  • A container library must contain only a library manager and some library documentation.

  • The libraries inside of the library manager should be referenced according to the common rules for library referencing.

  • The Publish all IEC Symbols… dialog option must be set for each referenced library.

  • The qualified-access-only property is permitted.

  • These requirements for a container library will be checked by the compiler when Check all Pool Objects is executed.

  • The file name contains the type specific suffix “_Cnt”.

Note

As a result of a structural change of a library, the absolute reference of the resulting container library can be deviated from by assigning the property IsCommonLibraryContainer to the library instead of the property IsContainerLibrary.

Additionally the property Placeholder has to be used of course.

This is especially useful for former system libraries whose container libraries must still be referenced with a placeholder for compatibility reasons.

Interface Libraries

Interface libraries define the interface of a software component and can provide only language elements that do not generate code (for example, constants, structures, and interfaces).
It can only be extended in a compatible way, but never changed [1].
  • An interface library should be always referenced by other libraries with the “newest” version constraint (“*” - The version number is a star sign).

  • An interface library has been marked with IsInterfaceLibrary (Bool) := True.

  • An interface library contains only elements not generating code.

  • Every Interface type has to extend the predefined __SYSTEM.IQueryInterface type (see: Query Interface).

  • If this is not possible, then the Interface type has to be marked with the no-query-interface-check attribute.

  • These requirements for an interface library will be checked by the compiler when Check all Pool Objects is executed.

  • An interface library should be extended in a compatible way only, but never ever changed! [1] (see: Compatibility).

  • After the first release of an interface library, the setting of the compiler version must never be changed. [2]

  • These requirements for an interface library will be checked by CODESYS while you try to install the library in the Library Repository.

  • The file name contains the type specific suffix “_Itfs”.

If there is no way to extend an interface library in a compatible way, please follow the rules for changing a interface library.

Note

The compatibility of an interface library is a serious matter. The promises made with its release must be able to be kept under all circumstances. As soon as this is not possible (because, for example, the content is the responsibility of a standardization body), consideration should be given to publishing the planned content in a common library, for example. A common library does not necessarily have to contain executable code, it may contain the same content as an interface library without having to follow the strict rules of such a library.

End-User Libraries

This is a type of super-category for libraries. It is intended to make it a brand that represents exceptional quality. Only a small set of select libraries may be marked with End-User Library.

  • An end-user library has been marked with the IsEndUserLibrary (Bool) := True property.

  • Libraries labeled in this way take into account the special needs of end users:

    • Synchronous functions are carefully crafted together with the corresponding asynchronous building blocks.

    • The libraries are optimized for a easy use in graphical programming languages, such as FBD and CFC.

    • Resource management (Before OnlineChange, Download, Reset, …)

    • Using generally accepted patterns (for example, the PLCopen “Execute / Busy / Done” pattern)

    • Conform to uniform Coding Rules

    • Type checking of handles (use INTERFACE not DWORD)

    • OnlineChange-aware parameter types

    • No experience in object orientation, pointers, or ADR and REF= operators is required to use these libraries.

  • An end-user library contains detailed documentation (accessible by pressing F1) in the online help system.

  • Whenever possible, an end-user library behaves the same way on all devices.

  • In the future, end-user libraries will be presented and offered in a special way (for example, in the Add Library dialog).

The decision for a specific library type is important because not every library that contains an Interface type should be marked automatically as a Interface Library. Usually choosing the common library type should be the start of successful library development.