This tutorial shows how to build a SAMSON Extension on Mac OS using XCode. If you want to use QtCreator as the main IDE for developing a SAMSON Extension you can follow the same steps from the Building on Linux tutorial.
Requirements
If you have not installed the SAMSON SDK, please, follow the instructions from the Installation of SDK section.
- Compiler Clang (available when you install XCode)
- CMake v.3.10+
- Qt6.5.2 (download Qt: https://www.qt.io/download)
- XCode, QtCreator (should be available when you install Qt) or another IDE you prefer. QtCreator is necessary if you want to modify Qt forms.
If you would like to use QtCreator on Mac, please refer to Building on Linux.
Configuration of a project in XCode
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) 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).
We will configure a project in the terminal. Go to the folder where your SAMSON Extension is stored, open the build folder (if there is no such folder, create it) and execute the following command in terminal:
The -G designates the cmake generator, to check the available ones execute cmake -h in the terminal.
Note: If you have not specified the QT_CMAKE_INCLUDE_DIR during the SAMSON SDK Intallation 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:
This should generate a XCode project .xcodeproj 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 a project structure similar to the one shown 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 opened, 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 the SAMSON 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 (SEMyElement) or when your solution contains several SAMSON Extensions and you want to compile them all at once, by building the ALL_BUILD target.
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 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.
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. Choose and build the install target (either in Debug or Release 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 you should start the SAMSON configuration that corresponds to the configuration used to build your SAMSON Extension:
- a SAMSON Extension compiled in Release mode will be available only when launching the SAMSON-Core executable provided with SAMSON installation;
- 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 XCode know which version of SAMSON to start, open Edit scheme and enter the path to the SAMSON-Core executable (not the SAMSON-Core.command file) for both Release and Debug build configurations:
- for the Debug configuration indicate the SAMSON-Core executable from the SAMSON SDK installation and tick the Debug executable checkbox.
- for the Release configuration indicate the SAMSON-Core executable from the SAMSON installation and untick the Debug executable checkbox.
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_PATHfilled with absolute path coresponding to SAMSON debug libraries:YourSDKPath/SAMSON-Sdks/5.0.1/SAMSON-Debug/BinariesDYLD_FRAMEWORK_PATHfilled with absolute path coresponding to the location of Qt frameworks:YourQtPath/Qt/6.5.2/clang_64/lib/.
You may also add some command line arguments into Arguments Passed On Launch, like: –logconsole –disablenetwork –import –logfile “file” –logdefaultfile.
Now when you build the install target SAMSON will start.
Debugging a SAMSON Extension
You can debug your code in the Debug mode, add breakpoints, inspect variables, etc.
