mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-02 20:00:38 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Populate tutorial guide text

Browse Source 
Migrate tutorial text from individual `directions.txt` files to the main
tutorial document.  Add some comments to source code to provide anchors
for inclusion.
This commit is contained in:
Betsy McPhail
2019-06-18 10:49:40 -04:00
committed by Brad King
parent 862cfc0e6c
commit eef3e020c2
44 changed files with 777 additions and 939 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
Help/guide/tutorial/Complete/CMakeLists.txt
View File

@@ -1,20 +1,20 @@
cmake_minimum_required(VERSION 3.3)
project(Tutorial)
set(CMAKE_CXX_STANDARD 14)
# set the version number
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)
# control where the static and shared libraries are built so that on windows
# we don't need to tinker with the path to run the executable
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_CXX_STANDARD 14)
option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
# the version number.
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)
if(APPLE)
set(CMAKE_INSTALL_RPATH "@executable_path/../lib")
elseif(UNIX)

2
Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
View File

@@ -1,4 +1,3 @@
# add the library that runs
add_library(MathFunctions MathFunctions.cxx)
@@ -62,6 +61,7 @@ target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
# install rules
install(TARGETS MathFunctions
DESTINATION lib
EXPORT MathFunctionsTargets)

6
Help/guide/tutorial/Consumer/directions.txt
View File

@@ -1,6 +0,0 @@
# Import a CMake Project#
This examples shows how a project can find other CMake packages that
generated Config.cmake files.
It also shows how to state a projects external dependencies when generating a Config.cmake.

34
Help/guide/tutorial/MultiPackage/directions.txt
View File

@@ -1,34 +0,0 @@
# Packaging Debug and Release #
By default CMake is model is that a build directory only contains a single
configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo.
But it is possible to setup CPack to bundle multiple build directories at the same
time to build a package that contains multiple configurations of the same project.
First we need to ahead and construct a directory called 'multi_config' this
will contain all the builds that we want to package together.
Second create a 'debug' and 'release' directory underneath 'multi_config'. At
the end you should have a layout that looks like:
─ multi_config
├── debug
└── release
Now we need to setup debug and release builds, which would roughly entail
the following:
cd debug
cmake -DCMAKE_BUILD_TYPE=Debug ../../MultiPackage/
cmake --build .
cd ../release
cmake -DCMAKE_BUILD_TYPE=Release ../../MultiPackage/
cmake --build .
cd ..
Now that both the debug and release builds are complete we can now use
the custom MultiCPackConfig to package both builds into a single release.
cpack --config ../../MultiPackage/MultiCPackConfig.cmake

16
Help/guide/tutorial/Readme.txt
View File

@@ -1,16 +0,0 @@
Step 0: A Starting Point
Step 1: Configure a File and C++11 Controls
Step 2: Adding a Library
Step 3: Usage Requirements for Library
Step 4: Installing and Testing
Step 5: System Introspection
Step 6: Custom Command and Generated File
Step 7: Building an Installer
Step 8: CDash submission
Step 9: Mixing Static and Shared
Step 10: Generator Expressions
Step 11: Adding Export Configuration
Complete: End result of Step 11
Consumer: Example of Import Packages
MultiPackage: How to package Debug and Release versions

95
Help/guide/tutorial/Step1/directions.txt
View File

@@ -1,95 +0,0 @@
# Adding a Version Number and Configured Header File #
The first feature we will add is to provide our executable and project with a
version number. While we could do this exclusively in the source code, using
CMakeLists provides more flexibility.
To add a version number we modify the CMakeLists file as follows:
cmake_minimum_required(VERSION 3.3)
project(Tutorial)
# the version number.
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)
# configure a header file to pass some of the CMake settings
# to the source code
configure_file(
"${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
"${PROJECT_BINARY_DIR}/TutorialConfig.h"
)
# add the executable
add_executable(Tutorial tutorial.cxx)
# add the binary tree to the search path for include files
# so that we will find TutorialConfig.h
target_include_directories(Tutorial PUBLIC
"${PROJECT_BINARY_DIR}"
)
We then create a TutorialConfig.h.in file in the source tree with the
following contents:
// the configured options and settings for Tutorial
#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
When CMake configures this header file the values for @Tutorial_VERSION_MAJOR@
and @Tutorial_VERSION_MINOR@ will be replaced by the values from the CMakeLists
file. Next we modify tutorial.cxx to include the configured header file and to
make use of the version numbers. The resulting source code is listed below.
// A simple program that computes the square root of a number
#include <cmath>
#include <iostream>
#include <string>
#include <sstream>
#include "TutorialConfig.h"
int main (int argc, char *argv[])
{
if (argc < 2) {
std::cout << argv[0] << " Version "
<< Tutorial_VERSION_MAJOR << "." << Tutorial_VERSION_MINOR
<< std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
return 1;
}
double inputValue = atof(argv[1]);
double outputValue = sqrt(inputValue);
std::cout << "The square root of "
<< inputValue << " is " << outputValue << std::endl;
return 0;
}
# Adding C++11 support #
Let's add some C++11 features to our project. We will need to explicitly state
in the CMake code that it should use the correct flags. The easiest way to
enable C++11 support for CMake is by using the CMAKE_CXX_STANDARD
and CMAKE_CXX_STANDARD_REQUIRED variables.
First, replace `atof` with `std::stod` in tutorial.cxx.
Then, add the CMAKE_CXX_STANDARD and CMAKE_CXX_STANDARD_REQUIRED variables to
the CMakeLists file. The STANADARD value should be set to 11, and REQUIRED
should be set to True.
# Build and Test #
Run cmake or cmake-gui to configure the project and then build it with your
chosen build tool
cd to the directory where Tutorial was built (likely the make directory or
a Debug or Release build configuration subdirectory) and run these commands:
Tutorial 4294967296
Tutorial 10
Tutorial

12
Help/guide/tutorial/Step10/CMakeLists.txt
View File

