该文档是基于CMake的官方教程翻译而来,并稍微添加了自己的理解:
cmake的官方网站为:CMake Tutorial
The CMake tutorial provides a step-by-step guide that covers common build system issues that CMake helps address. Seeing how various topics all work together in an example project can be very helpful.
CMake 教程提供了一个循序渐进的指南,涵盖了 CMake 可帮助解决的常见构建系统问题。在一个示例项目中了解各个主题是如何协同工作的,会非常有帮助。
The tutorial source code examples are available in this archive. Each step has its own subdirectory containing code that may be used as a starting point. The tutorial examples are progressive so that each step provides the complete solution for the previous step.
本文档中提供了教程源代码示例。每个步骤都有自己的子目录,其中包含可用作起点的代码。教程示例是循序渐进的,因此每一步都提供了前一步的完整解决方案。
Note: This example is valid for single-configuration generators and will not work for multi-configuration generators (e.g. Visual Studio).
注:本例适用于单配置生成器,不适用于多配置生成器(如 Visual Studio)。
By default, CMake’s model is that a build directory only contains a single configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. It is possible, however, to setup CPack to bundle multiple build directories and construct a package that contains multiple configurations of the same project.
默认情况下,CMake 的模型是一个联编目录只包含一个配置,无论是 Debug、Release、MinSizeRel 还是 RelWithDebInfo。不过,可以通过设置 CPack 来捆绑多个编译目录,并构建一个包含同一项目多个配置的软件包。
First, we want to ensure that the debug and release builds use different names for the libraries that will be installed. Let’s use d as the postfix for the debug libraries.
首先,我们要确保调试版本和发行版本使用不同的名称来命名将要安装的库。让我们使用 d 作为调试库的后缀。
Set CMAKE_DEBUG_POSTFIX near the beginning of the top-level CMakeLists.txt file:
在顶层 CMakeLists.txt
文件的开头附近设置 CMAKE_DEBUG_POSTFIX
:
CMakeLists.txt
set(CMAKE_DEBUG_POSTFIX d)
add_library(tutorial_compiler_flags INTERFACE)
And the DEBUG_POSTFIX property on the tutorial executable:
以及tutorial可执行文件的 DEBUG_POSTFIX 属性:
CMakeLists.txt
add_executable(Tutorial tutorial.cxx)
set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX})
target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags)
Let’s also add version numbering to the MathFunctions library. In MathFunctions/CMakeLists.txt
, set the VERSION and SOVERSION properties:
我们还要为 MathFunctions
库添加版本号。在 MathFunctions/CMakeLists.txt
中,设置 VERSION
和 SOVERSION
属性:
MathFunctions/CMakeLists.txt
set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
From the Step12 directory, create debug and release subdirectories. The layout will look like:
从 Step12_build 目录创建调试和发布子目录。布局如下
- mkdir Step12_build
- Step12_build
- debug
- release
Now we need to setup debug and release builds. We can use CMAKE_BUILD_TYPE to set the configuration type:
现在我们需要设置debug和release版本。我们可以使用 CMAKE_BUILD_TYPE
来设置配置类型:
cd Step12_build
cd debug
cmake -DCMAKE_BUILD_TYPE=Debug ../../Step12
cmake --build .
cd ../release
cmake -DCMAKE_BUILD_TYPE=Release ../../Step12
cmake --build .
Now that both the debug and release builds are complete, we can use a custom configuration file to package both builds into a single release. In the Step12 directory, create a file called MultiCPackConfig.cmake. In this file, first include the default configuration file that was created by the cmake executable.
现在debug和release版本都已完成,我们可以使用用户自定义配置文件将两个版本打包成一个发布版本。在 Step12 目录中,创建一个名为 MultiCPackConfig.cmake 的文件。在该文件中,首先包含 cmake 可执行文件创建的默认配置文件。
Next, use the CPACK_INSTALL_CMAKE_PROJECTS variable to specify which projects to install. In this case, we want to install both debug and release.
接下来,使用 CPACK_INSTALL_CMAKE_PROJECTS
变量指定要安装的项目。在本例中,我们要同时安装debug和release版本。
MultiCPackConfig.cmake
include("release/CPackConfig.cmake")
set(CPACK_INSTALL_CMAKE_PROJECTS
"debug;Tutorial;ALL;/"
"release;Tutorial;ALL;/"
)
From the Step12_build directory, run cpack specifying our custom configuration file with the config option:
在 Step12_build 目录下运行 cpack,使用 config 选项指定我们的自定义配置文件:
cpack --config ../Step12/MultiCPackConfig.cmake
cmake_minimum_required(VERSION 3.15)
# set the project name and version
project(Tutorial VERSION 1.0)
set(CMAKE_DEBUG_POSTFIX d)
add_library(tutorial_compiler_flags INTERFACE)
target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
# add compiler warning flags just when building this project via
# the BUILD_INTERFACE genex
set(gcc_like_cxx "$" )
set(msvc_cxx "$" )
target_compile_options(tutorial_compiler_flags INTERFACE
"$<${gcc_like_cxx}:$>"
"$<${msvc_cxx}:$>"
)
# 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}")
option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
if(APPLE)
set(CMAKE_INSTALL_RPATH "@executable_path/../lib")
elseif(UNIX)
set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib")
endif()
# configure a header file to pass the version number only
configure_file(TutorialConfig.h.in TutorialConfig.h)
# add the MathFunctions library
add_subdirectory(MathFunctions)
# add the executable
add_executable(Tutorial tutorial.cxx)
set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX})
target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags)
# 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}"
)
# add the install targets
install(TARGETS Tutorial DESTINATION bin)
install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h"
DESTINATION include
)
# 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 a bunch of result based tests
do_test(Tutorial 4 "4 is 2")
do_test(Tutorial 9 "9 is 3")
do_test(Tutorial 5 "5 is 2.236")
do_test(Tutorial 7 "7 is 2.645")
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}")
set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
include(CPack)
# install the configuration targets
install(EXPORT MathFunctionsTargets
FILE MathFunctionsTargets.cmake
DESTINATION lib/cmake/MathFunctions
)
include(CMakePackageConfigHelpers)
# generate the config file that 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 generated configuration files
install(FILES
${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake
${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake
DESTINATION lib/cmake/MathFunctions
)
# 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"
)
# 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
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
$<INSTALL_INTERFACE:include>
)
set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
# should we use our own math functions
option(USE_MYMATH "Use tutorial provided math implementation" ON)
if(USE_MYMATH)
target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
include(MakeTable.cmake) # generates Table.h
# 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}
)
# state that SqrtLibrary need PIC when the default is shared libraries
set_target_properties(SqrtLibrary PROPERTIES
POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
)
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif()
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# define the symbol stating we are using the declspec(dllexport) when
# building on windows
target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
# install libs
set(installable_libs MathFunctions tutorial_compiler_flags)
if(TARGET SqrtLibrary)
list(APPEND installable_libs SqrtLibrary)
endif()
install(TARGETS ${installable_libs}
EXPORT MathFunctionsTargets
DESTINATION lib)
# install include headers
install(FILES MathFunctions.h DESTINATION include)
test@test:~/sda3/work/cmake/Step12_build$ tree
.
├── debug
│ ├── CMakeCache.txt
│ ├── CMakeFiles
│ │ ├── 3.22.3
│ │ │ ├── CMakeCCompiler.cmake
│ │ │ ├── CMakeCXXCompiler.cmake
│ │ │ ├── CMakeDetermineCompilerABI_C.bin
│ │ │ ├── CMakeDetermineCompilerABI_CXX.bin
│ │ │ ├── CMakeSystem.cmake
│ │ │ ├── CompilerIdC
│ │ │ │ ├── a.out
│ │ │ │ ├── CMakeCCompilerId.c
│ │ │ │ └── tmp
│ │ │ └── CompilerIdCXX
│ │ │ ├── a.out
│ │ │ ├── CMakeCXXCompilerId.cpp
│ │ │ └── tmp
│ │ ├── cmake.check_cache
│ │ ├── CMakeDirectoryInformation.cmake
│ │ ├── CMakeOutput.log
│ │ ├── CMakeRuleHashes.txt
│ │ ├── CMakeTmp
│ │ ├── Export
│ │ │ └── lib
│ │ │ └── cmake
│ │ │ └── MathFunctions
│ │ │ ├── MathFunctionsTargets.cmake
│ │ │ └── MathFunctionsTargets-debug.cmake
│ │ ├── Makefile2
│ │ ├── Makefile.cmake
│ │ ├── progress.marks
│ │ ├── TargetDirectories.txt
│ │ └── Tutorial.dir
│ │ ├── build.make
│ │ ├── cmake_clean.cmake
│ │ ├── compiler_depend.make
│ │ ├── compiler_depend.ts
│ │ ├── DependInfo.cmake
│ │ ├── depend.make
│ │ ├── flags.make
│ │ ├── link.txt
│ │ ├── progress.make
│ │ ├── tutorial.cxx.o
│ │ └── tutorial.cxx.o.d
│ ├── cmake_install.cmake
│ ├── CPackConfig.cmake
│ ├── CPackSourceConfig.cmake
│ ├── CTestTestfile.cmake
│ ├── libMathFunctionsd.so -> libMathFunctionsd.so.1
│ ├── libMathFunctionsd.so.1 -> libMathFunctionsd.so.1.0.0
│ ├── libMathFunctionsd.so.1.0.0
│ ├── libSqrtLibraryd.a
│ ├── Makefile
│ ├── MakeTable
│ ├── MathFunctions
│ │ ├── CMakeFiles
│ │ │ ├── CMakeDirectoryInformation.cmake
│ │ │ ├── MakeTable.dir
│ │ │ │ ├── build.make
│ │ │ │ ├── cmake_clean.cmake
│ │ │ │ ├── compiler_depend.make
│ │ │ │ ├── compiler_depend.ts
│ │ │ │ ├── DependInfo.cmake
│ │ │ │ ├── depend.make
│ │ │ │ ├── flags.make
│ │ │ │ ├── link.txt
│ │ │ │ ├── MakeTable.cxx.o
│ │ │ │ ├── MakeTable.cxx.o.d
│ │ │ │ └── progress.make
│ │ │ ├── MathFunctions.dir
│ │ │ │ ├── build.make
│ │ │ │ ├── cmake_clean.cmake
│ │ │ │ ├── compiler_depend.make
│ │ │ │ ├── compiler_depend.ts
│ │ │ │ ├── DependInfo.cmake
│ │ │ │ ├── depend.make
│ │ │ │ ├── flags.make
│ │ │ │ ├── link.txt
│ │ │ │ ├── MathFunctions.cxx.o
│ │ │ │ ├── MathFunctions.cxx.o.d
│ │ │ │ └── progress.make
│ │ │ ├── progress.marks
│ │ │ └── SqrtLibrary.dir
│ │ │ ├── build.make
│ │ │ ├── cmake_clean.cmake
│ │ │ ├── cmake_clean_target.cmake
│ │ │ ├── compiler_depend.make
│ │ │ ├── compiler_depend.ts
│ │ │ ├── DependInfo.cmake
│ │ │ ├── depend.make
│ │ │ ├── flags.make
│ │ │ ├── link.txt
│ │ │ ├── mysqrt.cxx.o
│ │ │ ├── mysqrt.cxx.o.d
│ │ │ └── progress.make
│ │ ├── cmake_install.cmake
│ │ ├── Makefile
│ │ └── Table.h
│ ├── MathFunctionsConfig.cmake
│ ├── MathFunctionsConfigVersion.cmake
│ ├── MathFunctionsTargets.cmake
│ ├── TutorialConfig.h
│ └── Tutoriald
└── release
├── CMakeCache.txt
├── CMakeFiles
│ ├── 3.22.3
│ │ ├── CMakeCCompiler.cmake
│ │ ├── CMakeCXXCompiler.cmake
│ │ ├── CMakeDetermineCompilerABI_C.bin
│ │ ├── CMakeDetermineCompilerABI_CXX.bin
│ │ ├── CMakeSystem.cmake
│ │ ├── CompilerIdC
│ │ │ ├── a.out
│ │ │ ├── CMakeCCompilerId.c
│ │ │ └── tmp
│ │ └── CompilerIdCXX
│ │ ├── a.out
│ │ ├── CMakeCXXCompilerId.cpp
│ │ └── tmp
│ ├── cmake.check_cache
│ ├── CMakeDirectoryInformation.cmake
│ ├── CMakeOutput.log
│ ├── CMakeRuleHashes.txt
│ ├── CMakeTmp
│ ├── Export
│ │ └── lib
│ │ └── cmake
│ │ └── MathFunctions
│ │ ├── MathFunctionsTargets.cmake
│ │ └── MathFunctionsTargets-release.cmake
│ ├── Makefile2
│ ├── Makefile.cmake
│ ├── progress.marks
│ ├── TargetDirectories.txt
│ └── Tutorial.dir
│ ├── build.make
│ ├── cmake_clean.cmake
│ ├── compiler_depend.make
│ ├── compiler_depend.ts
│ ├── DependInfo.cmake
│ ├── depend.make
│ ├── flags.make
│ ├── link.txt
│ ├── progress.make
│ ├── tutorial.cxx.o
│ └── tutorial.cxx.o.d
├── cmake_install.cmake
├── CPackConfig.cmake
├── CPackSourceConfig.cmake
├── CTestTestfile.cmake
├── libMathFunctions.so -> libMathFunctions.so.1
├── libMathFunctions.so.1 -> libMathFunctions.so.1.0.0
├── libMathFunctions.so.1.0.0
├── libSqrtLibrary.a
├── Makefile
├── MakeTable
├── MathFunctions
│ ├── CMakeFiles
│ │ ├── CMakeDirectoryInformation.cmake
│ │ ├── MakeTable.dir
│ │ │ ├── build.make
│ │ │ ├── cmake_clean.cmake
│ │ │ ├── compiler_depend.make
│ │ │ ├── compiler_depend.ts
│ │ │ ├── DependInfo.cmake
│ │ │ ├── depend.make
│ │ │ ├── flags.make
│ │ │ ├── link.txt
│ │ │ ├── MakeTable.cxx.o
│ │ │ ├── MakeTable.cxx.o.d
│ │ │ └── progress.make
│ │ ├── MathFunctions.dir
│ │ │ ├── build.make
│ │ │ ├── cmake_clean.cmake
│ │ │ ├── compiler_depend.make
│ │ │ ├── compiler_depend.ts
│ │ │ ├── DependInfo.cmake
│ │ │ ├── depend.make
│ │ │ ├── flags.make
│ │ │ ├── link.txt
│ │ │ ├── MathFunctions.cxx.o
│ │ │ ├── MathFunctions.cxx.o.d
│ │ │ └── progress.make
│ │ ├── progress.marks
│ │ └── SqrtLibrary.dir
│ │ ├── build.make
│ │ ├── cmake_clean.cmake
│ │ ├── cmake_clean_target.cmake
│ │ ├── compiler_depend.make
│ │ ├── compiler_depend.ts
│ │ ├── DependInfo.cmake
│ │ ├── depend.make
│ │ ├── flags.make
│ │ ├── link.txt
│ │ ├── mysqrt.cxx.o
│ │ ├── mysqrt.cxx.o.d
│ │ └── progress.make
│ ├── cmake_install.cmake
│ ├── Makefile
│ └── Table.h
├── MathFunctionsConfig.cmake
├── MathFunctionsConfigVersion.cmake
├── MathFunctionsTargets.cmake
├── Tutorial
└── TutorialConfig.h
36 directories, 170 files
test@test:~/sda3/work/cmake/Step12_build$
test@test:~/sda3/work/cmake/Step12_build$ ls
_CPack_Packages debug release Tutorial-1.0-Linux.sh Tutorial-1.0-Linux.tar.gz Tutorial-1.0-Linux.tar.Z
test@test:~/sda3/work/cmake/Step12_build$
test@test:~/sda3/work/cmake/Step12_build$ ./debug/Tutoriald 100
Computing sqrt of 100 to be 50.5
Computing sqrt of 100 to be 26.2401
Computing sqrt of 100 to be 15.0255
Computing sqrt of 100 to be 10.8404
Computing sqrt of 100 to be 10.0326
Computing sqrt of 100 to be 10.0001
Computing sqrt of 100 to be 10
Computing sqrt of 100 to be 10
Computing sqrt of 100 to be 10
Computing sqrt of 100 to be 10
The square root of 100 is 10
test@test:~/sda3/work/cmake/Step12_build$ ./release/Tutorial 10000
Computing sqrt of 10000 to be 5000.5
Computing sqrt of 10000 to be 2501.25
Computing sqrt of 10000 to be 1252.62
Computing sqrt of 10000 to be 630.304
Computing sqrt of 10000 to be 323.084
Computing sqrt of 10000 to be 177.018
Computing sqrt of 10000 to be 116.755
Computing sqrt of 10000 to be 101.202
Computing sqrt of 10000 to be 100.007
Computing sqrt of 10000 to be 100
The square root of 10000 is 100
test@test:~/sda3/work/cmake/Step12_build$