Building a SAMSON Element on Mac OS


Please, refer to the updated version: Developer guide: Building a SAMSON Element on Mac OS.

This tutorial shows how to build SAMSON Elements on Mac OS using XCode. If you want to use QtCreator as the main IDE for developing SAMSON Elements you can follow the same steps and check the tutorial Building SAMSON Element on Linux.

The tutorial applies for SAMSON version 0.7.0 and higher. For an older version, please, check SAMSON School 2017: Introduction and installation of the SAMSON SDK.

If you experience any problems with building your SAMSON Element, please let us know on SAMSON-Connect forum.


  1. Requirements
  2. Configuration of a project in XCode
  3. Adding files to your SAMSON Element
  4. Building step
  5. Running SAMSON from XCode


If you have not installed SAMSON SDK, please, follow instructions from Installing the SAMSON SDK.

  • Compiler Clang (available when you install XCode)
  • CMake v.2.8.9+
  • Qt5.9.3
  • XCode; QtCreator (should be available when you install Qt) if you want to modify Qt forms.

Configuration of a project in XCode

Once CMake is installed, generating a project for your development environment is straightforward.

Assume that Qt is installed in YourQtPath (i.e. the folder which contains the Qt5.9.3 folder) and the SAMSON SDK is installed in YourSDKPath/SDK/0.7.0/ (i.e. the folder which contains the following sub-folders: cmake, include, libs, SAMSON-Debug).

  • Open a terminal, go to the folder where your SAMSON Element is stored, open the build folder (if there is no such folder, create it).
  • Execute the following command in the terminal: cmake -DSAMSON_SDK_PATH="YourSDKPath/SDK/0.7.0/" -G"Xcode" -DQT5_CMAKE_INCLUDE_DIR="YourQtPath/5.9.3/5.9.3/clang_64/lib/cmake" ..

  • A XCode project .xcodeproj file should be generated.

This should generate a project for your development environment. In this example for Xcode, cmake generates, among others, the xcodeproj file SAMSON-Elements-release that you can now open in Xcode. The Solution Explorer of XCode should show the structure below:

Adding files to your SAMSON Element

You may need to 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 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 whitespace somewhere) and save it: when building the project (see the next section), CMake will detect the change and update the project.

Building step

Once your project is opened, 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 the 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 (SEMyElement) or when your solution contains several SAMSON Elements and you want to compile them all at once, by building the ALL_BUILD target.

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 switch between Debug and Release builds, click on the Edit scheme (see image below) and in the Run tab set the Build configuration to Debug or Release.

Click on Edit scheme

Select Debug or Release mode

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. Choose and build the install target (either in Debug or Release 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.

Choose install target

Running SAMSON from XCode

Note that you should start the SAMSON configuration that corresponds to the configuration used to build your SAMSON Elements: 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 XCode know which version of SAMSON to start, open Edit scheme and enter the path to the SAMSON-Core executable (not SAMSON-Core.command file) for both Release and Debug build configurations:

  • For Debug configuration indicate the SAMSON-Core executable from the SAMSON SDK installation and tick the Debug executable checkbox.
  • For Release configuration indicate the SAMSON-Core executable from SAMSON installation and untick the Debug executable checkbox.

Set the SAMSON-Core executable

We need to setup some environment variables to let SAMSON search for frameworks or libraries to the corect location. In the Arguments tab add the following environment variables :

  • DYLD_LIBRARY_PATH filled with absolute path coresponding to SAMSON debug libraries: YourSDKPath/SDK/0.7.0/SAMSON-Debug/Binaries
  • DYLD_FRAMEWORK_PATH filled with absolute path coresponding to the location of Qt frameworks: YourQtPath/Qt5.9.3/5.9.3/clang_64/lib/.

You may also add some command-line arguments into Arguments Passed On Launch, like: –logconsole –disablenetwork –import –logfile “file” –logdefaultfile.

Set environment variables

Now when you build the install target SAMSON will start.

You can debug your code in Debug mode, add breakpoints and inspect variables values.

If you have any questions or feedback, please use the SAMSON forum.


Comments are closed.