@@ -1,20 +1,20 @@
cmake_minimum_required(VERSION 3.3)
project(Tutorial)
set(CMAKE_CXX_STANDARD 14)
# Set the version number
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)
# control where the static and shared libraries are built so that on windows
# we don't need to tinker with the path to run the executable
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_CXX_STANDARD 14)
option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
# the version number.
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)
# configure a header file to pass the version number only
configure_file(
"${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"

2
Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt
View File

@@ -1,4 +1,3 @@
# add the library that runs
add_library(MathFunctions MathFunctions.cxx)
@@ -57,5 +56,6 @@ endif()
# building on windows
target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
# install rules
install(TARGETS MathFunctions DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)

38
Help/guide/tutorial/Step10/directions.txt
View File

@@ -1,38 +0,0 @@
# Adding Generator Expressions #
Generator expressions are evaluated during build system generation to produce
information specific to each build configuration.
Generator expressions are allowed in the context of many target properties, such
as LINK_LIBRARIES, INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and others. They may
also be used when using commands to populate those properties, such as
target_link_libraries(), target_include_directories(),
target_compile_definitions() and others.
Generator expressions may to used to enable conditional linking, conditional
definitions used when compiling, and conditional include directories and more.
The conditions may be based on the build configuration, target properties,
platform information or any other queryable information.
There are different types of generator expressions including Logical,
Informational, and Output expressions.
Logical expressions are used to create conditional output. The basic expressions
are the 0 and 1 expressions. A "$<0:...>" results in the empty string, and
"$<1:...>" results in the content of "...". They can also be nested.
For example:
if(HAVE_LOG AND HAVE_EXP)
target_compile_definitions(SqrtLibrary
PRIVATE "HAVE_LOG" "HAVE_EXP")
endif()
Can be rewritten with generator expressions:
target_compile_definitions(SqrtLibrary PRIVATE
"$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>"
"$<$<BOOL:${HAVE_EXP}>:HAVE_EXP>"
)
Note that "${HAVE_LOG}" is evaluated at CMake configure time while
"$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>" is evaluated at build system generation time.

1
Help/guide/tutorial/Step10/tutorial.cxx
View File

@@ -9,6 +9,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;

12
Help/guide/tutorial/Step11/CMakeLists.txt
View File

@@ -1,20 +1,20 @@
cmake_minimum_required(VERSION 3.3)
project(Tutorial)
set(CMAKE_CXX_STANDARD 14)
# set the version number
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)
# control where the static and shared libraries are built so that on windows
# we don't need to tinker with the path to run the executable
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_CXX_STANDARD 14)
option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
# the version number.
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)
# configure a header file to pass the version number only
configure_file(
"${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"

2
Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt
View File

@@ -1,4 +1,3 @@
# add the library that runs
add_library(MathFunctions MathFunctions.cxx)
@@ -56,5 +55,6 @@ target_compile_definitions(MathFunctions PRIVATE "$<$<BOOL:${USE_MYMATH}>:USE_MY
#building on windows
target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
# install rules
install(TARGETS MathFunctions DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)

104
Help/guide/tutorial/Step11/directions.txt
View File

@@ -1,104 +0,0 @@
# Adding Export Configuration #
During Step 4 of the tutorial we added the ability for CMake to install the
library and headers of the project. During Step 7 we added the ability
to package up this information so it could be distributed to other people.
The next step is to add the necessary information so that other CMake projects
can use our project, be it from a build directory, a local install or when
packaged.
The first step is to update our install(TARGETS) commands to not only specify
a DESTINATION but also an EXPORT. The EXPORT keyword generates and installs a
CMake file containing code to import all targets listed in the install command
from the installation tree. So let's go ahead and explicitly EXPORT the
MathFunctions library by updating the install command in
MathFunctions/CMakeLists.txt to look like:
install(TARGETS MathFunctions DESTINATION lib EXPORT MathFunctionsTargets)
Now that we have MathFunctions being exported, we also need to explicitly install
the generated MathFunctionsTargets.cmake file. This is done by adding
the following to the bottom of the top-level CMakeLists.txt:
# install the configuration targets
install(EXPORT MathFunctionsTargets
FILE MathFunctionsTargets.cmake
DESTINATION lib/cmake/MathFunctions
)
At this point you should try and run CMake. If everything is setup properly
you will see that CMake will generate an error that looks like:
Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains
path:
"/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions"
which is prefixed in the source directory.
What CMake is trying to say is that during generating the export information
it will export a path that is intrinsically tied to the current machine and
will not be valid on other machines. The solution to this is to update the
MathFunctions target_include_directories to understand that it needs different
INTERFACE locations when being used from within the build directory and from an
install / package. This means converting the target_include_directories
call for MathFunctions to look like:
target_include_directories(MathFunctions
INTERFACE
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
$<INSTALL_INTERFACE:include>
)
Once this has been updated, we can re-run CMake and see verify that it doesn't
warn anymore.
At this point, we have CMake properly packaging the target information that is
required but we will still need to generate a MathFunctionsConfig.cmake, so
that the CMake find_package command can find our project. So let's go ahead and
add a new file to the top-level of the project called Config.cmake.in with the
following contents:
@PACKAGE_INIT@
include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" )
Then, to properly configure and install that file, add the following to the
bottom of the top-level CMakeLists:
include(CMakePackageConfigHelpers)
# generate the config file that is includes the exports
configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
"${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
INSTALL_DESTINATION "lib/cmake/example"
NO_SET_AND_CHECK_MACRO
NO_CHECK_REQUIRED_COMPONENTS_MACRO
)
# generate the version file for the config file
write_basic_package_version_file(
"${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}"
COMPATIBILITY AnyNewerVersion
)
# install the configuration file
install(FILES
${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake
DESTINATION lib/cmake/MathFunctions
)
At this point, we have generated a relocatable CMake Configuration for our project
that can be used after the project has been installed or packaged. If we want
our project to also be used from a build directory we only have to add
the following to the bottom of the top level CMakeLists:
# generate the export targets for the build tree
# needs to be after the install(TARGETS ) command
export(EXPORT MathFunctionsTargets
FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake"
)
With this export call we now generate a Targets.cmake, allowing the configured
MathFunctionsConfig.cmake in the build directory to be used by other projects,
without needing it to be installed.

1
Help/guide/tutorial/Step11/tutorial.cxx
View File

@@ -9,6 +9,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;

3
Help/guide/tutorial/Step2/CMakeLists.txt
View File

@@ -2,7 +2,8 @@ cmake_minimum_required(VERSION 3.3)
project(Tutorial)
set(CMAKE_CXX_STANDARD 14)
# the version number.
# set the version number
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)

101
Help/guide/tutorial/Step2/directions.txt
View File

@@ -1,101 +0,0 @@
# Adding a Library #
Now we will add a library to our project. This library will contain our own
implementation for computing the square root of a number. The executable can
then use this library instead of the standard square root function provided by
the compiler.
For this tutorial we will put the library into a subdirectory
called MathFunctions. It will have the following one line CMakeLists file:
add_library(MathFunctions mysqrt.cxx)
The source file mysqrt.cxx has one function called mysqrt that provides similar
functionality to the compiler’s sqrt function. To make use of the new library
we add an add_subdirectory call in the top-level CMakeLists file so that the
library will get built. We add the new library to the executable, and add the
MathFunctions as an include directory so that mqsqrt.h header file can be
found. The last few lines of the top-level CMakeLists file now look like:
add_subdirectory(MathFunctions)
#add the executable
add_executable(Tutorial tutorial.cxx)
target_link_libraries(Tutorial ${EXTRA_LIBS})
Now let us make the MathFunctions library optional. While for the tutorial
there really isn’t any need to do so, but with larger projects this is a common
occurrence. The first step is to add an option to the top-level CMakeLists file.
option (USE_MYMATH
"Use tutorial provided math implementation" ON)
This will show up in CMake GUI and ccmake with a default value of ON that can
be changed by the user. This setting will be stored so that the user does not
need to set the value each time they run CMake on this build directory.
The next change is to make building and linking the MathFunctions library
conditional. To do this we change the top-level CMakeLists file to look like
the following:
cmake_minimum_required(VERSION 3.3)
project(Tutorial)
set(CMAKE_CXX_STANDARD 14)
# the version number.
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)
# configure a header file to pass some of the CMake settings
# to the source code
configure_file(
"${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
"${PROJECT_BINARY_DIR}/TutorialConfig.h"
)
# should we use our own math functions
option(USE_MYMATH "Use tutorial provided math implementation" ON)
# add the MathFunctions library?
if(USE_MYMATH)
add_subdirectory(MathFunctions)
list(APPEND EXTRA_LIBS MathFunctions)
list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions")
endif(USE_MYMATH)
# add the executable
add_executable(Tutorial tutorial.cxx)
target_link_libraries(Tutorial ${EXTRA_LIBS})
# add the binary tree to the search path for include files
# so that we will find TutorialConfig.h
target_include_directories(Tutorial PUBLIC
"${PROJECT_BINARY_DIR}"
${EXTRA_INCLUDES}
)
Note the use of the variables EXTRA_LIBS, and EXTRA_INCLUDES to collect
up any optional libraries to later be linked into the executable. This is a
classic approach when dealing with many optional components, we will cover the
modern approach in the next step. For now the corresponding changes to the
source code are fairly straightforward and leave us with:
#ifdef USE_MYMATH
double outputValue = mysqrt(inputValue);
#else
double outputValue = sqrt(inputValue);
#endif
Since the source code now requires USE_MYMATH we can add it to the
TutorialConfig.h.in. Simply add the following line:
#cmakedefine USE_MYMATH
Run cmake or cmake-gui to configure the project and then build it with your
chosen build tool and then run the built Tutorial executable.
Which function gives better results, Step1’s sqrt or Step2’s mysqrt?

