Referencing other Libraries

Rule #4:

Use the right way for referencing other Libraries (Required)

Common Libraries: Placeholder Reference
Interface Libraries: Newest Constraint
Container Libraries: Absolute Reference

In the world of CODESYS libraries there is a main basic principle: “There can be only one!”

This famous quotation from the Highlander Saga wants to be understood as follows: In the memory of a controller at a definite time there should be used a definite version of a definite library. In exceptional cases it might be well to be able to use more than one version of a library (in such a case however with different namespaces), but usually it won’t. It is a great strength of CODESYS, that new libraries can be created easily by reusing existing libraries. By consequently using this possibility in CODESYS, deeply nested library hierarchies may result. However for those the same base principle must apply: If possible, at a definite time there should be just one definite version of a library in the controller’s memory. Besides the saving of memory space this will ensure that all overlaid libraries are using the same code via the same interfaces with the same data types.

In the course of time, for the different library types certain methods have arised for maintaining the network of dependencies between the libraries with a minimum effort.

Asterisk References (“Newest-Constraint”)

This method requires no definite version of the library to be referenced. Automatically the latest version available in the library repository will be used for compilation. This is a very effective way of referencing, however also has some drawbacks. Always when a new version of a certain library gets installed in the library repository, all projects and libraries referencing this library with the “newest” constraint, will get changed. Usually this is not the desired behaviour.

Absolute References

This method of referencing requires to exactly define within a library, which version of another library should be used. CODESYS itself gets no chance to modify the defined relationships. This very rigorous way of referencing however harbours a high maintenance effort. Always when an underlaid library gets changed, then the reference of the respective overlaid libraries must be adapted. Due to the fact that the modification of the reference forces a change of the library version, this process is necessary over all layers up to the root of the library hierarchy.

Placeholder Reference

The advantages of the absolute references are clear. They result in exactly defined relationships among the libraries. The disadvantage however is the high adaptation effort in case an underlaid library changes. By introducing so-called placeholders this disadvantage could be eliminated. Now there is a location outside of the respective library, where an exact reference of another library can be specified: The placeholder definition. There the relevant properties of a library reference (Name, Company and Version) can be assigned to a placeholder name. So in the particular library another library can be referenced merely by its placeholder. If this underlaid library changes, “only” the placeholder definition will have to be adapted accordingly, not however each library using this placeholder. The references of all libraries, which each reference the other library, will get changed automatically.

For a more detailed explanation about placeholders have a look at Placeholder.

However, if references again might change also unintentionally, what is the benefit compared to using the Asterisk References?

There are various places for the definition of placeholders. Depending on the definition place and the CODESYS component, the resolution of the placeholders to definite library versions will be treated differently.

The Device Description:

Here the resolution of the placeholders is done according to a certain firmware version of the controller.
The Library Profile:

Here the resolution of the placeholders is done according to a certain CODESYS compiler version.
In each Application inside the project of the end user:

Here in case of emergency the placeholder resolution of any placeholder can be overwritten manually.

In addition, the so-called “unbound” placeholders can be managed. These placeholders are neither defined in the device description still in the library profile. They are used to reference libraries having no dependencies on the compiler version and no dependency to the firmware version.

With this measurements you are able to control very exactly, in which context the relationships of certain library families should be treated. Only by re-setting certain CODESYS parameters automatically the appropriate placeholder groups will be switched.

Updating to a new firmware might also entail a group of new libraries implemented in the runtime system. Changing to a new version of the device description will switch all placeholders defined therein.
After having switched to a new compiler version, it makes sense to use the new possibilities in new library versions. Switching to another compiler version will switch all placeholders found in the library profile.
The optimization of the library of a third party vendor requires an update of the respective library and thus an update of the concerned placeholder. Switching to a new library means switching the related placeholder assigned to this library.
In order to be able to work around an error in a sublaid library, which might be recognized at very short notice, there must be the possibility to switch to another version of this library directly on-site. Overwriting of a placeholder in the project will change the usage of the concerned libraries within the entire project, that means also in the sublaid libraries.

Placeholder references, in contrast to the asterisk references, get not changed merely by the - often accidentally done - installation of a newer library version. Placeholder references get only changed by a deliberate switching to newer versions of certain CODESYS components (device description, compiler, package, project)