This tutorial shows how to build a SAMSON Element on Linux using QtCreator. For other IDE, please, check the Main steps to configure a project for your SAMSON Element.
This tutorial was done with QtCreator v.4.4.1 and Qt 5.9.3.
If you have not installed the SAMSON SDK, please, follow the instructions from the Installation of SDK section.
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 Qt5.9.3 folder), SAMSON is installed in YourSAMSONPath/SAMSON/0.8.1 (i.e. the folder which contains the Binaries folder), and the SAMSON SDK is installed in YourSDKPath/SDK/0.8.1/ (i.e. the folder which contains the following sub-folders: cmake, include, libs, SAMSON-Debug).
Open QtCreator and click on Open Project.
Choose the root CMakeList.txt of your newly generated SAMSON Element (CMakeList.txt from the parent folder to your SAMSON Element, not the CMakeList.txt that is inside of your SAMSON Element 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:
SAMSON_SDK_PATH
and set its value to the SAMSON SDK path: YourSDKPath/0.8.1/DEBUG
and set its value to TRUE (ON)
for the Debug build and to FALSE (OFF)
for the Release build. If not present, provide a string variable named CMAKE_BUILD_TYPE
and set its value to Debug for the Debug build or to Release for the Release build.QT5_CMAKE_INCLUDE_DIR
and set its value to the Qt cmake path: YourQtPath/Qt5.9.3/5.9.3/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:
You can add files to (or remove files from) your new SAMSON Element (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.
Once your project is created, you can now browse your SAMSON Element files and edit your code. The project contains one target for your SAMSON Element (SEMyElement), as well as some cmake-specific targets. When you generate new SAMSON Elements with theSAMSON Element 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 Elements and you want to compile them all at once, by building the build all target.
Note: If your SAMSON Element does not compile, you may have to install libstdc++ packages dev and static for 64-bit architecture.
Note that SAMSON Elements 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 Element, and when uploading it to SAMSON Connect.
To be able to use your SAMSON Element, 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 Element (building the install target will automatically build your project). If the build was successful your SAMSON Element 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 Element will be loaded alongside with the SAMSON Elements you added from SAMSON Connect, as well as other SAMSON Elements you developed.
Note that a SAMSON Element compiled in Release mode will be available only when launching the SAMSON-Core executable provided with SAMSON installation, while a SAMSON Element 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 Elements 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):
YourSDKPath/SDK/0.8.1/SAMSON-Debug/Binaries/SAMSON-Core
YourSAMSONPath/SAMSON/0.8.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:
YourQtPath/Qt5.9.3/5.9.3/gcc_64/lib:YourSDKPath/SDK/0.8.1/SAMSON-Debug/Binaries
YourSAMSONPath/SAMSON/0.8.1/Binaries/SAMSONQtLibs/:YourSAMSONPath/SAMSON/0.8.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 Element, add breakpoints and inspect variables values.
Here we list the main steps for configuration of a SAMSON Element 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 Qt5.9.3 folder), SAMSON is installed in YourSAMSONPath/SAMSON/0.8.1 (i.e. the folder which contains the Binaries folder), and the SAMSON SDK is installed in YourSDKPath/SDK/0.8.1/ (i.e. the folder which contains the following sub-folders: cmake, include, libs, SAMSON-Debug).
You can configure a project either in a terminal or in IDE of your choice.
Check which cmake generators are available on your platform:
You can configure a project by going to the folder where your SAMSON Element 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 QT5_CMAKE_INCLUDE_DIR
during the SAMSON SDK Intallation procedure, you will need either to add the QT5_CMAKE_INCLUDE_DIR
environment variable or specify it in the previous cmake command by adding -DQT5_CMAKE_INCLUDE_DIR
:
You can open a project in the IDE of your choice by choosing the root CMakeList.txt of your newly generated SAMSON Element (CMakeList.txt from the parent folder to your SAMSON Element, not the CMakeList.txt that is inside of your SAMSON Element folder). Configure Release and Debug builds by provoding the following variables:
SAMSON_SDK_PATH
and set its value to the SAMSON SDK path: YourSDKPath/SDK/0.8.1/DEBUG
and set its value to TRUE (ON)
for the Debug build and to FALSE (OFF)
for the Release build. If not present, provide a string variable named CMAKE_BUILD_TYPE
and set its value to Debug for the Debug build or to Release for the Release build.QT5_CMAKE_INCLUDE_DIR
and set its value to the Qt cmake path: YourQtPath/Qt5.9.3/5.9.3/gcc_64/lib/cmake
For both Release and Debug builds, set the install target so that after a successful compilation your SAMSON Element would be installed in a special SAMSON directory to make it available in your SAMSON installation.
To be able to run SAMSON from your IDE, specify the following SAMSON-Core executables (not the SAMSON-Core.sh file) in run configurations:
YourSDKPath/SDK/0.8.1/SAMSON-Debug/Binaries/SAMSON-Core
YourSAMSONPath/SAMSON/0.8.1/Binaries/SAMSON-Core
Note that a SAMSON Element compiled in Release mode will be available only when launching the SAMSON-Core executable provided with the SAMSON installation, while a SAMSON Element 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:
YourQtPath/Qt5.9.3/5.9.3/gcc_64/lib:YourSDKPath/SDK/0.8.1/SAMSON-Debug/Binaries
YourSAMSONPath/SAMSON/0.8.1/Binaries/SAMSONQtLibs/:YourSAMSONPath/SAMSON/0.8.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
.