This tutorial shows how to build a SAMSON Extension on Linux using QtCreator. For other IDE, please, check the Main steps to configure a project for your SAMSON Extension.
This tutorial was done with QtCreator.
Requirements
If you have not installed the SAMSON SDK, please, follow the instructions from the Installation of SDK section.
- Compiler gcc/g++ v.5.4+
- CMake v.3.10+
- Qt6.5.2 (download Qt: https://www.qt.io/download)
- QtCreator (should be available when you install Qt) or another IDE you prefer. QtCreator is necessary if you want to modify Qt forms.
Configuration of a project in QtCreator
If you have CMake installed QtCreator should generate a kit for it. Else, if QtCreator did not detect CMake we refer to Qt tutorial on Setting Up CMake for setting up CMake in QtCreator.
Once CMake is installed, generating a project for your development environment is straightforward.
Let's assume that Qt is installed in YourQtPath (i.e. the folder which contains the Qt6.5.2 folder), SAMSON is installed in YourSAMSONPath/SAMSON-Application/5.0.1 (i.e. the folder which contains the Binaries folder), and the SAMSON SDK is installed in YourSDKPath/SAMSON-Sdks/5.0.1/ (i.e. the folder which contains the following sub-folders: cmake, include, libs, SAMSON-Debug).
Note: By default, SAMSON and its SDK are installed into /home/USERNAME/OneAngstrom/.
Open QtCreator and click on Open Project.
Choose the root CMakeList.txt of your newly generated SAMSON Extension (CMakeList.txt from the parent folder to your SAMSON Extension, not the CMakeList.txt that is inside of your SAMSON Extension folder)
Choose the Build&Run kit (if necessary, you can configure your kits in Options > Build&Run > Kits), set build folders for Debug and Release builds, and press the Configure Project button.
You may see some errors in the Issues window. This is because it is necessary to specify some other CMake arguments for both Debug and Release builds. To do so, switch to the Projects mode ( Ctrl + 5 ). And specify the following variables for both Debug and Release builds:
- Add a string variable named
SAMSON_SDK_PATHand set its value to the SAMSON SDK path:YourSDKPath/SAMSON-Sdks/5.0.1/(by default,/home/USERNAME/OneAngstrom/SAMSON-Sdks/5.0.1/). - Provide a boolean variable named
DEBUGand set its value toTRUE (ON)for the Debug build and toFALSE (OFF)for the Release build. If not present, provide a string variable namedCMAKE_BUILD_TYPEand set its value to Debug for the Debug build or to Release for the Release build. - [Optional] If Qt 6.5.2 was not properly identified by the IDE you use, you will need to specify a path to the Qt cmake folder. For that, add a string variable named
QT_CMAKE_INCLUDE_DIRand set its value to the Qt cmake path:YourQtPath/Qt/6.5.2/gcc_64/lib/cmake
Once you specified the variables for the build, press Apply Configuration Changes and you should see a set of settings variables defined by cmake like on the image below.
This generates a project for your development environment. In the Edit mode ( Ctrl + 2 ) you should see a structure like on the image below:
Adding files to a SAMSON Extension
You can add files to (or remove files from) your new SAMSON Extension (e.g. to add or remove classes, to wrap existing code, etc.). When you do so, you should run cmake again (or let your IDE to run it) to regenerate a project for your development environment. One simple way to do this without having to open a command window is to slightly alter the CMakeLists.txt file located in the SEMyElement (e.g. add and remove a whitespace somewhere) and save it: when building the project (see the next section), CMake will detect the changes and update the project.
Building step
Once your project is created, you can now browse your SAMSON Extension files and edit your code. The project contains one target for your SAMSON Extension (SEMyElement), as well as some cmake-specific targets. When you generate new SAMSON Extensions with theSAMSON Extension generator in the same folder, cmake will re-generate the project files and will add new targets as needed.
You may now check that your code compiles by either building the target corresponding to it (e.g. SEMyElement) or if your solution contains several SAMSON Extensions and you want to compile them all at once, by building the build all target.
Note: If your SAMSON Extension does not compile, you may have to install libstdc++ packages dev and static for 64-bit architecture.
Note that SAMSON Extensions may be built in both Debug and Release configurations. The Debug configuration is the one you should use to develop and debug your code, while the Release configuration is the one you should use when testing the performance of your SAMSON Extension, and when uploading it to SAMSON Connect.
To be able to use your SAMSON Extension, it should be installed in a specific SAMSON directory to make it available in your SAMSON installation.
For making it possible, switch to Projects mode ( Ctrl + 5 ) and in the Build Settings for each build configuration (Release and Debug) set in Build Steps target to install as it is shown in the image below.
Now you can build the install target (either in Release or Debug configurations) to install your new SAMSON Extension (building the install target will automatically build your project). If the build was successful your SAMSON Extension should be available when you launch SAMSON (for Release configuration - SAMSON-Core from SAMSON installation, for Debug configuration - SAMSON-Core from the SAMSON SDK installation). During startup, your SAMSON Extension will be loaded alongside with the SAMSON Extensions you added from SAMSON Connect, as well as other SAMSON Extensions you developed.
Running SAMSON
Note that a SAMSON Extension compiled in Release mode will be available only when launching the SAMSON-Core executable provided with SAMSON installation, while a SAMSON Extension compiled in Debug mode will be available only when launching the SAMSON-Core executable provided with SAMSON SDK installation. SAMSON Users only get the Release configuration, since this is the optimized one. The SAMSON SDK installer, though, adds a Debug version of the SAMSON-Core executable. It is this version that should be started when testing or debugging SAMSON Extensions compiled in the Debug configuration.
In order to let QtCreator know which version of SAMSON to start, enter the path to the SAMSON-Core executable for each build configuration. For that switch to Projects mode ( Ctrl + 5 ) and in the Run Settings create two run configurations (one for Release and one for Debug) and specify the following SAMSON-Core executables (not the SAMSON-Core.sh files):
- for the Debug run configuration:
YourSDKPath/SAMSON-Sdks/5.0.1/SAMSON-Debug/Binaries/SAMSON-Core - for the Release run configuration:
YourSAMSONPath/SAMSON-Application/5.0.1/Binaries/SAMSON-Core
You may also add some command line arguments, like: –logconsole –disablenetwork –import –logfile "file" –logdefaultfile
We need to setup some environment variables to let SAMSON search for frameworks or libraries to the correct location. For that, for each run configuration (Release and Debug) in the Run Environment section of the project settings add a variable named LD_LIBRARY_PATH and fill it with the following absolute paths:
- for the Debug run configuration: paths corresponding to the location of Qt framework and SAMSON debug libraries:
YourQtPath/Qt/6.5.2/gcc_64/lib:YourSDKPath/SAMSON-Sdks/5.0.1/SAMSON-Debug/Binaries - for the Release run configuration:
YourSAMSONPath/SAMSON-Application/5.0.1/Binaries/SAMSONQtLibs/:YourSAMSONPath/SAMSON-Application/5.0.1/Binaries/
Also, for both Release and Debug run configurations, add a variable named LC_ALL and set its value to en_US.UTF-8.
Now when you build the install target ( Ctrl + B ) and run ( Ctrl + R ) SAMSON will be launched from QtCreator.
If you choose Debug build and Debug run you can debug your SAMSON Extension, add breakpoints and inspect variables values.
Main steps to configure a project for your SAMSON Extension
Here we list the main steps for configuration of a SAMSON Extension project. Application of these steps in QtCreator is described in the section Configuration of a project in QtCreator.
Let's assume that Qt is installed in YourQtPath (i.e. the folder which contains the Qt6.5.2 folder), SAMSON is installed in YourSAMSONPath/SAMSON-Application/5.0.1 (i.e. the folder which contains the Binaries folder), and the SAMSON SDK is installed in YourSDKPath/SAMSON-Sdks/5.0.1/ (i.e. the folder which contains the following sub-folders: cmake, include, libs, SAMSON-Debug).
Note: By default, SAMSON and its SDK are installed into /home/USERNAME/OneAngstrom/.
Step 1: Configure a project to build a SAMSON Extension
You can configure a project either in a terminal or in IDE of your choice.
Configuring a project in the terminal
Check which cmake generators are available on your platform:
You can configure a project by going to the folder where your SAMSON Extension is stored, opening the build folder (if there is no such folder, create it) and executing the following command in terminal (let's assume that you have the "CodeLite - Unix Makefiles" generator available, you can specify a different one):
Note: If you have not specified the QT_CMAKE_INCLUDE_DIR during the SAMSON SDK Installation procedure, you will need either to add the QT_CMAKE_INCLUDE_DIR environment variable or specify it in the previous cmake command by adding -DQT_CMAKE_INCLUDE_DIR:
Configuring a project in IDE
You can open a project in the IDE of your choice by choosing the root CMakeList.txt of your newly generated SAMSON Extension (CMakeList.txt from the parent folder to your SAMSON Extension, not the CMakeList.txt that is inside of your SAMSON Extension folder). Configure Release and Debug builds by providing the following variables:
- Provide a string variable named
SAMSON_SDK_PATHand set its value to the SAMSON SDK path: YourSDKPath/SAMSON-Sdks/5.0.1/ (by default,/home/USERNAME/OneAngstrom/SAMSON-Sdks/5.0.1/). - Provide a boolean variable named
DEBUGand set its value toTRUE (ON)for the Debug build and toFALSE (OFF)for the Release build. If not present, provide a string variable namedCMAKE_BUILD_TYPEand set its value to Debug for the Debug build or to Release for the Release build. - [Optional] If Qt 6.5.2 was not properly identified by the IDE you use, you will need to specify a path to the Qt cmake folder. For that, add a string variable named
QT_CMAKE_INCLUDE_DIRand set its value to the Qt cmake path:YourQtPath/Qt/6.5.2/gcc_64/lib/cmake
Step 2: Configure a project to install a SAMSON Extension
For both Release and Debug builds, set the install target so that after a successful compilation your SAMSON Extension would be installed in a special SAMSON directory to make it available in your SAMSON installation.
Step 3: Configure a project to run SAMSON
To be able to run SAMSON from your IDE, specify the following SAMSON-Core executables (not the SAMSON-Core.sh file) in run configurations:
- for the Debug run configuration:
YourSDKPath/SAMSON-Sdks/5.0.1/SAMSON-Debug/Binaries/SAMSON-Core - for the Release run configuration:
YourSAMSONPath/SAMSON-Application/5.0.1/Binaries/SAMSON-Core
Note that a SAMSON Extension compiled in Release mode will be available only when launching the SAMSON-Core executable provided with the SAMSON installation, while a SAMSON Extension compiled in Debug mode will be available only when launching the SAMSON-Core executable provided with the SAMSON SDK installation.
You will need to specify some environment variables to let SAMSON search for frameworks or libraries to the correct location. For that, for each run configuration (Release and Debug) in the Run Environment section of the project settings add a variable named LD_LIBRARY_PATH and fill it with the following absolute paths:
- for the Debug run configuration: paths corresponding to the location of Qt framework and SAMSON debug libraries:
YourQtPath/Qt/6.5.2/gcc_64/lib:YourSDKPath/SAMSON-Sdks/5.0.1/SAMSON-Debug/Binaries - for the Release run configuration:
YourSAMSONPath/SAMSON-Application/5.0.1/Binaries/SAMSONQtLibs/:YourSAMSONPath/SAMSON-Application/5.0.1/Binaries/
Also, for both Release and Debug run configurations, add a variable named LC_ALL and set its value to en_US.UTF-8.
Compatibility with older Linux distributions
SAMSON supports Linux distributions with GLIBC 2.17 or higher. You can check the GLIBC version on your system via, for example, the following command in the terminal:
To make your SAMSON Extension able to run on older Linux distributions with GLIBC versions starting from 2.17 (released in December 2012), SAMSON SDK provides a header file (SBCSystemDefinitions.hpp) which defines GLIBC compatibility symbols that forces linking against symbols from a GLIBC version not higher than 2.17. This allows you to compile your SAMSON Extension on a recent Linux distribution while still supporting older distributions. This header is already included in some base classes so you do not need to include it - it will be included automatically. If you use an external library or external source code you might need to include this header in them:
It is necessary only if in your SAMSON Extension you are using GLIBC functionality which has been updated in recent versions (starting from the version 2.17), e.g. functions pow, exp, log for single precision floating-point numbers (float).
You can check which functionality from GLIBC your SAMSON Extension is using by executing the following command in the terminal against your SAMSON Extension library .so file:
where UUID.so is the SAMSON Extension library. This will show you the list of GLIBC functions used in your SAMSON Extension and their version number.
When it is useful: Let's say that you build your SAMSON Extension on a recent Fedora or Ubuntu distribution which has GLIBC 2.27 or higher. If, for example, in your SAMSON Extension you are using pow, exp, or log functions for single precision floating-point numbers (float) (these functions were updated in GLIBC 2.27), then on older Linux distributions which have GLIBC older than 2.27 your SAMSON Extension will not be loaded in SAMSON because of the lack of GLIBC 2.27. The above-mentioned header allows to overcome this and support older GLIBC versions (starting from 2.17) even when building a SAMSON Extension using a newer GLIBC version.