Creating and using shared (consumable) libraries

Available from 2021.0 LTS

Creating a shared (consumable) library

Developing a library which can be consumed by other projects is a useful feature. A project with the type consumablelibrary can be created by means of the PLCnext CLI or one of the IDE tools provided by Phoenix Contact.

This creates a base project for cross-compiling and creating a shared library for PLCnext Technology devices. The directories are meant to be used as following:

The /src folder contains all implementations and internal header files.
The /include folder contains all public header files.
The /external folder can contains dependent shared libraries (see Using shared libaries in other projects below).

Note: For organisational purpose, it is useful to put the header files in a sub-directory which is named after the library.

As an example, there is a library called MyLib and an implementation class with the namespace MyLib::Sub::Namespace which is located in the src/Sub/Namespace directory. Here, the regarding header files should be put into the include/MyLib/Sub/Namespace directory.

Generate a new shared library:
```
$ plcncli new consumablelibrary
```
Program that library, keeping in mind to use the designated folders as described above
Set the targets to build and deploy the library, e.g.:
```
$ plcncli set target -a -n axcf2152 -v 2021.0
```
Call the build command:
```
$ plcncli build
```

The resulting files and directory structure can be found in the /bin folder.

Note: In this template, the plcncli generate all command is not used. The plcncli deploy command only allows the --files option to copy the output files to the destination directories.

Using shared (consumable) libraries in other projects

All project templates of the PLCnext CLI include an external folder. To use a shared library, copy the whole build output (content of the bin folder) to the external folder. Make sure that the build for your project targets are included.

After that, it is necessary to make these changes to the CMakeLists.txt: (with <library-name> being the name of the added shared library):

In the section add link targets, add an additional find_package(<library-name> REQUIRED) call for each shared library you want to add.
Add the found package to the target_link_libraries call by adding the <library-name> at the end of the call; e.g.:
```
target_link_libraries(MyProject PRIVATE ArpDevice ArpProgramming <library-name>)
```

To use the above mentioned class located in the MyLib::Sub::Namespace namespace, it is necessary to include the file in the header:

#include "MyLib/Sub/Namespace/ClassName.hpp"

To use it, it is necessary to use the namespace together with the type name:

MyLib::Sub::Namespace::ClassName myVariable;

Deploying shared (consumable) libraries with a project

When deploying a PLM project as a .pcwlx library the consumed library is automatically included in the .pcwlx file.

Also external libraries like .so files build from open source projects or downloaded from the internet can be used and included in the .pcwlx library. According to CMake standards, they need to be part of your project. The CMake server automatically identifies these libraries and automatically includes them into the .pcwlx file.

There are two exceptions:

If you use the --files option for the deploy command then only these external libraries are included.
If the library is located inside of the SDK in use, it is ignored.

For all other project types the library needs to be deployed manually:

Add the shared objects files of depending libraries into the usr/local/lib directory on the target.