CMake and Visual Studio

CMake produces Visual Studio solutions seamlessly. This post will map CMake commands to the Visual Studio IDE with an example which makes learning much easier. It is primarily intended for a C++ developer using Visual Studio. Most references here is based on Visual Studio 2010 but will apply equally well to other versions. Continuing from the preface CMake for Visual Studio Developers.

Out of source builds
Visual Studio to CMake Mapping
Example
    Source Structure
    Execute CMake
    Visual Studio Solution Explorer View
    Build and Debug
    Install and Run
    Test
    CMakeLists.txt Details
CMake pre-defined projects
Debug and Release Configurations
Conclusion

Out of source builds

Typically source should be considered as any files that are explicitly modified by the developer. Anything that is or can be consistently generated from the source files should be considered as output of the build process. A build will always generate a lot of temporary/intermediate files and to avoid polluting the actual source, it is recommended to have out of source builds.

Other than the typical intermediate files like .obj, Visual Studio produces many more transient files like .sbr, .suo, .vcxproj.filters, .db etc. These need not (and should not) be checked into the source repository as sometimes they are large and user specific.

A Visual Studio developer might consider the project file (.vcxproj) and the solution file (.sln) as a “source” since it involves adding/removing source files, modifying library dependencies, setting build dependencies etc. However, with CMake you can consider this to be an intermediate file too, as CMake will generate it and is recommended for it to be outside the source directory.

To clean or reset your build environment, you would simply delete the out of source build directory.

Visual Studio to CMake Mapping

In a CMake build system, the build “rules” or “project settings” are defined in text files called CMakeLists.txt.
Some common Visual Studio project operations and settings and its mapping to CMake is listed below as an overview.

Visual Studio	CMake Command
Solution file (.sln)	project
Project file (.vcproj)	target name in the command add_executable or add_library
executable (.exe)	add_executable
static library (.lib)	add_library
dynamic library (.dll)	add_library(SHARED)
Source Folders	source_group
Project Folders	set_property(TARGET PROPERTY FOLDER)
Properties->General->Output Directory	set_target_properties(PROPERTIES RUNTIME_OUTPUT_DIRECTORY)
Properties->C/C++->Preprocessor->Preprocessor Definitions	add_definitions
Properties->C/C++->General->Additional Include Directories	include_directories
Properties->Linker->General->Additional Library Directories	link_directories
Properties->Linker->Input->Additional Dependencies	target_link_libraries

Example

The tutorial from CMake is a very simple example. Please refer to it if you are not familiar with the basics. Here, it has been enhanced to show specific aspects commonly used on Windows.
 
The example code can be accessed via GitHub at https://github.com/cognitivewaves/CMake-VisualStudio-Example. For those not familiar with Git, GitHub has an option to download it as a zip file.

Source Structure

CMake-VisualStudio-Example
   |-- app
   |   |-- CMakeLists.txt
   |   |-- main.cxx
   |-- math
   |   |-- advanced
   |   |   |-- AdvancedFunctions.cxx
   |   |   |-- AdvancedFunctions.h
   |   |-- simple
   |   |   |-- SimpleFunctions.cxx
   |   |   |-- SimpleFunctions.h
   |   |-- CMakeLists.txt
   |   |-- MathExports.h
   |-- CMakeLists.txt
   |-- TutorialConfig.h.in

Execute CMake

As recommended earlier, for an out of source build, create a directory where CMake will produce the required Visual Studio Project files and a lot of CMake specific files.

D:\tmp\CMake-VisualStudio-Example> mkdir _build

Make the build directory the current working directory.

D:\tmp\CMake-VisualStudio-Example> cd _build

Run the CMake command and specify where to find the first(root) CMakeLists.txt. In this case ".." is used to indicate one directory up from the current working directory. The -G option specifies it to generate a Visual Studio 2010 Win64 project files.

D:\tmp\CMake-VisualStudio-Example\_build> cmake .. -G "Visual Studio 10 Win64"

Note that other Visual Studio (e.g. VS 2012, VS 2013, VS 2015) generators can be specified. Use cmake --help to see the full list.

