CMake Details

• General
• Specifying generator and compiler
• Specifying the build type
• Specifying other options

General

CMake grabs information from environment variables, which means on Windows it should be run from a Visual Studio Command Prompt rather than a regular instance of cmd.

We only allow [out-of-source][out_of_source] builds for our projects, which means you need to create a separate build directory from which to run CMake. So, from somewhere outside of MaidSafe root:

cmake -H<path to MaidSafe root> -Bbuild_maidsafe

This is shortcut for doing:

mkdir build_maidsafe
cd build_maidsafe
cmake <path to MaidSafe root>

The first run of CMake is generally the longest since many of the variables are cached once set. Also, Boost may be downloaded and extracted as part of the configuration process. This is usually the slowest part of the configure step.

After the CMake command has finished, you should have a file 'build_maidsafe/CMakeCache.txt' containing these variables. This is used on future runs of CMake, and CMake can now be targeted either at the source root (where CMakeLists.txt lives), or at the build folder where the CMakeCache.txt lives. So, from within the build folder, you can now rerun CMake by simply doing:

cmake .

Specifying generator and compiler

CMake will choose a reasonable default for the generator. Once the generator and compilers have been set, they cannot be changed. If you need to use a different generator or compilers, you should clear your existing build folder or create a different one.

Specifying the generator is done with the -G command line flag. So, for example, on Windows the default is a 32-bit Visual Studio configuration. If you want to build a 64-bit version, you need to do:

cmake -H<path to MaidSafe root> -Bbuild_maidsafe -G"Visual Studio 12 Win64"

To see all the generators available on your platform, do:

cmake --help

To specify a different compiler, you can set the CMake variables CMAKE_C_COMPILER and CMAKE_CXX_COMPILER using the command line flag -D. Do not leave a space after the -D:

 cmake -H<path to MaidSafe root> -Bbuild_maidsafe -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++

Most other CMake variables can be changed by re-running CMake with the -DVAR=NewValue argument. This means we no longer have to keep specifying the -H, -B and -G args - the rest of the documentaion assumes this has already been done and CMake is being invoked from the build root (allowing us to use cmake .).

Specifying the build type

For multi-configuration generators like MSVC or Xcode, there is no need to specify the build type when running CMake. However, for all others you can specify the build type in the variable [CMAKE_BUILD_TYPE][cmake_build_type]:

cmake . -DCMAKE_BUILD_TYPE=Release

Its default value is Debug. Other interesting values include:

• Asan: Build with AddressSanitizer.
• Msan: Build with MemorySanitizer.
• Tsan: Build with ThreadSanitizer.

Specifying other options

The following options can likewise be set via the -DVAR=Value syntax. For example:

 cmake . -DHAVE_LIBC++=ON -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++ -DCMAKE_BUILD_TYPE=Debug

Any values which could contain a space (often paths on Windows) should be wrapped in "", e.g.

cmake . -DCBFS_ROOT_DIR="C:\Non standard path\cbfs"

