How to change a library

Note

Compatibility: Compatibility of two libraries usually means that they react in the same way according to the requirements of an application.

Important

After changing a library it is necessary to change its version number to a new, never earlier assigned, number! Changing a library without adapting its version number results in huge difficulties.

The following restrictions must never be violated by a change to an already released library:

  1. After the update to a newer version of a library, no errors must be displayed after compiling the referencing library (CheckAllPoolObjects) or application (GenerateCode), if it could previously be compiled without errors.

  2. After changing a library reference to new version of a interface library, neither the OnlineChange service nor the Download service may occur when logging into a device, if the previous version of the library or application is currently available on this device.

  3. After downloading an application in which some libraries have been updated to a newer version, to a device equipped with an unchanged firmware version, there must be no unresolved references.

A already released library can be further evolved in three different ways:

Extending in a compatible Way

Common Libraries

Changing a common library results at least in an online change the next time you connect to the controller.
After changing a common library CODESYS must not report compiler errors or unresolved references.

The following changes can be made to a library as part of a further development in a compatible way.

  • Each change to a common library requires a change to the version number in relation to the last release. The version number receives a value that is greater than its value at the last release. In particular, the properties Title, Company, Filename and Placeholder in the project information must not differ in comparison between the current and the predecessor library. (See Test Specification: STL_I_03)

  • The set of symbols of the current library must be a superset of the symbols of its predecessor. A common library is incompatible with its predecessor if certain symbols are omitted during the transition from the current version to the next. (See Test Specification: STL_S_01)

  • A symbol of the predecessor library must appear unchanged in the current library. Changes to the signature of an existing symbol mean an incompatible change to the current library in relation to its predecessor. (See Test Specification: STL_S_02)

  • In common libraries, the set of library references in the current library must be a superset of the set of library references in the previous library. If library references are omitted during the transition from the previous library to the current library, this change is an incompatible change. (See Test Specification: STL_R_02)

An common library is not backwards compatible if the newer version…

  • … changes the signature of INTERFACE, FUNCTION_BLOCK types (method, property) or FUNCTION types or

  • … changes the sequence or signature of STRUCT/UNION members or members of the visible parts of a FUNCTION_BLOCK or FUNCTION like variables in the areas VAR_INPUT, VAR_OUTPUT and alike.

Container Libraries

Changing a container library results at least in an online change the next time you connect to the controller.
After changing a container library CODESYS must not report compiler errors or unresolved references.

  • Each change to a container library requires a change to the version number in relation to the last release. The version number receives a value that is greater than its value at the last release. In particular, the properties Title, Company, Filename or IsContainerLibrary in the project information must not differ in comparison between the current and the predecessor library. (See Test Specification: STL_I_03)

  • In container libraries, the set of library references in the current library must be a superset of the set of library references in the previous library. If library references are omitted during the transition from the previous library to the current library, this change is an incompatible change. (See Test Specification: STL_R_02)

Interface Libraries

An interface library is backwards compatible if CODESYS does not require an online change after updating the application with the newer library.

Each change to a interface library requires a change to the version number in relation to the last release. The version number receives a value that is greater than its value at the last release. In particular, the properties Title, Company, Filename or IsInterfaceLibrary in the project information must not differ in comparison between the current and the predecessor library. (See Test Specification: STL_I_03)

An interface library is not backwards compatible if the newer version…

  • … changes the signature or init value of constants,

  • … changes the signature of INTERFACE types (method, property),

  • … changes the signature or init value of ENUM members,

  • … changes the sequence or signature of STRUCT/UNION members,

  • … adds or removes a library reference to or from the library manager,

  • … changes the compiler version, or

  • adds data types or operators (for example, __XWORD, __UXINT, __XINT,…) which are not defined by the current compiler version setting of the library.

Structural Changes

Transforming the content of an already released library in a new structure is a special form of compatible evolving. The type of the library may be changing, but the layout of the data structures and the effects of the function blocks, methods and functions it contains must be kept unchanged.

There are two reasons for structural modifications of a library:

  1. Splitting a library in different sub libraries.

    Example: Splitting SysTime.library in a new version of SysTime.library and the new libraries SysTimeCore.library and SysTimeRTC.library

    • The container library (SysTime.library) contains only a library manager with two library (Placeholder) references.

      _images/SysTimeRtc.png

    • The Property LanguageModelAttribute (Text) := qualified-access-only may be set to hide all symbols behind the name-space.

    • The Property DefaultNamespace (Text) may be set to a appropriate value to provide the “old” name-space.

    • The Property IsContainerLibrary (Bool) := True must be set to identify this library as a container library.

  2. Separation between implementation and interface.

    Example: Separate SysTask.library in a new version of SysTask.library and the new libraries SysTaskImp.library (Placeholder) and SysTask_Itfs.library (Interface Library)

    • The container library (SysTask.library) contains only a library manager with two library (Placeholder) references. And these libraies publish their symbols into the name-space of the container library.

    • The property LanguageModelAttribute (Text) := qualified-access-only may be set to hide all symbols behind the name-space.

    • The property DefaultNamespace (Text) my be set to a appropriate value to provide the “old” name-space.

    • The property IsContainerLibrary (Bool) := True must be set to identify this library as a container library.

    The library SysTaskImp.library:

    • The property LanguageModelAttribute (Text) := qualified-access-only may be set to hide all symbols behind the name-space.

    • The property Placeholder must be set to identify this library as a common library.

    • The property DefaultNamespace (Text) my be set to a appropriate value to provide the “old” name-space.

    The library SysTask_Itfs.library:

    • The property LanguageModelAttribute (Text) := qualified-access-only may be set to hide all symbols behind the name-space.

    • The property IsInterfaceLibrary (Bool) := True must be set to identify this library as a interface library.

    • The property DefaultNamespace (Text) my be set to a appropriate value to provide the “old” name-space.

For the processes just described, there is a common element. A container library is always created whose “new” behaviour must correspond to the “old” behaviour of the previous library. This means that the container library publishes all previous available symbols under the previous name-space, so that the transition of an otherwise unchanged referencing library or application to the use of the new library reference is possible without problems.

In some cases, it may be useful to adopt the type of referencing from the “old” library to the “new” library. In these cases, the property IsCommonLibraryContainer is used instead of property IsContainerLibrary in the container library. The “new” library is then referenced by a placeholder.

The “new” container library should be able to replace always the last published “old” library without any troubles. The update assistant of CODESYS supports the transition from the “old” library to the use of the “new” library. It suggests to the user to replace the “old” library by the related “new” one.

Incompatible Evolution

If a currently existing library cannot be extended in a compatible way, but the desired changes seems sensible for a future use of the library, so then a new series of compatible libraries must be started. The name (title) is changed in the project information of the new library. This is best done in such a way that the user can see the relationship between the new library and its predecessor. This procedure ensures that old projects can continue to be operated with the old series of libraries without any problems. The old projects first have to be adapted if the new requirements also have to be met there. New projects must meet the new requirements and should therefore use the new series of libraries right from the start.

See: Precursor Property for creating a back link to the library which can not be further evolved in a compatible way.