Visual Studio 11 2012 = Generates Visual Studio 11 (VS 2012) project files
Visual Studio 12 2013 = Generates Visual Studio 12 (VS 2013) project files
Visual Studio 14 2015 = Generates Visual Studio 14 (VS 2015) project files

The Visual Studio solution file will be created in the _build directory.

Visual Studio Solution Explorer View

Open the solution file in Visual Studio.

Build and Debug

Build the solution in Visual Studio. By default, the output binary files (app.exe, math.dll) from the build are created under their own sub-directories in the _build directory. But you can set the RUNTIME_OUTPUT_DIRECTORY property to specify an output directory in Visual Studio. This will ensure that the executable can be launched from the debugger and will find all the dependent libraries.

⚠ Note that project ALL_BUILD is the default “Startup Project”. This is never the case for debugging. So right click on the executable project (app in this case) and select as “Startup Project” from the context menu.
CMake 3.6.3 has added a property VS_STARTUP_PROJECT to specify a startup project.

⚠ Since this example takes a command line argument, to run/debug it from Visual Studio, the properties on the executable project (app) must be set.
Set Properties->Debugging->Command Arguments to 200

Install and Run

Install is a concept which comes from Linux (make install) and not very common in a Windows development environment. Basically, the build process will generate many artifacts but only a subset may be necessary for deployment. This is where install comes into play. The INSTALL project copies the binaries to the specified installation directory. So build INSTALL.vcproj explicitly, as it does not get built as part of the solution.

The executable can now be run in a command window from the installation directory.

D:\tmp\CMake-VisualStudio-Example\_install> app.exe 200
The sum of 200 and 200 is 400
The square root of 200 is 14.1421

Test

Invoking CTest from the build directory will run the tests. Alternatively, the tests can be run within the Visual Studio environment by right click “Build” on the RUN_TESTS project and the test run report will be displayed in the output window.

D:\tmp\CMake-VisualStudio-Example\_build>ctest
Test project D:/tmp/CMake-VisualStudio-Example/_build
    Start 1: AppTest1
1/3 Test #1: AppTest1 .........................   Passed    0.00 sec
    Start 2: AppTest2
2/3 Test #2: AppTest2 .........................   Passed    0.00 sec
    Start 3: AppTest3
3/3 Test #3: AppTest3 .........................   Passed    0.00 sec

100% tests passed, 0 tests failed out of 3

Total Test time (real) =   0.03 sec

CMakeLists.txt Details

The comments in each line provides more details about each CMake command.

File: CMake-VisualStudio-Example/CMakelist.txt

cmake_minimum_required (VERSION 2.6)

# Maps to Visual Studio solution file (Tutorial.sln)
# The solution will have all targets (exe, lib, dll) 
# as Visual Studio projects (.vcproj)
project (Tutorial)

# Turn on the ability to create folders to organize projects (.vcproj)
# It creates "CMakePredefinedTargets" folder by default and adds CMake
# defined projects like INSTALL.vcproj and ZERO_CHECK.vcproj
set_property(GLOBAL PROPERTY USE_FOLDERS ON)

# Set compiler flags and options. 
# Here it is setting the Visual Studio warning level to 4
set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /W4")

# Command to output information to the console
# Useful for displaying errors, warnings, and debugging
message ("cxx Flags:" ${CMAKE_CXX_FLAGS})

# Sub-directories where more CMakeLists.txt exist
add_subdirectory(app)
add_subdirectory (math)

# Turn on CMake testing capabilities
enable_testing()

# Add test cases
add_test(AppTest1 ${PROJECT_BINARY_DIR}/bin/app 100)
add_test(AppTest2 ${PROJECT_BINARY_DIR}/bin/app 200)
add_test(AppTest3 ${PROJECT_BINARY_DIR}/bin/app 300)

File: CMake-VisualStudio-Example/math/CMakeLists.txt