1
Help/guide/tutorial/Step2/tutorial.cxx
View File

@@ -8,6 +8,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;

2
Help/guide/tutorial/Step3/CMakeLists.txt
View File

@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 14)
# should we use our own math functions
option(USE_MYMATH "Use tutorial provided math implementation" ON)
# the version number.
# set the version number
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)

26
Help/guide/tutorial/Step3/directions.txt
View File

@@ -1,26 +0,0 @@
# Adding Usage Requirements for Library #
Usage requirements allow for far better control over a library / executable's
link and include line. While also giving more control over the transitive
property of targets inside CMake. The primary commands that leverage usage
requirements are:
- target_compile_definitions
- target_compile_options
- target_include_directories
- target_link_libraries
First up is MathFunctions. We first state that anybody linking to MathFunctions
needs to include the current source directory, while MathFunctions itself
doesn't. So this can become an INTERFACE usage requirement.
Remember INTERFACE means things that consumers require but the producer doesn't.
target_include_directories(MathFunctions
INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})
Now that we've specified usage requirements for MathFunctions we can safely remove
our uses of the EXTRA_INCLUDES variable.
Run cmake or cmake-gui to configure the project and then build it with your
chosen build tool.

3
Help/guide/tutorial/Step3/tutorial.cxx
View File

@@ -5,6 +5,7 @@
#include "TutorialConfig.h"
// should we include the MathFunctions header?
#ifdef USE_MYMATH
# include "MathFunctions.h"
#endif
@@ -12,6 +13,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
double inputValue = std::stod(argv[1]);
// which square root function should we use?
#ifdef USE_MYMATH
double outputValue = mysqrt(inputValue);
#else

2
Help/guide/tutorial/Step4/CMakeLists.txt
View File

@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 14)
# should we use our own math functions
option(USE_MYMATH "Use tutorial provided math implementation" ON)
# the version number.
# set the version number
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)

72
Help/guide/tutorial/Step4/directions.txt
View File

@@ -1,72 +0,0 @@
# Installing and Testing #
Now we can start adding testing support and install rules to our project.
The install rules are fairly simple; for MathFunctions we install the library
and header file, for the application we install the executable and configured
header.
So to MathFunctions/CMakeLists.txt we add:
install (TARGETS MathFunctions DESTINATION bin)
install (FILES MathFunctions.h DESTINATION include)
And the to top-level CMakeLists.txt we add:
install(TARGETS Tutorial DESTINATION bin)
install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h"
DESTINATION include
)
That is all that is needed to create a basic local install of the tutorial.
Run cmake or cmake-gui to configure the project and then build it with your
chosen build tool. Then build the “install” target by typing 'make install'
from the command line or build the INSTALL target from an IDE. This will
install the appropriate header files, libraries, and executables.
Verify that the installed Tutorial runs. Note: The CMake variable
CMAKE_INSTALL_PREFIX is used to determine the root of where the files will
be installed.
Next let's test our application. Adding testing is an easy process. At the
end of the top-level CMakeLists file we can add a number of basic tests to
verify that the application is working correctly.
# enable testing
enable_testing()
# does the application run
add_test(NAME Runs COMMAND Tutorial 25)
# does the usage message work?
add_test(NAME Usage COMMAND Tutorial)
set_tests_properties(Usage
PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number"
)
# define a function to simplify adding tests
function(do_test target arg result)
add_test(NAME Comp${arg} COMMAND ${target} ${arg})
set_tests_properties(Comp${arg}
PROPERTIES PASS_REGULAR_EXPRESSION ${result}
)
endfunction(do_test)
# do a bunch of result based tests
do_test(Tutorial 25 "25 is 5")
do_test(Tutorial -25 "-25 is [-nan|nan|0]")
do_test(Tutorial 0.0001 "0.0001 is 0.01")
The first test simply verifies that the application runs, does not segfault or
otherwise crash, and has a zero return value. This is the basic form of a CTest
test.
The Usage test uses a regular expression to verify that the usage message
is printed when an incorrect number of arguments are provided.
Lastly, we have a function called do_test that simplifies running the
application and verifying that the computed square root is correct for given
input.
To run tests, cd to the binary directory and run “ctest -N” and “ctest -VV”.

3
Help/guide/tutorial/Step4/tutorial.cxx
View File

@@ -5,6 +5,7 @@
#include "TutorialConfig.h"
// should we include the MathFunctions header?
#ifdef USE_MYMATH
# include "MathFunctions.h"
#endif
@@ -12,6 +13,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
double inputValue = std::stod(argv[1]);
// which square root function should we use?
#ifdef USE_MYMATH
double outputValue = mysqrt(inputValue);
#else

2
Help/guide/tutorial/Step5/CMakeLists.txt
View File

@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 14)
# should we use our own math functions
option(USE_MYMATH "Use tutorial provided math implementation" ON)
# the version number.
# set the version number
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)

1
Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt
View File

@@ -6,5 +6,6 @@ target_include_directories(MathFunctions
INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
)
# install rules
install(TARGETS MathFunctions DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)

69
Help/guide/tutorial/Step5/directions.txt
View File

@@ -1,69 +0,0 @@
# Adding System Introspection #
Let us consider adding some code to our project that depends on features the
target platform may not have. For this example, we will add some code that
depends on whether or not the target platform has the log and exp functions. Of
course almost every platform has these functions but for this tutorial assume
that they are not common.
If the platform has log and exp then we will use them to compute the square
root in the mysqrt function. We first test for the availability of these
functions using the CheckSymbolExists.cmake macro in the top-level CMakeLists
file as follows:
# does this system provide the log and exp functions?
include(CheckSymbolExists)
set(CMAKE_REQUIRED_LIBRARIES "m")
check_symbol_exists(log "math.h" HAVE_LOG)
check_symbol_exists(exp "math.h" HAVE_EXP)
Now let's add these defines to TutorialConfig.h.in so that we can use them
from mysqrt.cxx:
// does the platform provide exp and log functions?
#cmakedefine HAVE_LOG
#cmakedefine HAVE_EXP
Modify mysqrt.cxx to include math.h. Next, in the mysqrt function we can
provide an alternate implementation based on log and exp if they are available
on the system using the following code:
// if we have both log and exp then use them
#if defined(HAVE_LOG) && defined (HAVE_EXP)
double result = exp(log(x)*0.5);
std::cout << "Computing sqrt of " << x << " to be " << result << " using log" << std::endl;
#else
...
Run cmake or cmake-gui to configure the project and then build it with your
chosen build tool.
You will notice that even though HAVE_LOG and HAVE_EXP are both defined mysqrt
isn't using them. We should realize quickly that we have forgotten to include
TutorialConfig.h in mysqrt.cxx. We will also need to update
MathFunctions/CMakeLists.txt with where it is located.
So let's go ahead and update MathFunctions/CMakeLists.txt to look like:
add_library(MathFunctions mysqrt.cxx)
target_include_directories(MathFunctions
INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
PRIVATE ${Tutorial_BINARY_DIR}
)
install(TARGETS MathFunctions DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)
Now all we need to do is include TutorialConfig.h in mysqrt.cxx
At this point you should go ahead and build the project again.
Run the built Tutorial executable. Which function gives better results now,
Step1’s sqrt or Step5’s mysqrt?
Exercise: Why is it important that we configure TutorialConfig.h.in after the
checks for HAVE_LOG and HAVE_EXP? What would happen if we inverted the two?
Exercise: Is there a better place for us to save the HAVE_LOG and HAVE_EXP
values other than in TutorialConfig.h?

