Compilation

First of all, you should have the CMake utility installed on your system to generate build files:

• CMake (Cross-platform Make, http://www.cmake.org/) is an open-source build system.

"CMake is used to control the software compilation process using simple platform
and compiler independent configuration files. CMake generates native makefiles
and workspaces that can be used in the compiler environment of your choice."

Compilation using MS Visual Studio

Starting from the version 3.1.2, Microsoft Visual Studio 2015 and 2017 are supported.

Get all necessary 3rd party libraries by downloading the ZIP file with from here:

• Latest version 4.1.x – 3rdParty_v4.1.1_VC14_x64_all.zip
• Older version 3.1.x – 3rdParty_v3.1.3_VC14_x64-all.zip

Unzip the file somewhere on your disk. It contains the file MapThisFolderToDriveX.bat which needs to be launched. As the name suggests, it creates drive X: from that folder which enables CMake scripts to find everything in one place at that location.

Alternatively, you can build all the libraries on your own. In that case, we recommend you to build at least OpenSceneGraph, Qt and VPL. For a complete list of required 3rd party libraries take a look at 3rdParty.txt.

Currently only VS2015 ×64 libs are used for both the VS2015 and VS2017 as they are binary compatible. If you are using VS2017 you will need to specify the older toolset (v140) when configuring:

If you have the X drive mapped and CMake installed you’re good to go. Just point the Source code and Binary paths to desired locations and press Configure.

Configuring for the first will select the newest libraries available for linking.

Note: I recommend using the Grouped option ON and Advanced option OFF for the best experience.

If you wish to change project to build or some of its options you will find them under BUILD group.
If you wish to change used libraries you will find them under LIBRARY group.

<ins>No changes should be necessary.</ins> Just select the project you will be working on (i.e. Viewer) in the drop down menu under BUILD_PROJECT_NAME variable, hit Configure, Generate and open the solution 3Dim_PROJECT_NAME.sln which will be placed in the build directory and try to compile the project.

Final executable will be placed directly in the build folder under _[project name\]/bin/[configuration]

Further notes

Some additional information about the available options and features:

• If you have Advanced OFF, under LIBRARY group will be shown only the libraries, that are actually used by the project. Turning Advanced ON will show all of them.

• Most of the BUILD options have tooltip to better explain their function.

• Important : After you change something, you will need to Configure again, for these changes to take effect. Configuring creates cache, which is used by Generate, to produce the solution. If there is need to clear the cache, it can be done under File->Delete cache in the top menu.

• In the generated solution is install target, that copies all the needed dlls and resources into a folder with built executable and it is run automatically as post build step. This means, you can
  run or debug the project without worrying about what makes the program crash at startup and how to fix it.

• This install can be forced to run every time you try to run the program from VS by enabling RUN_INSTALL_AS_POST_BUILD_EVERYTIME, and disabled by turning RUN_INSTALL_AS_POST_BUILD OFF.

• Under INFO group there are listed paths to lib and include folders as well as list of present library files. These have only informational/debug role and can be ignored.

• If different version of some library is desired, it can be selected under LIBRARY_[Name]. The highest version is selected by default.

• If there is experimental keyword used in the name of the library folder in the X location (for example like this: “OSG 4.0.9 experimental”), it will be excluded from default selection,
  unless there is no non-experimental library. This is useful for libraries, that you want to test and not break other people’s builds unwittingly, if you distribute that library.

• Alternatively you can place own version of library alongside provided libraries and it should be available for selection after Configuring again.
  • Make sure the internal folder structure of that library and naming system of debug versions of files are the same as in the other versions of that lib.
  • Also the names of the library folders must match others to be detected as the same. The names are case sensitive.

• The mapping to drive X is lost every time the computer is restarted, so it is often useful to create a shortcut to it and place it into a windows startup folder located on W10 at “C:/Users/username/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup”.