Introduction

 

The SAMSON SDK (Software Development Kit) is a set of software development tools that help and allow the creation of new SAMSON Elements for the SAMSON software platform.

In addition to the provided SAMSON API (Application programming interfaces) which is a set of c++ headers and libraries, the SAMSON SDK also provides some helper executables to help developers design their SAMSON Elements. For example, there is a UUID Generator that generates random UUIDs, a SAMSON Element Generator that automatically generates compilable source code for new SAMSON Elements, and a SAMSON Element packager that wraps your SAMSON Elements into containers that are easy to upload and share on SAMSON Connect.

 

 

Requirements

 

A 64 bit Architecture with a 64 bit operating system (Windows 7, Windows 8, Windows 10, Ubuntu 14.04 or more*, Fedora 21 or more*, Mac OS 10.10.5 or more*)

* We have not tested the installation with previous versions.

SAMSON SDK 0.6.0 needs SAMSON 0.6.0 installed first.

SAMSON SDK needs Qt installed on your machine.

• Windows, SAMSON SDK 0.6.0 needs Qt5.8.0
  • Install Qt
  • Add YourQtPath\5.8.0\5.8\msvc2015_64\lib to the system “Path” environment variable.
• Linux, SAMSON SDK 0.6.0 needs Qt5.8.0
• Mac Os, SAMSON SDK 0.6.0 needs Qt5.7.1

 

SAMSON SDK 0.6.0 needs at least CMake 2.8.9, you can use your preferred version.

• Windows,  CMake link for SAMSON SDK 0.6.0, during the installation don’t forget to specify to add CMake to the Path environment variable
• Linux, CMake link for SAMSON SDK 0.6.0
• Mac Os, CMake link for SAMSON SDK 0.6.0

 

SAMSON SDK 0.6.0 needs an IDE (“Integrated Development Environment”) and a compatible compiler.

• Windows,  SAMSON SDK 0.6.0 needs Visual Studio 2015 Community or Professional
• Linux, SAMSON SDK 0.6.0 needs QtCreator (available when you install Qt) or whatever you prefers and gcc/g++ (at least 5.4 version)
• Mac Os, SAMSON SDK 0.6.0 needs XCode or QtCreator (available when you install Qt) with CLang compiler (available when you install XCode) .

 

Installation

 

To install the SAMSON SDK,

You need to be granted as developer, to do that you need to theses steps and send a developer request to us via samson-connect.net.

1. Go to samson-connect.net
2. Login to your account
3. Go to My SAMSON
4. Go to Develop Elements
5. Click on “Get the SDK”
6. if everithing works well you should see the notification
7. “Your request has been sent”
   and the button text should be “Request sent”

 

Once you are  granted as developer, you can access the developer of samson-connect.net

1. Go to samson-connect.net
2. Login to your account (you need to logout and login again to refresh samson-connect behaviour)
3. Go to Download
4. Go to SDK
5. Click on “Get the SDK”
6. Select were to save the installer and click Ok
7. a key will be sent to the email address you used for registration when downloading the SDK.

Once you have downloaded the SAMSON SDK and prepared your environment as indicated in the Requirements section, you can launch the installer.

• Windows
  • double-click on the executable file
  • follow the installation steps.
• Linux
  • Open a terminal
  • Go to the download folder
  • sudo chmod +x SAMSON-Developer-Setup.run
  • ./SAMSON-Developer-Setup.run (please do not use sudo here !)
  • follow the installation steps
• Mac Os
  • double-click on the executable file (you may have to accept some security “Apple menu > System Preferences, click Security & Privacy”)
  • follow the installation steps.

 

Once the SAMSON SDK installation is finished, there are some final things to do depending on the platform you are.

• Windows
  • Go to NANO-DPath/SDK/0.6.0/SAMSON-Debug/Binaries ( NANO-DPath = Home Directory\NANO-D or C:\Program Files\NANO-D )
  • Double click on SAMSON-Core.exe, SAMSON should works, if not please do not hesitate to contact us.
• Linux
  • Open a terminal
  • Go to ~/NANO-D/SDK/0.6.0/SAMSON-Debug/Binaries
  • execute the command : ls -la
  • SAMSON-Core.sh and SAMSON-Core should be executable, if it is not the case, execute this command : sudo chmod +x SAMSON-Core*
  • edit SAMSON-Core.sh
  • modify line 7 : export LD_LIBRARY_PATH=YourQtPath/5.8.0/5.8/gcc_64/lib:.:$LD_LIBRARY_PATH) and save the file
  • if you execute ./SAMSON-Core.sh SAMSON should works, if not please do not hesitate to contact us.

• Mac Os
  • Open a terminal
  • Go to ~/NANO-D/SDK/0.6.0/SAMSON-Debug/Binaries
  • execute the command : ls -la
  • SAMSON-Core.command and SAMSON-Core should be executable, if it is not the case, execute this command : sudo chmod +x SAMSON-Core*
  • edit SAMSON-Core.command
  • uncomment and verify line 14 : export DYLD_FRAMEWORK_PATH=YourQtPath/Qt5.7.1/5.7/clang_64/lib:$DYLD_FRAMEWORK_PATH
  • if you execute ./SAMSON-Core.command SAMSON should works, if not please do not hesitate to contact us.

 