Option and Possible Values (default value marked with *)	Description
-DGIT_ROOT_DIR="git/path"	Usually only needed if [Git][git] is installed to a non-standard location. Provide the path to the install directory of [Git][git].
-DCOVERAGE=OFF * -DCOVERAGE=ON	If ON, compiles and links the targets with coverage flags to allow gcov to present coverage data. (Not available on Windows).
-DPROFILING=OFF * -DPROFILING=ON	If ON, enables the SCOPED_PROFILE macro defined in [profiler.h][profiler]. Any function which includes SCOPED_PROFILE has profiling information gathered during execution and a summary is output when the program exits.
-DHAVE_LIBC++=OFF -DHAVE_LIBC++=ON	If ON, -stdlib=libc++ is added to the compile and link flags. This is ON by default for OSX, and OFF by default for others.
-DUSE_BOOST_CACHE=OFF * -DUSE_BOOST_CACHE=ON	If ON, boost is downloaded, extracted and built to a directory outside of the MaidSafe build tree. The chosen directory can be set in BOOST_CACHE_DIR, or if this is empty, an appropriate default is chosen for the given platform. This can be useful if you have different build trees for the same compiler (e.g. one for Debug and another for Release), or if you have different clones of the MaidSafe project, but want these all to use the same boost repo.
-DBOOST_CACHE_DIR="boost/cache/path"	See comment for USE_BOOST_CACHE above.
-DLOGGING=OFF -DLOGGING=ON	Enables or disables LOG messages in the C++ code. ON by default in Debug builds, otherwise OFF by default.
-DVLOGGING=OFF * -DVLOGGING=ON	If ON, enables Visualiser log messages - messages which are sent via HTTP to the visualiser server.
-DUSE_JUST_THREADS=OFF * -DUSE_JUST_THREADS=ON	If ON, CMake tries to find and use the [just::thread][just_thread] library (Windows or GCC only).
-DJUST_THREAD_ROOT_DIR="just/thread/path"	Usually only needed if [just::thread][just_thread] is installed to a non-standard location. Provide the path to the install directory of [just::thread][just_thread].
-DJUST_THREAD_DEADLOCK_CHECK=OFF * -DJUST_THREAD_DEADLOCK_CHECK=ON	If ON, enables the checked [just::thread][just_thread] library to assist in deadlock debugging.
-DMAIDSAFE_TEST_TYPE=ALL * -DMAIDSAFE_TEST_TYPE=BEH -DMAIDSAFE_TEST_TYPE=FUNC	All MaidSafe gtest cases are named with a leading BEH_ or FUNC_. Shorter tests (generally less than 10 seconds to complete) are prefixed BEH_. Setting the MAIDSAFE_TEST_TYPE enables just those tests with the corresponding name prefix.
-DCLEAN_TEMP=OFF * -DCLEAN_TEMP=ONCE -DCLEAN_TEMP=ALWAYS	Some tests write large volumes of data to the system temp folder. If the test crashes, it will be left undeleted. Setting to ALWAYS means that the temp folder is cleaned of MaidSafe test folders every time CMake is run. This is generally inadvisable since it could delete the test folder of a currently-running test, even from a completely different clone of MaidSafe. Setting to ONCE cleans just for that run of CMake then switches to the default OFF value.
-DADD_FUSE_INCLUDE_DIR="fuse/include/path"	Only applicable on OSX. Usually only needed if [FUSE][fuse] is installed to a non-standard location. Provide the path to the include directory of [FUSE][fuse].
-DADD_LIBRARY_DIR="fuse/lib/path"	Only applicable on Linux and OSX. Usually only needed if [FUSE][fuse] is installed to a non-standard location. Provide the path to the [FUSE][fuse] library (libfuse.so on Linux, libosxfuse_i64.dylib on OSX).
-DCBFS_ROOT_DIR="cbfs/path"	Only applicable on Windows. Usually only needed if Callback File System is installed to a non-standard location. Provide the path to the install directory of Callback File System.
-DCBFS_KEY=<Value of key> or -DCBFS_KEY="key/file/path"	Only applicable on Windows. This should be set to the value of the EldoS licence key, which must be provided to use CBFS. This is automatically set via cloning a private MaidSafe repo for MaidSafe's use only. To use a different key, you can either provide the value of the key or else the path to a file containing only the key's value.
-DDONT_USE_CBFS=FALSE * -DDONT_USE_CBFS=TRUE	Only applicable on Windows. By default, if CBFS is found then it is used. To disable this, set to TRUE.
-DNO_UBSAN=FALSE * -DNO_UBSAN=TRUE	By default, if your compiler provided the undefined behaviour sanitiser then it is used for all builds, debug and release. To disable this, set to TRUE.

[cmake_build_type]: http://www.cmake.org/cmake/help/v3.0/variable/CMAKE_BUILD_TYPE.html "CMake v3.0 documentation for "CMAKE_BUILD_TYPE" variable" [fuse]: http://fuse.sourceforge.net "Filesystem in Userspace" [git]: http://git-scm.com "git distributed version control system" [out_of_source]: http://www.cmake.org/Wiki/CMake_FAQ#Out-of-source_build_trees "CMake FAQ: Out-of-source build trees" [profiler]: https://github.com/maidsafe/MaidSafe-Common/blob/master/include/maidsafe/common/profiler.h "Header file, profiler.h" [just_thread]: http://www.stdthread.co.uk "just::thread C++ Standard Thread Library implementation by Anthony Williams"