11 Where a software package supplies a CMake-based buildsystem
12 with the source of their software, the consumer of the
13 software is required to run a CMake user interaction tool
16 Well-behaved CMake-based buildsystems do not create any
17 output in the source directory, so typically, the user
18 performs an out-of-source build and performs the build
19 there. First, CMake must be instructed to generate a
20 suitable buildsystem, then the user invokes a build tool
21 to process that generated buildsystem. The generated
22 buildsystem is specific to the machine used to generate
23 it and is not redistributable. Each consumer of a provided
24 source software package is required to use CMake to
25 generate a buildsystem specific to their system.
27 Generated buildsystems should generally be treated as
28 read-only. The CMake files as a primary artifact should
29 completely specify the buildsystem and there should be no
30 reason to populate properties manually in an IDE for
31 example after generating the buildsystem. CMake will
32 periodically rewrite the generated buildsystem, so
33 modifications by users will be overwritten.
35 The features and user interfaces described in this manual
36 are available for all CMake-based build systems by virtue
37 of providing CMake files.
39 The CMake tooling may report errors to the user when
40 processing provided CMake files, such as reporting that
41 the compiler is not supported, or the compiler does not
42 support a required compile option, or a dependency can
43 not be found. These errors must be resolved by the user
44 by choosing a different compiler,
45 :guide:`installing dependencies <Using Dependencies Guide>`,
46 or instructing CMake where to find them, etc.
48 Command Line cmake tool
49 -----------------------
51 A simple but typical use of :manual:`cmake(1)` with a fresh
52 copy of software source code is to create a build directory
53 and invoke cmake there:
55 .. code-block:: console
57 $ cd some_software-1.4.2
60 $ cmake .. -DCMAKE_INSTALL_PREFIX=/opt/the/prefix
62 $ cmake --build . --target install
64 It is recommended to build in a separate directory to the
65 source because that keeps the source directory pristine,
66 allows for building a single source with multiple
67 toolchains, and allows easy clearing of build artifacts by
68 simply deleting the build directory.
70 The CMake tooling may report warnings which are intended
71 for the provider of the software, not intended for the
72 consumer of the software. Such warnings end with "This
73 warning is for project developers". Users may disable
74 such warnings by passing the :option:`-Wno-dev <cmake -Wno-dev>`
75 flag to :manual:`cmake(1)`.
80 Users more accustomed to GUI interfaces may use the
81 :manual:`cmake-gui(1)` tool to invoke CMake and generate
84 The source and binary directories must first be
85 populated. It is always advised to use different
86 directories for the source and the build.
88 .. image:: GUI-Source-Binary.png
89 :alt: Choosing source and binary directories
91 Generating a Buildsystem
92 ========================
94 There are several user interface tools which may be used
95 to generate a buildsystem from CMake files. The
96 :manual:`ccmake(1)` and :manual:`cmake-gui(1)` tools guide
97 the user through setting the various necessary options.
98 The :manual:`cmake(1)` tool can be invoked to specify
99 options on the command line. This manual describes options
100 which may be set using any of the user interface tools,
101 though the mode of setting an option is different for each
104 Command line environment
105 ------------------------
107 When invoking :manual:`cmake(1)` with a command line
108 buildsystem such as ``Makefiles`` or ``Ninja``, it is
109 necessary to use the correct build environment to
110 ensure that build tools are available. CMake must be
111 able to find the appropriate
112 :variable:`build tool <CMAKE_MAKE_PROGRAM>`,
113 compiler, linker and other tools as needed.
115 On Linux systems, the appropriate tools are often
116 provided in system-wide locations and may be readily
117 installed through the system package manager. Other
118 toolchains provided by the user or installed in
119 non-default locations can also be used.
121 When cross-compiling, some platforms may require
122 environment variables to be set or may provide
123 scripts to set the environment.
125 Visual Studio ships multiple command prompts and
126 ``vcvarsall.bat`` scripts for setting up the
127 correct environments for command line buildsystems. While
128 not strictly necessary to use a corresponding
129 command line environment when using a Visual Studio
130 generator, doing so has no disadvantages.
132 When using Xcode, there can be more than one Xcode
133 version installed. Which one to use can be selected
134 in a number of different ways, but the most common
137 * Setting the default version in the preferences
139 * Setting the default version via the ``xcode-select``
141 * Overriding the default version by setting the
142 ``DEVELOPER_DIR`` environment variable when running
143 CMake and the build tool.
145 For convenience, :manual:`cmake-gui(1)` provides an
146 environment variable editor.
148 Command line ``-G`` option
149 --------------------------
151 CMake chooses a generator by default based on the
152 platform. Usually, the default generator is sufficient
153 to allow the user to proceed to build the software.
155 The user may override the default generator with
156 the :option:`-G <cmake -G>` option:
158 .. code-block:: console
162 The output of :option:`cmake --help` includes a list of
163 :manual:`generators <cmake-generators(7)>` available
164 for the user to choose from. Note that generator
165 names are case sensitive.
167 On Unix-like systems (including Mac OS X), the
168 :generator:`Unix Makefiles` generator is used by
169 default. A variant of that generator can also be used
170 on Windows in various environments, such as the
171 :generator:`NMake Makefiles` and
172 :generator:`MinGW Makefiles` generator. These generators
173 generate a ``Makefile`` variant which can be executed
174 with ``make``, ``gmake``, ``nmake`` or similar tools.
175 See the individual generator documentation for more
176 information on targeted environments and tools.
178 The :generator:`Ninja` generator is available on all
179 major platforms. ``ninja`` is a build tool similar
180 in use-cases to ``make``, but with a focus on
181 performance and efficiency.
183 On Windows, :manual:`cmake(1)` can be used to generate
184 solutions for the Visual Studio IDE. Visual Studio
185 versions may be specified by the product name of the
186 IDE, which includes a four-digit year. Aliases are
187 provided for other means by which Visual Studio
188 versions are sometimes referred to, such as two
189 digits which correspond to the product version of the
190 VisualC++ compiler, or a combination of the two:
192 .. code-block:: console
194 $ cmake .. -G "Visual Studio 2019"
195 $ cmake .. -G "Visual Studio 16"
196 $ cmake .. -G "Visual Studio 16 2019"
198 Visual Studio generators can target different architectures.
199 One can specify the target architecture using the
200 :option:`-A <cmake -A>` option:
202 .. code-block:: console
204 cmake .. -G "Visual Studio 2019" -A x64
205 cmake .. -G "Visual Studio 16" -A ARM
206 cmake .. -G "Visual Studio 16 2019" -A ARM64
208 On Apple, the :generator:`Xcode` generator may be used to
209 generate project files for the Xcode IDE.
211 Some IDEs such as KDevelop4, QtCreator and CLion have
212 native support for CMake-based buildsystems. Those IDEs
213 provide user interface for selecting an underlying
214 generator to use, typically a choice between a ``Makefile``
215 or a ``Ninja`` based generator.
217 Note that it is not possible to change the generator
218 with :option:`-G <cmake -G>` after the first invocation of CMake.
219 To change the generator, the build directory must be
220 deleted and the build must be started from scratch.
222 When generating Visual Studio project and solutions
223 files several other options are available to use when
224 initially running :manual:`cmake(1)`.
226 The Visual Studio toolset can be specified with the
227 :option:`cmake -T` option:
229 .. code-block:: console
231 $ # Build with the clang-cl toolset
232 $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T ClangCL
233 $ # Build targeting Windows XP
234 $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T v120_xp
236 Whereas the :option:`-A <cmake -A>` option specifies the _target_
237 architecture, the :option:`-T <cmake -T>` option can be used to specify
238 details of the toolchain used. For example, ``-Thost=x64``
239 can be given to select the 64-bit version of the host
240 tools. The following demonstrates how to use 64-bit
241 tools and also build for a 64-bit target architecture:
243 .. code-block:: console
245 $ cmake .. -G "Visual Studio 16 2019" -A x64 -Thost=x64
247 Choosing a generator in cmake-gui
248 ---------------------------------
250 The "Configure" button triggers a new dialog to
251 select the CMake generator to use.
253 .. image:: GUI-Configure-Dialog.png
254 :alt: Configuring a generator
256 All generators available on the command line are also
257 available in :manual:`cmake-gui(1)`.
259 .. image:: GUI-Choose-Generator.png
260 :alt: Choosing a generator
262 When choosing a Visual Studio generator, further options
263 are available to set an architecture to generate for.
265 .. image:: VS-Choose-Arch.png
266 :alt: Choosing an architecture for Visual Studio generators
268 .. _`Setting Build Variables`:
270 Setting Build Variables
271 =======================
273 Software projects often require variables to be
274 set on the command line when invoking CMake. Some of
275 the most commonly used CMake variables are listed in
278 ========================================== ============================================================
280 ========================================== ============================================================
281 :variable:`CMAKE_PREFIX_PATH` Path to search for
282 :guide:`dependent packages <Using Dependencies Guide>`
283 :variable:`CMAKE_MODULE_PATH` Path to search for additional CMake modules
284 :variable:`CMAKE_BUILD_TYPE` Build configuration, such as
285 ``Debug`` or ``Release``, determining
286 debug/optimization flags. This is only
287 relevant for single-configuration buildsystems such
288 as ``Makefile`` and ``Ninja``. Multi-configuration
289 buildsystems such as those for Visual Studio and Xcode
291 :variable:`CMAKE_INSTALL_PREFIX` Location to install the
293 ``install`` build target
294 :variable:`CMAKE_TOOLCHAIN_FILE` File containing cross-compiling
296 :manual:`toolchains and sysroots <cmake-toolchains(7)>`.
297 :variable:`BUILD_SHARED_LIBS` Whether to build shared
298 instead of static libraries
299 for :command:`add_library`
300 commands used without a type
301 :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` Generate a ``compile_commands.json``
302 file for use with clang-based tools
303 ========================================== ============================================================
305 Other project-specific variables may be available
306 to control builds, such as enabling or disabling
307 components of the project.
309 There is no convention provided by CMake for how
310 such variables are named between different
311 provided buildsystems, except that variables with
312 the prefix ``CMAKE_`` usually refer to options
313 provided by CMake itself and should not be used
314 in third-party options, which should use
315 their own prefix instead. The
316 :manual:`cmake-gui(1)` tool can display options
317 in groups defined by their prefix, so it makes
318 sense for third parties to ensure that they use a
319 self-consistent prefix.
321 Setting variables on the command line
322 -------------------------------------
324 CMake variables can be set on the command line either
325 when creating the initial build:
327 .. code-block:: console
331 $ cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug
333 or later on a subsequent invocation of
336 .. code-block:: console
339 $ cmake . -DCMAKE_BUILD_TYPE=Debug
341 The :option:`-U <cmake -U>` flag may be used to unset variables
342 on the :manual:`cmake(1)` command line:
344 .. code-block:: console
347 $ cmake . -UMyPackage_DIR
349 A CMake buildsystem which was initially created
350 on the command line can be modified using the
351 :manual:`cmake-gui(1)` and vice-versa.
353 The :manual:`cmake(1)` tool allows specifying a
354 file to use to populate the initial cache using
355 the :option:`-C <cmake -C>` option. This can be useful to simplify
356 commands and scripts which repeatedly require the
359 Setting variables with cmake-gui
360 --------------------------------
362 Variables may be set in the cmake-gui using the "Add Entry"
363 button. This triggers a new dialog to set the value of
366 .. image:: GUI-Add-Entry.png
367 :alt: Editing a cache entry
369 The main view of the :manual:`cmake-gui(1)` user interface
370 can be used to edit existing variables.
375 When CMake is executed, it needs to find the locations of
376 compilers, tools and dependencies. It also needs to be
377 able to consistently re-generate a buildsystem to use the
378 same compile/link flags and paths to dependencies. Such
379 parameters are also required to be configurable by the
380 user because they are paths and options specific to the
383 When it is first executed, CMake generates a
384 ``CMakeCache.txt`` file in the build directory containing
385 key-value pairs for such artifacts. The cache file can be
386 viewed or edited by the user by running the
387 :manual:`cmake-gui(1)` or :manual:`ccmake(1)` tool. The
388 tools provide an interactive interface for re-configuring
389 the provided software and re-generating the buildsystem,
390 as is needed after editing cached values. Each cache
391 entry may have an associated short help text which is
392 displayed in the user interface tools.
394 The cache entries may also have a type to signify how it
395 should be presented in the user interface. For example,
396 a cache entry of type ``BOOL`` can be edited by a
397 checkbox in a user interface, a ``STRING`` can be edited
398 in a text field, and a ``FILEPATH`` while similar to a
399 ``STRING`` should also provide a way to locate filesystem
400 paths using a file dialog. An entry of type ``STRING``
401 may provide a restricted list of allowed values which are
402 then provided in a drop-down menu in the
403 :manual:`cmake-gui(1)` user interface (see the
404 :prop_cache:`STRINGS` cache property).
406 The CMake files shipped with a software package may also
407 define boolean toggle options using the :command:`option`
408 command. The command creates a cache entry which has a
409 help text and a default value. Such cache entries are
410 typically specific to the provided software and affect
411 the configuration of the build, such as whether tests
412 and examples are built, whether to build with exceptions
418 CMake understands a file, ``CMakePresets.json``, and its
419 user-specific counterpart, ``CMakeUserPresets.json``, for
420 saving presets for commonly-used configure settings. These
421 presets can set the build directory, generator, cache
422 variables, environment variables, and other command-line
423 options. All of these options can be overridden by the
424 user. The full details of the ``CMakePresets.json`` format
425 are listed in the :manual:`cmake-presets(7)` manual.
427 Using presets on the command-line
428 ---------------------------------
430 When using the :manual:`cmake(1)` command line tool, a
431 preset can be invoked by using the :option:`--preset <cmake --preset>`
432 option. If :option:`--preset <cmake --preset>` is specified,
433 the generator and build directory are not required, but can be
434 specified to override them. For example, if you have the following
435 ``CMakePresets.json`` file:
441 "configurePresets": [
443 "name": "ninja-release",
444 "binaryDir": "${sourceDir}/build/${presetName}",
445 "generator": "Ninja",
447 "CMAKE_BUILD_TYPE": "Release"
453 and you run the following:
455 .. code-block:: console
457 cmake -S /path/to/source --preset=ninja-release
459 This will generate a build directory in
460 ``/path/to/source/build/ninja-release`` with the
461 :generator:`Ninja` generator, and with
462 :variable:`CMAKE_BUILD_TYPE` set to ``Release``.
464 If you want to see the list of available presets, you can
467 .. code-block:: console
469 cmake -S /path/to/source --list-presets
471 This will list the presets available in
472 ``/path/to/source/CMakePresets.json`` and
473 ``/path/to/source/CMakeUsersPresets.json`` without
474 generating a build tree.
476 Using presets in cmake-gui
477 --------------------------
479 If a project has presets available, either through
480 ``CMakePresets.json`` or ``CMakeUserPresets.json``, the
481 list of presets will appear in a drop-down menu in
482 :manual:`cmake-gui(1)` between the source directory and
483 the binary directory. Choosing a preset sets the binary
484 directory, generator, environment variables, and cache
485 variables, but all of these options can be overridden after
486 a preset is selected.
488 Invoking the Buildsystem
489 ========================
491 After generating the buildsystem, the software can be
492 built by invoking the particular build tool. In the
493 case of the IDE generators, this can involve loading
494 the generated project file into the IDE to invoke the
497 CMake is aware of the specific build tool needed to invoke
498 a build so in general, to build a buildsystem or project
499 from the command line after generating, the following
500 command may be invoked in the build directory:
502 .. code-block:: console
506 The :option:`--build <cmake --build>` flag enables a
507 particular mode of operation for the :manual:`cmake(1)`
508 tool. It invokes the :variable:`CMAKE_MAKE_PROGRAM`
509 command associated with the
510 :manual:`generator <cmake-generators(7)>`, or
511 the build tool configured by the user.
513 The :option:`--build <cmake --build>` mode also accepts
514 the parameter :option:`--target <cmake--build --target>` to
515 specify a particular target to build, for example a
516 particular library, executable or custom target, or a
517 particular special target like ``install``:
519 .. code-block:: console
521 $ cmake --build . --target myexe
523 The :option:`--build <cmake --build>` mode also accepts a
524 :option:`--config <cmake--build --config>` parameter
525 in the case of multi-config generators to specify which
526 particular configuration to build:
528 .. code-block:: console
530 $ cmake --build . --target myexe --config Release
532 The :option:`--config <cmake--build --config>` option has no
533 effect if the generator generates a buildsystem specific
534 to a configuration which is chosen when invoking cmake
535 with the :variable:`CMAKE_BUILD_TYPE` variable.
537 Some buildsystems omit details of command lines invoked
538 during the build. The :option:`--verbose <cmake--build --verbose>`
539 flag can be used to cause those command lines to be shown:
541 .. code-block:: console
543 $ cmake --build . --target myexe --verbose
545 The :option:`--build <cmake --build>` mode can also pass
546 particular command line options to the underlying build
547 tool by listing them after ``--``. This can be useful
548 to specify options to the build tool, such as to continue the
549 build after a failed job, where CMake does not
550 provide a high-level user interface.
552 For all generators, it is possible to run the underlying
553 build tool after invoking CMake. For example, ``make``
554 may be executed after generating with the
555 :generator:`Unix Makefiles` generator to invoke the build,
556 or ``ninja`` after generating with the :generator:`Ninja`
557 generator etc. The IDE buildsystems usually provide
558 command line tooling for building a project which can
564 Each executable and library described in the CMake files
565 is a build target, and the buildsystem may describe
566 custom targets, either for internal use, or for user
567 consumption, for example to create documentation.
569 CMake provides some built-in targets for all buildsystems
570 providing CMake files.
573 The default target used by ``Makefile`` and ``Ninja``
574 generators. Builds all targets in the buildsystem,
575 except those which are excluded by their
576 :prop_tgt:`EXCLUDE_FROM_ALL` target property or
577 :prop_dir:`EXCLUDE_FROM_ALL` directory property. The
578 name ``ALL_BUILD`` is used for this purpose for the
579 Xcode and Visual Studio generators.
581 Lists the targets available for build. This target is
582 available when using the :generator:`Unix Makefiles` or
583 :generator:`Ninja` generator, and the exact output is
586 Delete built object files and other output files. The
587 ``Makefile`` based generators create a ``clean`` target
588 per directory, so that an individual directory can be
589 cleaned. The ``Ninja`` tool provides its own granular
592 Runs tests. This target is only automatically available
593 if the CMake files provide CTest-based tests. See also
596 Installs the software. This target is only automatically
597 available if the software defines install rules with the
598 :command:`install` command. See also
599 `Software Installation`_.
601 Creates a binary package. This target is only
602 automatically available if the CMake files provide
603 CPack-based packages.
605 Creates a source package. This target is only
606 automatically available if the CMake files provide
607 CPack-based packages.
609 For ``Makefile`` based systems, ``/fast`` variants of binary
610 build targets are provided. The ``/fast`` variants are used
611 to build the specified target without regard for its
612 dependencies. The dependencies are not checked and
613 are not rebuilt if out of date. The :generator:`Ninja`
614 generator is sufficiently fast at dependency checking that
615 such targets are not provided for that generator.
617 ``Makefile`` based systems also provide build-targets to
618 preprocess, assemble and compile individual files in a
619 particular directory.
621 .. code-block:: console
627 The file extension is built into the name of the target
628 because another file with the same name but a different
629 extension may exist. However, build-targets without the
630 file extension are also provided.
632 .. code-block:: console
638 In buildsystems which contain ``foo.c`` and ``foo.cpp``,
639 building the ``foo.i`` target will preprocess both files.
641 Specifying a Build Program
642 --------------------------
644 The program invoked by the :option:`--build <cmake --build>`
645 mode is determined by the :variable:`CMAKE_MAKE_PROGRAM` variable.
646 For most generators, the particular program does not need to be
649 ===================== =========================== ===========================
650 Generator Default make program Alternatives
651 ===================== =========================== ===========================
653 Unix Makefiles ``make``
654 NMake Makefiles ``nmake`` ``jom``
655 NMake Makefiles JOM ``jom`` ``nmake``
656 MinGW Makefiles ``mingw32-make``
657 MSYS Makefiles ``make``
659 Visual Studio ``msbuild``
660 Watcom WMake ``wmake``
661 ===================== =========================== ===========================
663 The ``jom`` tool is capable of reading makefiles of the
664 ``NMake`` flavor and building in parallel, while the
665 ``nmake`` tool always builds serially. After generating
666 with the :generator:`NMake Makefiles` generator a user
667 can run ``jom`` instead of ``nmake``. The
668 :option:`--build <cmake --build>`
669 mode would also use ``jom`` if the
670 :variable:`CMAKE_MAKE_PROGRAM` was set to ``jom`` while
671 using the :generator:`NMake Makefiles` generator, and
672 as a convenience, the :generator:`NMake Makefiles JOM`
673 generator is provided to find ``jom`` in the normal way
674 and use it as the :variable:`CMAKE_MAKE_PROGRAM`. For
675 completeness, ``nmake`` is an alternative tool which
676 can process the output of the
677 :generator:`NMake Makefiles JOM` generator, but doing
678 so would be a pessimization.
680 Software Installation
681 =====================
683 The :variable:`CMAKE_INSTALL_PREFIX` variable can be
684 set in the CMake cache to specify where to install the
685 provided software. If the provided software has install
686 rules, specified using the :command:`install` command,
687 they will install artifacts into that prefix. On Windows,
688 the default installation location corresponds to the
689 ``ProgramFiles`` system directory which may be
690 architecture specific. On Unix hosts, ``/usr/local`` is
691 the default installation location.
693 The :variable:`CMAKE_INSTALL_PREFIX` variable always
694 refers to the installation prefix on the target
697 In cross-compiling or packaging scenarios where the
698 sysroot is read-only or where the sysroot should otherwise
699 remain pristine, the :variable:`CMAKE_STAGING_PREFIX`
700 variable can be set to a location to actually install
705 .. code-block:: console
707 $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local \
708 -DCMAKE_SYSROOT=$HOME/root \
709 -DCMAKE_STAGING_PREFIX=/tmp/package
711 $ cmake --build . --target install
713 result in files being installed to paths such
714 as ``/tmp/package/lib/libfoo.so`` on the host machine.
715 The ``/usr/local`` location on the host machine is
718 Some provided software may specify ``uninstall`` rules,
719 but CMake does not generate such rules by default itself.
724 The :manual:`ctest(1)` tool is shipped with the CMake
725 distribution to execute provided tests and report
726 results. The ``test`` build-target is provided to run
727 all available tests, but the :manual:`ctest(1)` tool
728 allows granular control over which tests to run, how to
729 run them, and how to report results. Executing
730 :manual:`ctest(1)` in the build directory is equivalent
731 to running the ``test`` target:
733 .. code-block:: console
737 A regular expression can be passed to run only tests
738 which match the expression. To run only tests with
739 ``Qt`` in their name:
741 .. code-block:: console
745 Tests can be excluded by regular expression too. To
746 run only tests without ``Qt`` in their name:
748 .. code-block:: console
752 Tests can be run in parallel by passing :option:`-j <ctest -j>`
753 arguments to :manual:`ctest(1)`:
755 .. code-block:: console
759 The environment variable :envvar:`CTEST_PARALLEL_LEVEL`
760 can alternatively be set to avoid the need to pass
761 :option:`-j <ctest -j>`.
763 By default :manual:`ctest(1)` does not print the output
764 from the tests. The command line argument :option:`-V <ctest -V>`
765 (or ``--verbose``) enables verbose mode to print the
766 output from all tests.
767 The :option:`--output-on-failure <ctest --output-on-failure>`
768 option prints the test output for failing tests only.
769 The environment variable :envvar:`CTEST_OUTPUT_ON_FAILURE`
770 can be set to ``1`` as an alternative to passing the
771 :option:`--output-on-failure <ctest --output-on-failure>`
772 option to :manual:`ctest(1)`.