3
Help/guide/tutorial/Step5/tutorial.cxx
View File

@@ -5,6 +5,7 @@
#include "TutorialConfig.h"
// should we include the MathFunctions header?
#ifdef USE_MYMATH
# include "MathFunctions.h"
#endif
@@ -12,6 +13,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
double inputValue = std::stod(argv[1]);
// which square root function should we use?
#ifdef USE_MYMATH
double outputValue = mysqrt(inputValue);
#else

2
Help/guide/tutorial/Step6/CMakeLists.txt
View File

@@ -3,7 +3,7 @@ project(Tutorial)
set(CMAKE_CXX_STANDARD 14)
# the version number.
# set the version number
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)

2
Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt
View File

@@ -4,11 +4,11 @@ add_library(MathFunctions mysqrt.cxx)
# to find MathFunctions.h, while we don't.
# state that we depend on Tutorial_BINARY_DIR but consumers don't, as the
# TutorialConfig.h include is an implementation detail
target_include_directories(MathFunctions
INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
PRIVATE ${Tutorial_BINARY_DIR}
)
# install rules
install(TARGETS MathFunctions DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)

104
Help/guide/tutorial/Step6/directions.txt
View File

@@ -1,104 +0,0 @@
# Adding a Custom Command and Generated File #
In this section we will show how you can add a generated source file into the
build process of an application. For this example, we will create a table of
precomputed square roots as part of the build process, and then compile that
table into our application.
To accomplish this, we first need a program that will generate the table. In the
MathFunctions subdirectory a new source file named MakeTable.cxx will do just that.
// A simple program that builds a sqrt table
#include <iostream>
#include <fstream>
#include <cmath>
int main (int argc, char *argv[])
{
// make sure we have enough arguments
if (argc < 2) {
return 1;
}
std::ofstream fout(argv[1],std::ios_base::out);
const bool fileOpen = fout.is_open();
if(fileOpen) {
fout << "double sqrtTable[] = {" << std::endl;
for (int i = 0; i < 10; ++i) {
fout << sqrt(static_cast<double>(i)) << "," << std::endl;
}
// close the table with a zero
fout << "0};" << std::endl;
fout.close();
}
return fileOpen ? 0 : 1; // return 0 if wrote the file
}
Note that the table is produced as valid C++ code and that the output filename
is passed in as an argument.
The next step is to add the appropriate commands to MathFunctions’ CMakeLists
file to build the MakeTable executable and then run it as part of the build
process. A few commands are needed to accomplish this, as shown below:
# first we add the executable that generates the table
add_executable(MakeTable MakeTable.cxx)
# add the command to generate the source code
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h
COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h
DEPENDS MakeTable
)
# add the main library
add_library(MathFunctions
mysqrt.cxx
${CMAKE_CURRENT_BINARY_DIR}/Table.h
)
target_include_directories(MathFunctions
INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
PUBLIC ${Tutorial_BINARY_DIR}
# add the binary tree directory to the search path for include files
${CMAKE_CURRENT_BINARY_DIR}
)
install(TARGETS MathFunctions DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)
First, the executable for MakeTable is added as any other executable would be
added. Then we add a custom command that specifies how to produce Table.h by
running MakeTable. Next we have to let CMake know that mysqrt.cxx depends on
the generated file Table.h. This is done by adding the generated Table.h to the
list of sources for the library MathFunctions. We also have to add the current
binary directory to the list of include directories so that Table.h can be
found and included by mysqrt.cxx.
Now let's use the generated table. First, modify mysqrt.cxx to include Table.h.
Next, we can rewrite the mysqrt function to use the table:
if (x <= 0) {
return 0;
}
// use the table to help find an initial value
double result = x;
if (x >= 1 && x < 10) {
result = sqrtTable[static_cast<int>(x)];
}
// do ten iterations
for (int i = 0; i < 10; ++i) {
if (result <= 0) {
result = 0.1;
}
double delta = x - (result*result);
result = result + 0.5*delta/result;
std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
}
Run cmake or cmake-gui to configure the project and then build it with your
chosen build tool. When this project is built it will first build the MakeTable
executable. It will then run MakeTable to produce Table.h. Finally, it will
compile mysqrt.cxx which includes Table.h to produce the MathFunctions library.

3
Help/guide/tutorial/Step6/tutorial.cxx
View File

@@ -5,6 +5,7 @@
#include "TutorialConfig.h"
// should we include the MathFunctions header?
#ifdef USE_MYMATH
# include "MathFunctions.h"
#endif
@@ -12,6 +13,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
double inputValue = std::stod(argv[1]);
// which square root function should we use?
#ifdef USE_MYMATH
double outputValue = mysqrt(inputValue);
#else

2
Help/guide/tutorial/Step7/CMakeLists.txt
View File

@@ -3,7 +3,7 @@ project(Tutorial)
set(CMAKE_CXX_STANDARD 14)
# the version number.
# set the version number
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)

1
Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt
View File

@@ -25,5 +25,6 @@ target_include_directories(MathFunctions
${CMAKE_CURRENT_BINARY_DIR}
)
# install rules
install(TARGETS MathFunctions DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)

40
Help/guide/tutorial/Step7/directions.txt
View File

@@ -1,40 +0,0 @@
# Building an Installer #
Next suppose that we want to distribute our project to other people so that they
can use it. We want to provide both binary and source distributions on a variety
of platforms. This is a little different from the install we did previously in
the Installing and Testing section (Step 4), where we were installing the
binaries that we had built from the source code. In this example we will be
building installation packages that support binary installations and package
management features. To accomplish this we will use CPack to create platform
specific installers. Specifically we need to add a few lines to the bottom of
our top-level CMakeLists.txt file.
include(InstallRequiredSystemLibraries)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
include(CPack)
That is all there is to it. We start by including InstallRequiredSystemLibraries.
This module will include any runtime libraries that are needed by the project
for the current platform. Next we set some CPack variables to where we have
stored the license and version information for this project. The version
information makes use of the variables we set earlier in this tutorial. Finally
we include the CPack module which will use these variables and some other
properties of the system you are on to setup an installer.
The next step is to build the project in the usual manner and then run CPack
on it. To build a binary distribution you would run:
cpack
To create a source distribution you would type:
cpack -C CPackSourceConfig.cmake
Alternatively, run “make package” or right click the Package target and
“Build Project” from an IDE.
Run the installer executable found in the binary directory. Then run the
installed executable and verify that it works.

3
Help/guide/tutorial/Step7/tutorial.cxx
View File

@@ -5,6 +5,7 @@
#include "TutorialConfig.h"
// should we include the MathFunctions header?
#ifdef USE_MYMATH
# include "MathFunctions.h"
#endif
@@ -12,6 +13,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
double inputValue = std::stod(argv[1]);
// which square root function should we use?
#ifdef USE_MYMATH
double outputValue = mysqrt(inputValue);
#else

3
Help/guide/tutorial/Step8/CMakeLists.txt
View File