At this step your SAMSON-Debug should work well.

We will now try to launch SAMSON Helpers to be sure that everything went well.

• Windows
  • Go to NANO-DPath/SDK/0.6.0/Helpers/Binaries ( NANO-DPath = Home Directory\NANO-D or C:\Program Files\NANO-D )
  • Try to launch ElementGenerator.exe, ElementPackager.exe, UUIDGenerator.exe, if any error messages appears, please do not hesitate to contact us.
• Linux
  • Open a terminal
  • Go to ~/NANO-D/SDK/0.6.0/Helpers/Binaries
  • Try to launch ElementGenerator.sh, ElementPackager.sh, UUIDGenerator.sh, if any error messages appears, please do not hesitate to contact us.
• Mac Os
  • Open a terminal
  • Go to ~/NANO-D/SDK/0.6.0/Helpers/Binaries
  • Try to launch ElementGenerator.app, ElementPackager.app, UUIDGenerator.app, if any error messages appears, please do not hesitate to contact us.

If everything went well from the beginning, you are ready to program your first SAMSON Element.

 

In order to setup correctly your development environment, we will generate an empty SAMSON element.

Start the Element Generator. The first page (seen below) lets you enter the name of your new SAMSON element and its description. The name will be included in the names of generated classes, and should not contain any white space (these are automatically removed for you). Precisely, if the name of your SAMSON element is MyElement, all generated files will begin with SEMyElement (SE stands for SAMSON element). Both a name and a description must be entered in order to be able to move to the next page. When you are done, click next.

The second page lets you enter the path to the folder where you develop SAMSON element. For your first SAMSON element, create an empty folder somewhere and indicate the path to it (hit the Browse button if necessary). In this example, we create a new folder called Elements at the root of the C:/ drive. This development folder may be distinct from the folder where SAMSON’s SDK is stored.

When you later create more SAMSON elements, you may reuse this folder again. For convenience, the path will be retained for the next time you run the Element Generator.

You may now add classes to your new SAMSON element thanks to the third page of the Element Generator (seen below).

Choose the type of a class you want to add to your SAMSON element from the combo box (seen below).

As in the figure below, give each class a distinct name. The name will be part of the corresponding generated files. For example, if you call a class VisualModel, generated files will include SEMyElementVisualModel in their names. Hit next to reach the generation page.

 

The generation page (below) is pretty simple to use, and only contains a Generate button.

 

Hit the Generate button, and voila, the Element Generator creates a compilable, workable SAMSON element that you may now complete.

You should now have, in the Elements folder you created earlier, two sub-folders (build and MyElement) and a CMakeLists.txt file. As the name indicates, the build folder is used to build your SAMSON Elements, while the MyElement folder contains the code generated by the Element Generator. The CMakeLists.txt file indicates to the CMake tool how to generate a project for your favorite development environment. When you later generate new SAMSON Elements, they will be added in sub-folders in the Elements folder, and the CMakeLists.txt file will be automatically modified to include these new SAMSON Elements in the development project.

Each generated SAMSON Element folder contains at least six sub-folders (some empty), and a CMakeLists.txt file indicating to CMake how to build the SAMSON Element:

• data: this folder is initially empty, but should be used to store data that should be distributed with the SAMSON Element (for example, a parameter file for an interaction model).
• doc: this folder is initially empty, and should contain html documentation about your SAMSON Element.
• form: this folder contains the Qt forms that help users interact with your SAMSON Element (for example, the GUI of an App).
• include: this folder contains the header files (*.hpp) of your SAMSON Element.
• resource: this folder contains various resources for your SAMSON Element (e.g. translation files and icons corresponding to your classes GUIs).
• source: this folder contains the source files (*.cpp) of your SAMSON Element.

Building your SAMSON Element on Windows

Once CMake is installed, generating a project for your development environment is straightforward. Assume for example that the SAMSON SDK is installed in SDK_PATH/0.6.0/ (i.e. this folder contains the cmake, Helpers, include and libs sub-folders),

• Open a command window from within the build folder (shift + right click on the desired folder)
• cmake -DSAMSON_SDK_PATH=”SDK_PATH/0.6.0/” -G”Visual Studio 14 Win64″ -DQT5_CMAKE_INCLUDE_DIR=”YourQtPath/5.8.0/5.8/msvc2015_64/lib/cmake” ..
• A .sln file should be generated you can open it.

This generates a project for your development environment. In this example for Visual Studio, cmake generates, among others, the Visual Studio solution file SAMSON-Elements.sln that you can now open in Visual Studio. The Solution Explorer of Visual Studio 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 a whitespace somewhere): 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, 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.

Testing your SAMSON Element

Finally, build the INSTALL target (either in Debug or Release configurations) to install your new SAMSON Element, and start SAMSON. 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.

Building the INSTALL target will automatically compile as well if necessary, so that it is often preferable to include this target when building the complete solution. In Visual Studio, this is done by ticking the build checkbox corresponding to the INSTALL target in the properties of the SAMSON-Elements solution, as seen below, for both the Debug and Release configurations:

For the Debug configuration, indicate the path to the SAMSON-Core executable located in the Binaries/Debug folder, and for the Release configuration, use the version of SAMSON-Core located in the Binaries folder.

You may now indicate to Visual Studio that SEMyElement is the StartUp project (right click on SEMyElement in the Solution Explorer, Select as StartUp project). When you start your project, with or without debugging (see the Debug menu), Visual Studio will start SAMSON.

 

Building your SAMSON Element on Mac Os using Xcode

Once CMake is installed, generating a project for your development environment is straightforward. Assume for example that the SAMSON SDK is installed in SDK_PATH/0.6.0/ (i.e. this folder contains the cmake, Helpers, include and libs sub-folders),

• Open a terminal from within the build folder
• cmake -DSAMSON_SDK_PATH=”SDK_PATH/0.6.0/” -G”Xcode” -DQT5_CMAKE_INCLUDE_DIR=”YourQtPath/5.7.1/5.7/clang_64/lib/cmake” -G”Xcode” ..
• A .xcodeproj file should be generated you can open it.

This generates a project for your development environment. In this example for Xcode, cmake generates, among others, the xcodeproj file SAMSON-Elements 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 a whitespace somewhere): 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, 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.

 

 

Testing your SAMSON Element

Finally, build the INSTALL target (either in Debug or Release configurations) to install your new SAMSON Element, and start SAMSON. 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.

Building the INSTALL target will automatically compile as well if necessary, so that it is often preferable to include this target when building the complete solution. This is done by ticking the build checkbox corresponding to the INSTALL target in the properties of the SAMSON-Elements solution, as seen below, for both the Debug and Release configurations:

 

 

Note that you should start the SAMSON configuration that corresponds to the configuration used to build your SAMSON Elements. 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 in a Binaries/Debug folder where SAMSON is installed. It is this version that should be started when testing or debugging SAMSON Elements compiled in the Debug configuration.

We need to setup some environment variable to let SAMSON search for frameworks or libraries to the corect location. For that DYLD_LIBRARY_PATH and DYLD_FRAMEWORK_PATH should be filled with absolute paths coresponding to SAMSON debug libraries (/installPath/SDK/0.6.0/SAMSON-Debug/Binaries) and the other with the location of Qt frameworks (/installPath/Qt5.7.1/5.7/clang_64/lib/)

For the Debug configuration, indicate the path to the SAMSON-Core executable located in the Binaries/Debug folder, and for the Release configuration, use the version of SAMSON-Core located in the Binaries folder.

Now when you build the tardet install SAMSON will start to debug your element.

When SAMSON is started you can see your empty editor

You can debug it step by step and also add breakpoints.

You can debug it step by step and inspect variables values.

 

 

Building your SAMSON Element on Linux using QtCreator

Once CMake is installed, generating a project for your development environment is straightforward. Assume for example that the SAMSON SDK is installed in SDK_PATH/0.6.0/ (i.e. this folder contains the cmake, Helpers, include and libs sub-folders),

Open Qt Creator and click on Open Project.

 

Choose the root CMakeList.txt of your new generated element.

 

Choose the build location

Qt Creator ask you for a Cmake arguments command.

-DSAMSON_SDK_PATH=”SDK_PATH/0.6.0/”  -DQT5_CMAKE_INCLUDE_DIR=”YourQtPath/5.8.0/5.8/gcc_64/lib/cmake” -DDEBUG=TRUE ..

Click on run CMake

 

This generates a project for your development environment. In this example for QtCreator 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 a whitespace somewhere): 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, 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.

If your element does not compile, you may have to install theses packages

• compat-libstdc++-33.x86_64
• libstdc++-devel.x86_64
• libstdc++-static.x86_64

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.

 

Testing your SAMSON Element

Finally, build the INSTALL target (either in Debug or Release configurations) to install your new SAMSON Element, and start SAMSON. 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.

Building the INSTALL target will automatically compile as well if necessary, so that it is often preferable to include this target when building the complete solution. This is done by ticking the build checkbox corresponding to the INSTALL target in the properties of the SAMSON-Elements solution, as seen below, for both the Debug and Release configurations:

Note that on Linux you should create 2 differents project to get both release and debug configuration. The steps are the same except -DDEBUG=FALSE/TRUE to get release or debug configuration.

We need to setup some environment variable to let SAMSON search for frameworks or libraries to the corect location. For that LD_LIBRARY_PATH should be filled with absolute paths coresponding to SAMSON debug libraries (/installPath/SDK/0.6.0/SAMSON-Debug/Binaries) and the location of Qt frameworks (/installPath/Qt5.8.0/5.8/gcc_64/lib/)

For the Debug configuration, indicate the path to the SAMSON-Core executable located in the Binaries/Debug folder, and for the Release configuration, use the version of SAMSON-Core located in the Binaries folder.

Now when you build the tardet install SAMSON will start to debug your element.

When SAMSON is started you can see your empty editor

 

You can debug it step by step and also add breakpoints.

 

You can debug it step by step and inspect variables values.