Please, refer to the updated version: Developer guide: Building a SAMSON Element on Windows.
This tutorial shows how to build SAMSON Elements on Windows using Microsoft Visual Studio (MS VS).
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.
- Configuration of a project in QtCreator
- Adding files to your SAMSON Element
- Building step
- Running SAMSON from Microsoft Visual Studio
If you have not installed SAMSON SDK, please, follow instructions from Installing the SAMSON SDK.
- CMake v.2.8.9+
- Qt5.9.3, add the path to Qt dll libraries into the system Path environment variable
- Microsoft Visual Studio 2015
- QtCreator (should be available when you install Qt) is necessary if you want to modify Qt forms.
Configuration of a project in Microsoft Visual Studio
Once CMake is installed, generating a project for your development environment is straightforward. In this tutorial, we show how to configure a project for SAMSON Element in Microsoft Visual Studio (MS VS) 2015+ using CMake for the generation of VS project and solution from the command line. Microsoft Visual Studio 2017 has introduced a built-in support for handling CMake projects – you can create a CMake project with taking into account the information provided below.
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).
- Go to the folder where your SAMSON Element is stored. Open a command window from within the build folder (Shift + right click on the build folder and choose Open PowerShell window here in the context menu), if there is no such folder, create it.
- Execute the following command for the version of Visual Studio you have:
for Visual Studio 2015:
cmake -DSAMSON_SDK_PATH="YourSDKPath/SDK/0.7.0/" -G"Visual Studio 14 Win64" -DQT5_CMAKE_INCLUDE_DIR="YourQtPath/Qt/5.9.3/msvc2015_64/lib/cmake" ..
for Visual Studio 2017:
cmake -DSAMSON_SDK_PATH="YourSDKPath/SDK/0.7.0/" -G"Visual Studio 15 Win64" -DQT5_CMAKE_INCLUDE_DIR="YourQtPath/Qt/5.9.3/msvc2017_64/lib/cmake" ..
- A Microsoft Visual Studio Solution .sln file should be generated in the build folder.
This should generate 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 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 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 (e.g. SEMyElement) or if 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 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 that, open Properties of the solution (right click on the Solution ‘SAMSON-Elements’ and choose Properties in the context menu); for both Debug and Release configurations, in Configuration Properties → Configuration tick the build checkbox corresponding to the INSTALL target. Building the INSTALL target will automatically compile the code if necessary.
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.
Running SAMSON from Microsoft Visual Studio
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 Visual Studio know which version of SAMSON to start, open the Properties of the SEMyElement target and enter the path to the SAMSON-Core executable for both Release and Debug configurations in Configuration Properties → Debugging → Command:
- For Debug configuration indicate the path to the SAMSON-Core executable from the SAMSON SDK installation (e.g. “C:\Program Files\NANO-D\SDK\0.7.0\SAMSON-Debug\Binaries\SAMSON-Core.exe”).
- For Release configuration indicate the path to the SAMSON-Core executable from SAMSON installation (e.g. “C:\Program Files\NANO-D\SAMSON\0.7.0\Binaries\SAMSON-Core.exe”).
You may now indicate to Visual Studio that SEMyElement is the StartUp project: right click on SEMyElement in the Solution Explorer, select Set as StartUp Project in the context menu. When you start your project, with or without debugging (see the Debug menu), Visual Studio will start SAMSON.
Now you can build the solution (menu Build → Build solution or F7 or Ctrl+Shift+B) which will build all the projects including INSTALL, and then run the StartUp project (F5).
If you have any questions or feedback, please use the SAMSON forum.