@@ -3,7 +3,7 @@ project(Tutorial)
set(CMAKE_CXX_STANDARD 14)
# the version number.
# set the version number
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)
@@ -74,6 +74,7 @@ do_test(Tutorial 25 "25 is 5")
do_test(Tutorial -25 "-25 is [-nan|nan|0]")
do_test(Tutorial 0.0001 "0.0001 is 0.01")
# setup installer
include(InstallRequiredSystemLibraries)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")

1
Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt
View File

@@ -25,5 +25,6 @@ target_include_directories(MathFunctions
${CMAKE_CURRENT_BINARY_DIR}
)
# install rules
install(TARGETS MathFunctions DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)

38
Help/guide/tutorial/Step8/directions.txt
View File

@@ -1,38 +0,0 @@
# Adding Support for a Dashboard #
Adding support for submitting our test results to a dashboard is very easy. We
already defined a number of tests for our project in the earlier steps of this
tutorial. We just have to run those tests and submit them to a dashboard. To
include support for dashboards we include the CTest module in our top-level
CMakeLists.txt.
Replace:
# enable testing
enable_testing()
With:
# enable dashboard scripting
include(CTest)
The CTest module will automatically call enable_testing(), so
we can remove it from our CMake files.
We will also need to create a CTestConfig.cmake file where we can specify the
name of the project and where to submit the dashboard.
set(CTEST_PROJECT_NAME "CMakeTutorial")
set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
set(CTEST_DROP_METHOD "http")
set(CTEST_DROP_SITE "my.cdash.org/")
set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial")
set(CTEST_DROP_SITE_CDASH TRUE)
CTest will read in this file when it runs. To create a simple dashboard you can
run cmake or cmake-gui to configure the project, but do not build it yet.
Instead, change directory to the binary tree, and then run:
'ctest [-VV] –D Experimental'. On Windows, build the EXPERIMENTAL target.
Ctest will build and test the project and submit results to the Kitware public
dashboard. The results of your dashboard will be uploaded to Kitware's public
dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial.

3
Help/guide/tutorial/Step8/tutorial.cxx
View File

@@ -5,6 +5,7 @@
#include "TutorialConfig.h"
// should we include the MathFunctions header?
#ifdef USE_MYMATH
# include "MathFunctions.h"
#endif
@@ -12,6 +13,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
double inputValue = std::stod(argv[1]);
// which square root function should we use?
#ifdef USE_MYMATH
double outputValue = mysqrt(inputValue);
#else

2
Help/guide/tutorial/Step9/CMakeLists.txt
View File

@@ -3,7 +3,7 @@ project(Tutorial)
set(CMAKE_CXX_STANDARD 14)
# the version number.
# set the version number
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)

1
Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt
View File

@@ -31,5 +31,6 @@ if(HAVE_LOG AND HAVE_EXP)
PRIVATE "HAVE_LOG" "HAVE_EXP")
endif()
# install rules
install(TARGETS MathFunctions DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)

166
Help/guide/tutorial/Step9/directions.txt
View File

@@ -1,166 +0,0 @@
# Mixing Static and Shared #
In this section we will show how by using the BUILD_SHARED_LIBS variable we can
control the default behavior of add_library, and allow control over how
libraries without an explicit type ( STATIC/SHARED/MODULE/OBJECT ) are built.
To accomplish this we need to add BUILD_SHARED_LIBS to the top level
CMakeLists.txt. We use the option command as it allows users to optionally
select if the value should be On or Off.
Next we are going to refactor MathFunctions to become a real library that
encapsulates using mysqrt or sqrt, instead of requiring the calling code
to do this logic. This will also mean that USE_MYMATH will not control building
MathFuctions, but instead will control the behavior of this library.
The first step is to update the starting section of the top level CMakeLists.txt
to look like:
cmake_minimum_required(VERSION 3.3)
project(Tutorial)
# control where the static and shared libraries are built so that on windows
# we don't need to tinker with the path to run the executable
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)
option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
# the version number.
set(Tutorial_VERSION_MAJOR 1)
set(Tutorial_VERSION_MINOR 0)
# configure a header file to pass the version number only
configure_file(
"${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
"${PROJECT_BINARY_DIR}/TutorialConfig.h"
)
# add the MathFunctions library
add_subdirectory(MathFunctions)
# add the executable
add_executable(Tutorial tutorial.cxx)
target_link_libraries(Tutorial PUBLIC MathFunctions)
Now that we have made MathFunctions always be used, we will need to update
the logic of that library. So, in MathFunctions/CMakeLists.txt we need to
create a SqrtLibrary that will conditionally be built when USE_MYMATH is
enabled. Now, since this is a tutorial, we are going to explicitly require
that SqrtLibrary is built statically.
The end result is that MathFunctions/CMakeLists.txt should look like:
# add the library that runs
add_library(MathFunctions MathFunctions.cxx)
# state that anybody linking to us needs to include the current source dir
# to find MathFunctions.h, while we don't.
target_include_directories(MathFunctions
INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
)
# should we use our own math functions
option(USE_MYMATH "Use tutorial provided math implementation" ON)
if(USE_MYMATH)
# does this system provide the log and exp functions?
include(CheckSymbolExists)
set(CMAKE_REQUIRED_LIBRARIES "m")
check_symbol_exists(log "math.h" HAVE_LOG)
check_symbol_exists(exp "math.h" HAVE_EXP)
# first we add the executable that generates the table
add_executable(MakeTable MakeTable.cxx)
# add the command to generate the source code
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h
COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h
DEPENDS MakeTable
)
# library that just does sqrt
add_library(SqrtLibrary STATIC
mysqrt.cxx
${CMAKE_CURRENT_BINARY_DIR}/Table.h
)
# state that we depend on our binary dir to find Table.h
target_include_directories(SqrtLibrary PRIVATE
${CMAKE_CURRENT_BINARY_DIR}
)
target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
if(HAVE_LOG AND HAVE_EXP)
target_compile_definitions(SqrtLibrary
PRIVATE "HAVE_LOG" "HAVE_EXP")
endif()
target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif()
# define the symbol stating we are using the declspec(dllexport) when
# building on windows
target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
install(TARGETS MathFunctions DESTINATION lib)
install(FILES MathFunctions.h DESTINATION include)
Next, update MathFunctions/mysqrt.cxx to use the mathfunctions and detail namespaces:
#include <iostream>
#include "MathFunctions.h"
// include the generated table
#include "Table.h"
#include <cmath>
namespace mathfunctions {
namespace detail {
// a hack square root calculation using simple operations
double mysqrt(double x)
{
...
return result;
}
}
}
We also need to make some changes in tutorial.cxx, so that it no longer uses USE_MYMATH:
1. Always include MathFunctions.h
2. Always use mathfunctions::sqrt
Finally, update MathFunctions/MathFunctions.h to use dll export defines:
#if defined(_WIN32)
#if defined(EXPORTING_MYMATH)
#define DECLSPEC __declspec(dllexport)
#else
#define DECLSPEC __declspec(dllimport)
#endif
#else //non windows
#define DECLSPEC
#endif
namespace mathfunctions
{
double DECLSPEC sqrt(double x);
}
At this point, if you build everything, you will notice that linking fails
as we are combining a static library without position enabled code with a
library that has position enabled code. This solution to this is to explicitly
set the POSITION_INDEPENDENT_CODE target property of SqrtLibrary to be True no
matter the build type.
Exercise: We modified MathFunctions.h to use dll export defines. Using CMake
documentation can you find a helper module to simplify this?
Exercise: Determine what command is enabling PIC for SqrtLibrary.
What happens if we remove said command?

3
Help/guide/tutorial/Step9/tutorial.cxx
View File