# Collect sources into the variable MATH_SOURCES without
# having to explicitly list each header and source file.
#
# CMake documentation states "We do not recommend using GLOB to collect a
# list of source files from your source tree. If no CMakeLists.txt file
# changes when a source is added or removed then the generated build system
# cannot know when to ask CMake to regenerate".
file (GLOB MATH_SOURCES
      "*.h")

# Collect sources into the variable SIMPLE_FUNCTION_SOURCES
file (GLOB SIMPLE_FUNCTION_SOURCES
      "simple/*.h"
      "simple/*.cxx")

# The recommended way to collect sources in variable 
# ADVANCED_FUNCTION_SOURCES by explicitly specifying the source files
set  (ADVANCED_FUNCTION_SOURCES
      "advanced/AdvancedFunctions.h"
      "advanced/AdvancedFunctions.cxx")

# Create named folders for the sources within the .vcproj
# Empty name lists them directly under the .vcproj
source_group("" FILES ${MATH_SOURCES})
source_group("simple" FILES ${SIMPLE_FUNCTION_SOURCES})
source_group("advanced" FILES ${ADVANCED_FUNCTION_SOURCES})

# Properties->C/C++->General->Additional Include Directories
include_directories (.)

# Set Properties->General->Configuration Type to Dynamic Library(.dll)
# Creates math.dll with the listed sources collected in the variables
# Also adds sources to the Solution Explorer
add_library(math SHARED ${MATH_SOURCES} 
                        ${SIMPLE_FUNCTION_SOURCES} 
                        ${ADVANCED_FUNCTION_SOURCES})

# Creates folder "libraries" and adds target project (math.vcproj)
set_property(TARGET math PROPERTY FOLDER "libraries")

# Properties->General->Output Directory
set_target_properties(math PROPERTIES
                      RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/bin)

# Adds logic to INSTALL.vcproj to copy math.dll to the destination directory
install (TARGETS math
         RUNTIME DESTINATION ${PROJECT_SOURCE_DIR}/_install
         LIBRARY DESTINATION ${PROJECT_SOURCE_DIR}/_install)

File: CMake-VisualStudio-Example/app/CMakeLists.txt

# Properties->C/C++->General->Additional Include Directories
include_directories ("${PROJECT_SOURCE_DIR}/Math")

# Set Properties->General->Configuration Type to Application(.exe)
# Creates app.exe with the listed sources (main.cxx)
# Adds sources to the Solution Explorer
add_executable (app main.cxx)

# Properties->Linker->Input->Additional Dependencies
target_link_libraries (app math)

# Creates a folder "executables" and adds target 
# project (app.vcproj) under it
set_property(TARGET app PROPERTY FOLDER "executables")

# Properties->General->Output Directory
set_target_properties(app PROPERTIES
                      RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/bin)

# Adds logic to INSTALL.vcproj to copy app.exe to destination directory
install (TARGETS app
         RUNTIME DESTINATION ${PROJECT_SOURCE_DIR}/_install)

CMake pre-defined projects

To add some CMake functionality to the Visual Studio environment, it creates a few project files which can be ignored for the most part. In any case, a brief description is given below.

INSTALL	CMake install specification. It is simulating the Linux make install so it has to be manually built after the full build.
RUN_TESTS	CMake test specification. This project will enable running tests in Visual Studio and the test run report will be shown in the output window
ZERO_CHECK	Used to make sure that the project files are up-to-date with respect to the CMakeLists.txt files
ALL_BUILD	Builds all projects with its dependency order

Debug and Release Configurations

Visual Studio supports multiple configurations in a single project file and creates a per-configuration directory. CMake generates four configurations by default: Debug, Release, MinSizeRel and RelWithDebInfo.

See CMake FAQ: How can I specify my own configurations (for generators that allow it)? for changing the default.

Conclusion

CMake is a better build system than Visual Studio projects and solutions. It is compact and much more easier to maintain even for Windows only projects. See CMake for Visual Studio Developers for some reasons.

Microsoft now claims direct CMake support in Visual Studio, but a cursory look at it seems more like an obfuscation of the CMake philosophy to make you dependent on Microsoft.

Hope the the document is useful. Feel free to comment if you need any clarifications or further information.

---