This tutorial shows how to build a SAMSON Element on Windows using Microsoft Visual Studio (MS VS).
Requirements
If you have not installed the SAMSON SDK, please, follow the instructions from the Installation of SDK section.
- 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, or higher
- 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 will show how to configure a project for a SAMSON Element in Microsoft Visual Studio (MS VS) 2015+ using CMake for 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.
Let's 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.8.3/ (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 build folder, create it.
In the PowerShell, execute the following command for the version of Visual Studio you have:
- for Visual Studio 2015: cmake -DSAMSON_SDK_PATH="YourQtPath/SDK/0.8.3/" -G"Visual Studio 14 Win64" ..
- for Visual Studio 2017: cmake -DSAMSON_SDK_PATH="YourQtPath/SDK/0.8.3/" -G"Visual Studio 15 Win64" ..
The -G designates the cmake generator, to check the available ones execute cmake -h in the terminal.
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 (the path is specific to the Visual Studio version you are using) or specify it in the previous cmake command by adding -DQT5_CMAKE_INCLUDE_DIR:
- for Visual Studio 2015: cmake -DSAMSON_SDK_PATH="YourSDKPath/SDK/0.8.3/" -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.8.3/" -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 that you can open in the Visual Studio. The Solution Explorer of Visual Studio should show the structure below:
Adding files to a SAMSON Element
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.
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 SAMSON 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 be able to use yourSAMSON 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 Element you added from SAMSON Connect, as well as other SAMSON Elements you developed.
Running SAMSON
Note that a SAMSON Element compiled in the Release mode will be available only when launching the SAMSON-Core executable provided with SAMSON installation, while a SAMSON Element compiled in the 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 the Debug configuration indicate the path to the SAMSON-Core executable from the SAMSON SDK installation, e.g.:
C:\Program Files\NANO-D\SDK\0.8.3\SAMSON-Debug\Binaries\SAMSON-Core.exe - for the Release configuration indicate the path to the SAMSON-Core executable from SAMSON installation, e.g.:
C:\Program Files\NANO-D\SAMSON\0.8.3\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).