@@ -6,6 +6,7 @@
#include "TutorialConfig.h"
// should we include the MathFunctions header?
#ifdef USE_MYMATH
# include "MathFunctions.h"
#endif
@@ -13,6 +14,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -21,6 +23,7 @@ int main(int argc, char* argv[])
double inputValue = std::stod(argv[1]);
// which square root function should we use?
#ifdef USE_MYMATH
double outputValue = mysqrt(inputValue);
#else

717
Help/guide/tutorial/index.rst
View File

@@ -1,2 +1,719 @@
CMake Tutorial
**************
A Basic Starting Point (Step 1)
===============================
Adding a Version Number and Configured Header File
--------------------------------------------------
The first feature we will add is to provide our executable and project with a
version number. While we could do this exclusively in the source code, using
CMakeLists provides more flexibility.
To add a version number we modify the CMakeLists file as follows:
.. literalinclude:: Step2/CMakeLists.txt
:language: cmake
:start-after: # set the version number
:end-before: # configure a header file
We then create a ``TutorialConfig.h.in`` file in the source tree with the
following contents:
.. literalinclude:: Step1/TutorialConfig.h.in
:language: cmake
When CMake configures this header file the values for
``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be
replaced by the values from the CMakeLists file. Next we modify
``tutorial.cxx`` to include the configured header file and to make use of the
version numbers. The updated source code is listed below.
.. literalinclude:: Step2/tutorial.cxx
:language: c++
:start-after: // report version
:end-before: return 1;
Specify the C++ Standard
-------------------------
Next let's add some C++11 features to our project. We will need to explicitly
state in the CMake code that it should use the correct flags. The easiest way
to enable C++11 support for CMake is by using the ``CMAKE_CXX_STANDARD``
variable.
First, replace ``atof`` with ``std::stod`` in ``tutorial.cxx``.
Then, set the ``CMAKE_CXX_STANDARD`` variable in the CMakeLists file.
Which variable can we set in the CMakeLists file to treat the
``CMAKE_CXX_STANDARD`` value as a requirement?
Build and Test
--------------
Run **cmake** or **cmake-gui** to configure the project and then build it
with your chosen build tool.
cd to the directory where Tutorial was built (likely the make directory or
a Debug or Release build configuration subdirectory) and run these commands:
.. code-block:: console
Tutorial 4294967296
Tutorial 10
Tutorial
Adding a Library (Step 2)
=========================
Now we will add a library to our project. This library will contain our own
implementation for computing the square root of a number. The executable can
then use this library instead of the standard square root function provided by
the compiler.
For this tutorial we will put the library into a subdirectory
called MathFunctions. It will have the following one line CMakeLists file:
.. literalinclude:: Step2/MathFunctions/CMakeLists.txt
:language: cmake
The source file ``mysqrt.cxx`` has one function called ``mysqrt`` that
provides similar functionality to the compiler’s ``sqrt`` function. To make use
of the new library we add an ``add_subdirectory`` call in the top-level
CMakeLists file so that the library will get built. We add the new library to
the executable, and add MathFunctions as an include directory so that the
``mqsqrt.h`` header file can be found. The last few lines of the top-level
CMakeLists file now look like:
.. code-block:: cmake
# add the MathFunctions library
add_subdirectory(MathFunctions)
# add the executable
add_executable(Tutorial tutorial.cxx)
target_link_libraries(Tutorial MathFunctions)
# add the binary tree to the search path for include files
# so that we will find TutorialConfig.h
target_include_directories(Tutorial PUBLIC
"${PROJECT_BINARY_DIR}"
"${PROJECT_SOURCE_DIR}/MathFunctions"
)
Now let us make the MathFunctions library optional. While for the tutorial
there really isn’t any need to do so, for larger projects this is a common
occurrence. The first step is to add an option to the top-level CMakeLists
file.
.. literalinclude:: Step3/CMakeLists.txt
:language: cmake
:start-after: # should we use our own math functions
:end-before: # set the version number
This will show up in the CMake GUI and ccmake with a default value of ON
that can be changed by the user. This setting will be stored in the cache so
that the user does not need to set the value each time they run CMake on this
build directory.
The next change is to make building and linking the MathFunctions library
conditional. To do this we change the end of the top-level CMakeLists file to
look like the following:
.. literalinclude:: Step3/CMakeLists.txt
:language: cmake
:start-after: # add the MathFunctions library?
Note the use of the variables ``EXTRA_LIBS`` and ``EXTRA_INCLUDES`` to collect
up any optional libraries to later be linked into the executable. This is a
classic approach when dealing with many optional components, we will cover the
modern approach in the next step.
The corresponding changes to the source code are fairly straightforward. First,
include the MathFunctions header if we need it:
.. literalinclude:: Step3/tutorial.cxx
:language: c++
:start-after: // should we include the MathFunctions header
:end-before: int main
Then make which square root function is used dependent on ``USE_MYMATH``:
.. literalinclude:: Step3/tutorial.cxx
:language: c++
:start-after: // which square root function should we use?
:end-before: std::cout << "The square root of
Since the source code now requires ``USE_MYMATH`` we can add it to
``TutorialConfig.h.in`` with the following line:
.. literalinclude:: Step3/TutorialConfig.h.in
:language: c
:lines: 4
Run **cmake** or **cmake-gui** to configure the project and then build it
with your chosen build tool. Then run the built Tutorial executable.
Which function gives better results, Step1’s sqrt or Step2’s mysqrt?
Adding Usage Requirements for Library (Step 3)
==============================================
Usage requirements allow for far better control over a library or executable's
link and include line while also giving more control over the transitive
property of targets inside CMake. The primary commands that leverage usage
requirements are:
- ``target_compile_definitions``
- ``target_compile_options``
- ``target_include_directories``
- ``target_link_libraries``
First up is MathFunctions. We first state that anybody linking to MathFunctions
needs to include the current source directory, while MathFunctions itself
doesn't. So this can become an ``INTERFACE`` usage requirement.
Remember ``INTERFACE`` means things that consumers require but the producer
doesn't. Update ``MathFunctions/CMakeLists.txt`` with:
.. literalinclude:: Step4/MathFunctions/CMakeLists.txt
:language: cmake
:start-after: # to find MathFunctions.h
Now that we've specified usage requirements for MathFunctions we can safely
remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level
CMakeLists.
Once this is done, run **cmake** or **cmake-gui** to configure the project
and then build it with your chosen build tool.
Installing and Testing (Step 4)
===============================
Now we can start adding install rules and testing support to our project.
Install Rules
-------------
The install rules are fairly simple for MathFunctions we want to install the
library and header file and for the application we want to install the
executable and configured header.
So to ``MathFunctions/CMakeLists.txt`` we add:
.. literalinclude:: Step5/MathFunctions/CMakeLists.txt
:language: cmake
:start-after: # install rules
And the to top-level ``CMakeLists.txt`` we add:
.. literalinclude:: Step5/CMakeLists.txt
:language: cmake
:start-after: # add the install targets
:end-before: # enable testing
That is all that is needed to create a basic local install of the tutorial.
Run **cmake** or **cmake-gui** to configure the project and then build it
with your chosen build tool. Build the ``install`` target by typing
``make install`` from the command line or build the ``INSTALL`` target from
an IDE. This will install the appropriate header files, libraries, and
executables.
Verify that the installed Tutorial runs. Note: The CMake variable
``CMAKE_INSTALL_PREFIX`` is used to determine the root of where the files will
be installed.
Testing Support
---------------
Next let's test our application. At the end of the top-level CMakeLists file we
can add a number of basic tests to verify that the application is
working correctly.
.. literalinclude:: Step5/CMakeLists.txt
:language: cmake
:start-after: # enable testing
The first test simply verifies that the application runs, does not segfault or
otherwise crash, and has a zero return value. This is the basic form of a CTest
test.
The next test makes use of the ``PASS_REGULAR_EXPRESSION`` test property to
verify that the output of the test contains certain strings, in this case:
verifying that the the usage message is printed when an incorrect number of
arguments are provided.
Lastly, we have a function called ``do_test`` that runs the application and
verifies that the computed square root is correct for given input. For each
invocation of ``do_test``, another test is added to the project with a name,
input, and expected results based on the passed arguments.
Rebuild the application and then cd to the binary directory and run
``ctest -N`` and ``ctest -VV``.
Adding System Introspection (Step 5)
====================================
Let us consider adding some code to our project that depends on features the
target platform may not have. For this example, we will add some code that
depends on whether or not the target platform has the ``log`` and ``exp``
functions. Of course almost every platform has these functions but for this
tutorial assume that they are not common.
If the platform has ``log`` and ``exp`` then we will use them to compute the
square root in the ``mysqrt`` function. We first test for the availability of
these functions using the ``CheckSymbolExists.cmake`` macro in the top-level
CMakeLists file as follows:
.. literalinclude:: Step6/CMakeLists.txt
:language: cmake
:start-after: # does this system provide the log and exp functions?
:end-before: # should we use our own math functions
Now let's add these defines to ``TutorialConfig.h.in`` so that we can use them
from ``mysqrt.cxx``:
.. literalinclude:: Step6/TutorialConfig.h.in
:language: c
:start-after: // does the platform provide exp and log functions?
Finally, in the ``mysqrt`` function we can provide an alternate implementation
based on ``log`` and ``exp`` if they are available on the system using the
following code:
.. literalinclude:: Step6/MathFunctions/mysqrt.cxx
:language: c++
:start-after: // if we have both log and exp then use them
:end-before: #else
Run **cmake** or **cmake-gui** to configure the project and then build it
with your chosen build tool.
You will notice that even though ``HAVE_LOG`` and ``HAVE_EXP`` are both
defined ``mysqrt`` isn't using them. We should realize quickly that we have
forgotten to include ``TutorialConfig.h`` in ``mysqrt.cxx``.
After making this update, go ahead and build the project again.
Run the built Tutorial executable. Which function gives better results now,
Step1’s sqrt or Step5’s mysqrt?
**Exercise**: Why is it important that we configure ``TutorialConfig.h.in``
after the checks for ``HAVE_LOG`` and ``HAVE_EXP``? What would happen if we
inverted the two?
**Exercise**: Is there a better place for us to save the ``HAVE_LOG`` and
``HAVE_EXP`` values other than in ``TutorialConfig.h``?
Adding a Custom Command and Generated File (Step 6)
===================================================
In this section, we will add a generated source file into the build process
of an application. For this example, we will create a table of precomputed
square roots as part of the build process, and then compile that
table into our application.
To accomplish this, we first need a program that will generate the table. In
the MathFunctions subdirectory a new source file named ``MakeTable.cxx`` will
do just that.
.. literalinclude:: Step7/MathFunctions/MakeTable.cxx
:language: c++
Note that the table is produced as valid C++ code and that the output filename
is passed in as an argument.
The next step is to add the appropriate commands to MathFunctions' CMakeLists
file to build the MakeTable executable and then run it as part of the build
process. A few commands are needed to accomplish this.
First, the executable for ``MakeTable`` is added as any other executable would
be added.
.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
:language: cmake
:start-after: # first we add the executable that generates the table
:end-before: # add the command to generate the source code
Then we add a custom command that specifies how to produce ``Table.h``
by running MakeTable.
.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
:language: cmake
:start-after: # add the command to generate the source code
:end-before: # add the main library
Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated
file ``Table.h``. This is done by adding the generated ``Table.h`` to the list
of sources for the library MathFunctions.
.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
:language: cmake
:start-after: # add the main library
:end-before: # state that anybody linking
We also have to add the current binary directory to the list of include
directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``.
.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
:start-after: # state that we depend on our bin
:end-before: # install rules
Now let's use the generated table. First, modify ``mysqrt.cxx`` to include
``Table.h``. Next, we can rewrite the mysqrt function to use the table:
.. literalinclude:: Step7/MathFunctions/mysqrt.cxx
:language: c++
:start-after: // a hack square root calculation using simple operations
Run **cmake** or **cmake-gui** to configure the project and then build it
with your chosen build tool. When this project is built it will first build
the ``MakeTable`` executable. It will then run ``MakeTable`` to produce
``Table.h``. Finally, it will compile ``mysqrt.cxx`` which includes
``Table.h`` to produce the MathFunctions library.
Building an Installer (Step 7)
==============================
Next suppose that we want to distribute our project to other people so that
they can use it. We want to provide both binary and source distributions on a
variety of platforms. This is a little different from the install we did
previously in `Installing and Testing (Step 4)`_ , where we were
installing the binaries that we had built from the source code. In this
example we will be building installation packages that support binary
installations and package management features. To accomplish this we will use
CPack to create platform specific installers. Specifically we need to add
a few lines to the bottom of our top-level ``CMakeLists.txt`` file.
.. literalinclude:: Step8/CMakeLists.txt
:language: cmake
:start-after: # setup installer
That is all there is to it. We start by including
``InstallRequiredSystemLibraries``. This module will include any runtime
libraries that are needed by the project for the current platform. Next we
set some CPack variables to where we have stored the license and version
information for this project. The version information makes use of the
variables we set earlier in this tutorial. Finally we include the CPack
module which will use these variables and some other properties of the system
you are on to setup an installer.
The next step is to build the project in the usual manner and then run
CPack on it. To build a binary distribution you would run:
.. code-block:: console
cpack
To create a source distribution you would type:
.. code-block:: console
cpack -C CPackSourceConfig.cmake
Alternatively, run ``make package`` or right click the ``Package`` target and
``Build Project`` from an IDE.
Run the installer executable found in the binary directory. Then run the
installed executable and verify that it works.
Adding Support for a Dashboard (Step 8)
=======================================
Adding support for submitting our test results to a dashboard is very easy. We
already defined a number of tests for our project in the earlier steps of this
tutorial. We just have to run those tests and submit them to a dashboard. To
include support for dashboards we include the CTest module in our top-level
``CMakeLists.txt``.
Replace:
.. code-block:: cmake
# enable testing
enable_testing()
With:
.. code-block:: cmake
# enable dashboard scripting
include(CTest)
The CTest module will automatically call ``enable_testing()``, so
we can remove it from our CMake files.
We will also need to create a ``CTestConfig.cmake`` file where we can specify
the name of the project and where to submit the dashboard.
.. literalinclude:: Step9/CTestConfig.cmake
:language: cmake
CTest will read in this file when it runs. To create a simple dashboard you can
run **cmake** or **cmake-gui** to configure the project, but do not build it
yet. Instead, change directory to the binary tree, and then run:
.. code-block:: console
'ctest [-VV] –D Experimental'
On Windows, build the EXPERIMENTAL target.
Ctest will build and test the project and submit the results to the Kitware
public dashboard. The results of your dashboard will be uploaded to Kitware's
public dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial.
Mixing Static and Shared (Step 9)
=================================
In this section we will show how by using the ``BUILD_SHARED_LIBS`` variable
we can control the default behavior of ``add_library``, and allow control
over how libraries without an explicit type (STATIC/SHARED/MODULE/OBJECT) are
built.
To accomplish this we need to add ``BUILD_SHARED_LIBS`` to the top-level
``CMakeLists.txt``. We use the ``option`` command as it allows users to
optionally select if the value should be On or Off.
Next we are going to refactor MathFunctions to become a real library that
encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling
code to do this logic. This will also mean that ``USE_MYMATH`` will not control
building MathFuctions, but instead will control the behavior of this library.
The first step is to update the starting section of the top-level
``CMakeLists.txt`` to look like:
.. literalinclude:: Step10/CMakeLists.txt
:language: cmake
:start-after: set(Tutorial_VERSION_MINOR
:end-before: # add the binary tree
Now that we have made MathFunctions always be used, we will need to update
the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to
create a SqrtLibrary that will conditionally be built when ``USE_MYMATH`` is
enabled. Now, since this is a tutorial, we are going to explicitly require
that SqrtLibrary is built statically.
The end result is that ``MathFunctions/CMakeLists.txt`` should look like:
.. literalinclude:: Step10/MathFunctions/CMakeLists.txt
:language: cmake
:lines: 1-40,46-
Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and
``detail`` namespaces:
.. literalinclude:: Step10/MathFunctions/mysqrt.cxx
:language: c++
We also need to make some changes in ``tutorial.cxx``, so that it no longer
uses ``USE_MYMATH``:
#. Always include ``MathFunctions.h``
#. Always use ``mathfunctions::sqrt``
Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
.. literalinclude:: Step10/MathFunctions/MathFunctions.h
:language: c++
At this point, if you build everything, you will notice that linking fails
as we are combining a static library without position enabled code with a
library that has position enabled code. The solution to this is to explicitly
set the ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary to be
True no matter the build type.
**Exercise**: We modified ``MathFunctions.h`` to use dll export defines.
Using CMake documentation can you find a helper module to simplify this?
Adding Generator Expressions (Step 10)
======================================
Generator expressions are evaluated during build system generation to produce
information specific to each build configuration.
Generator expressions are allowed in the context of many target properties,
such as ``LINK_LIBRARIES``, ``INCLUDE_DIRECTORIES``, ``COMPILE_DEFINITIONS``
and others. They may also be used when using commands to populate those
properties, such as ``target_link_libraries()``,
``target_include_directories()``,
``target_compile_definitions()`` and others.
Generator expressions may be used to enable conditional linking, conditional
definitions used when compiling, conditional include directories and more.
The conditions may be based on the build configuration, target properties,
platform information or any other queryable information.
There are different types of generator expressions including Logical,
Informational, and Output expressions.
Logical expressions are used to create conditional output. The basic
expressions are the 0 and 1 expressions. A ``$<0:...>`` results in the empty
string, and ``<1:...>`` results in the content of "...". They can also be
nested.
For example:
.. code-block:: cmake
if(HAVE_LOG AND HAVE_EXP)
target_compile_definitions(SqrtLibrary
PRIVATE "HAVE_LOG" "HAVE_EXP")
endif()
Can be rewritten with generator expressions:
.. code-block:: cmake
target_compile_definitions(SqrtLibrary PRIVATE
"$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>"
"$<$<BOOL:${HAVE_EXP}>:HAVE_EXP>"
)
Note that ``${HAVE_LOG}`` is evaluated at CMake configure time while
``$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>`` is evaluated at build system generation
time.
Adding Export Configuration (Step 11)
=====================================
During `Installing and Testing (Step 4)`_ of the tutorial we added the ability
for CMake to install the library and headers of the project. During
`Building an Installer (Step 7)`_ we added the ability to package up this
information so it could be distributed to other people.
The next step is to add the necessary information so that other CMake projects
can use our project, be it from a build directory, a local install or when
packaged.
The first step is to update our ``install(TARGETS)`` commands to not only
specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword
generates and installs a CMake file containing code to import all targets
listed in the install command from the installation tree. So let's go ahead
and explicitly ``EXPORT`` the MathFunctions library by updating the
``install`` command in ``MathFunctions/CMakeLists.txt`` to look like:
.. literalinclude:: Complete/MathFunctions/CMakeLists.txt
:language: cmake
:start-after: # install rules
Now that we have MathFunctions being exported, we also need to explicitly
install the generated ``MathFunctionsTargets.cmake`` file. This is done by
adding the following to the bottom of the top-level ``CMakeLists.txt``:
.. literalinclude:: Complete/CMakeLists.txt
:language: cmake
:start-after: # install the configuration targets
:end-before: include(CMakePackageConfigHelpers)
At this point you should try and run CMake. If everything is setup properly
you will see that CMake will generate an error that looks like:
.. code-block:: console
Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains
path:
"/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions"
which is prefixed in the source directory.
What CMake is trying to say is that during generating the export information
it will export a path that is intrinsically tied to the current machine and
will not be valid on other machines. The solution to this is to update the
MathFunctions ``target_include_directories`` to understand that it needs
different ``INTERFACE`` locations when being used from within the build
directory and from an install / package. This means converting the
``target_include_directories`` call for MathFunctions to look like:
.. literalinclude:: Complete/MathFunctions/CMakeLists.txt
:language: cmake
:start-after: # to find MathFunctions.h, while we don't.
:end-before: # should we use our own math functions
Once this has been updated, we can re-run CMake and see verify that it doesn't
warn anymore.
At this point, we have CMake properly packaging the target information that is
required but we will still need to generate a ``MathFunctionsConfig.cmake`` so
that the CMake ``find_package command`` can find our project. So let's go
ahead and add a new file to the top-level of the project called
``Config.cmake.in`` with the following contents:
.. literalinclude:: Complete/Config.cmake.in
Then, to properly configure and install that file, add the following to the
bottom of the top-level CMakeLists:
.. literalinclude:: Complete/CMakeLists.txt
:language: cmake
:start-after: # install the configuration targets
:end-before: # generate the export
At this point, we have generated a relocatable CMake Configuration for our
project that can be used after the project has been installed or packaged. If
we want our project to also be used from a build directory we only have to add
the following to the bottom of the top level CMakeLists:
.. literalinclude:: Complete/CMakeLists.txt
:language: cmake
:start-after: # needs to be after the install(TARGETS ) command
With this export call we now generate a ``Targets.cmake``, allowing the
configured ``MathFunctionsConfig.cmake`` in the build directory to be used by
other projects, without needing it to be installed.
Import a CMake Project (Consumer)
=================================
This examples shows how a project can find other CMake packages that
generate ``Config.cmake`` files.
It also shows how to state a project's external dependencies when generating
a ``Config.cmake``.
Packaging Debug and Release (MultiPackage)
==========================================
By default CMake is model is that a build directory only contains a single
configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo.
But it is possible to setup CPack to bundle multiple build directories at the
same time to build a package that contains multiple configurations of the
same project.
First we need to ahead and construct a directory called ``multi_config`` this
will contain all the builds that we want to package together.
Second create a ``debug`` and ``release`` directory underneath
``multi_config``. At the end you should have a layout that looks like:
─ multi_config
├── debug
└── release
Now we need to setup debug and release builds, which would roughly entail
the following:
.. code-block:: console
cd debug
cmake -DCMAKE_BUILD_TYPE=Debug ../../MultiPackage/
cmake --build .
cd ../release
cmake -DCMAKE_BUILD_TYPE=Release ../../MultiPackage/
cmake --build .
cd ..
Now that both the debug and release builds are complete we can now use
the custom MultiCPackConfig to package both builds into a single release.
.. code-block:: console
cpack --config ../../MultiPackage/MultiCPackConfig.cmake