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 ``-Wno-dev`` flag to
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
158 .. code-block:: console
162 The output of ``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 `-A` option:
201 .. code-block:: console
203 cmake .. -G "Visual Studio 2019" -A x64
204 cmake .. -G "Visual Studio 16" -A ARM
205 cmake .. -G "Visual Studio 16 2019" -A ARM64
207 On Apple, the :generator:`Xcode` generator may be used to
208 generate project files for the Xcode IDE.
210 Some IDEs such as KDevelop4, QtCreator and CLion have
211 native support for CMake-based buildsystems. Those IDEs
212 provide user interface for selecting an underlying
213 generator to use, typically a choice between a ``Makefile``
214 or a ``Ninja`` based generator.
216 Note that it is not possible to change the generator
217 with ``-G`` after the first invocation of CMake. To
218 change the generator, the build directory must be
219 deleted and the build must be started from scratch.
221 When generating Visual Studio project and solutions
222 files several other options are available to use when
223 initially running :manual:`cmake(1)`.
225 The Visual Studio toolset can be specified with the
228 .. code-block:: console
230 $ # Build with the clang-cl toolset
231 $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T ClangCL
232 $ # Build targeting Windows XP
233 $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T v120_xp
235 Whereas the ``-A`` option specifies the _target_
236 architecture, the ``-T`` option can be used to specify
237 details of the toolchain used. For example, `-Thost=x64`
238 can be given to select the 64-bit version of the host
239 tools. The following demonstrates how to use 64-bit
240 tools and also build for a 64-bit target architecture:
242 .. code-block:: console
244 $ cmake .. -G "Visual Studio 16 2019" -A x64 -Thost=x64
246 Choosing a generator in cmake-gui
247 ---------------------------------
249 The "Configure" button triggers a new dialog to
250 select the CMake generator to use.
252 .. image:: GUI-Configure-Dialog.png
253 :alt: Configuring a generator
255 All generators available on the command line are also
256 available in :manual:`cmake-gui(1)`.
258 .. image:: GUI-Choose-Generator.png
259 :alt: Choosing a generator
261 When choosing a Visual Studio generator, further options
262 are available to set an architecture to generate for.
264 .. image:: VS-Choose-Arch.png
265 :alt: Choosing an architecture for Visual Studio generators
267 .. _`Setting Build Variables`:
269 Setting Build Variables
270 =======================
272 Software projects often require variables to be
273 set on the command line when invoking CMake. Some of
274 the most commonly used CMake variables are listed in
277 ========================================== ============================================================
279 ========================================== ============================================================
280 :variable:`CMAKE_PREFIX_PATH` Path to search for
281 :guide:`dependent packages <Using Dependencies Guide>`
282 :variable:`CMAKE_MODULE_PATH` Path to search for additional CMake modules
283 :variable:`CMAKE_BUILD_TYPE` Build configuration, such as
284 ``Debug`` or ``Release``, determining
285 debug/optimization flags. This is only
286 relevant for single-configuration buildsystems such
287 as ``Makefile`` and ``Ninja``. Multi-configuration
288 buildsystems such as those for Visual Studio and Xcode
290 :variable:`CMAKE_INSTALL_PREFIX` Location to install the
292 ``install`` build target
293 :variable:`CMAKE_TOOLCHAIN_FILE` File containing cross-compiling
295 :manual:`toolchains and sysroots <cmake-toolchains(7)>`.
296 :variable:`BUILD_SHARED_LIBS` Whether to build shared
297 instead of static libraries
298 for :command:`add_library`
299 commands used without a type
300 :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` Generate a ``compile_commands.json``
301 file for use with clang-based tools
302 ========================================== ============================================================
304 Other project-specific variables may be available
305 to control builds, such as enabling or disabling
306 components of the project.
308 There is no convention provided by CMake for how
309 such variables are named between different
310 provided buildsystems, except that variables with
311 the prefix ``CMAKE_`` usually refer to options
312 provided by CMake itself and should not be used
313 in third-party options, which should use
314 their own prefix instead. The
315 :manual:`cmake-gui(1)` tool can display options
316 in groups defined by their prefix, so it makes
317 sense for third parties to ensure that they use a
318 self-consistent prefix.
320 Setting variables on the command line
321 -------------------------------------
323 CMake variables can be set on the command line either
324 when creating the initial build:
326 .. code-block:: console
330 $ cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug
332 or later on a subsequent invocation of
335 .. code-block:: console
338 $ cmake . -DCMAKE_BUILD_TYPE=Debug
340 The ``-U`` flag may be used to unset variables
341 on the :manual:`cmake(1)` command line:
343 .. code-block:: console
346 $ cmake . -UMyPackage_DIR
348 A CMake buildsystem which was initially created
349 on the command line can be modified using the
350 :manual:`cmake-gui(1)` and vice-versa.
352 The :manual:`cmake(1)` tool allows specifying a
353 file to use to populate the initial cache using
354 the ``-C`` option. This can be useful to simplify
355 commands and scripts which repeatedly require the
358 Setting variables with cmake-gui
359 --------------------------------
361 Variables may be set in the cmake-gui using the "Add Entry"
362 button. This triggers a new dialog to set the value of
365 .. image:: GUI-Add-Entry.png
366 :alt: Editing a cache entry
368 The main view of the :manual:`cmake-gui(1)` user interface
369 can be used to edit existing variables.
374 When CMake is executed, it needs to find the locations of
375 compilers, tools and dependencies. It also needs to be
376 able to consistently re-generate a buildsystem to use the
377 same compile/link flags and paths to dependencies. Such
378 parameters are also required to be configurable by the
379 user because they are paths and options specific to the
382 When it is first executed, CMake generates a
383 ``CMakeCache.txt`` file in the build directory containing
384 key-value pairs for such artifacts. The cache file can be
385 viewed or edited by the user by running the
386 :manual:`cmake-gui(1)` or :manual:`ccmake(1)` tool. The
387 tools provide an interactive interface for re-configuring
388 the provided software and re-generating the buildsystem,
389 as is needed after editing cached values. Each cache
390 entry may have an associated short help text which is
391 displayed in the user interface tools.
393 The cache entries may also have a type to signify how it
394 should be presented in the user interface. For example,
395 a cache entry of type ``BOOL`` can be edited by a
396 checkbox in a user interface, a ``STRING`` can be edited
397 in a text field, and a ``FILEPATH`` while similar to a
398 ``STRING`` should also provide a way to locate filesystem
399 paths using a file dialog. An entry of type ``STRING``
400 may provide a restricted list of allowed values which are
401 then provided in a drop-down menu in the
402 :manual:`cmake-gui(1)` user interface (see the
403 :prop_cache:`STRINGS` cache property).
405 The CMake files shipped with a software package may also
406 define boolean toggle options using the :command:`option`
407 command. The command creates a cache entry which has a
408 help text and a default value. Such cache entries are
409 typically specific to the provided software and affect
410 the configuration of the build, such as whether tests
411 and examples are built, whether to build with exceptions
417 CMake understands a file, ``CMakePresets.json``, and its
418 user-specific counterpart, ``CMakeUserPresets.json``, for
419 saving presets for commonly-used configure settings. These
420 presets can set the build directory, generator, cache
421 variables, environment variables, and other command-line
422 options. All of these options can be overridden by the
423 user. The full details of the ``CMakePresets.json`` format
424 are listed in the :manual:`cmake-presets(7)` manual.
426 Using presets on the command-line
427 ---------------------------------
429 When using the :manual:`cmake(1)` command line tool, a
430 preset can be invoked by using the ``--preset`` option. If
431 ``--preset`` is specified, the generator and build
432 directory are not required, but can be specified to
433 override them. For example, if you have the following
434 ``CMakePresets.json`` file:
440 "configurePresets": [
442 "name": "ninja-release",
443 "binaryDir": "${sourceDir}/build/${presetName}",
444 "generator": "Ninja",
446 "CMAKE_BUILD_TYPE": "Release"
452 and you run the following:
454 .. code-block:: console
456 cmake -S /path/to/source --preset=ninja-release
458 This will generate a build directory in
459 ``/path/to/source/build/ninja-release`` with the
460 :generator:`Ninja` generator, and with
461 :variable:`CMAKE_BUILD_TYPE` set to ``Release``.
463 If you want to see the list of available presets, you can
466 .. code-block:: console
468 cmake -S /path/to/source --list-presets
470 This will list the presets available in
471 ``/path/to/source/CMakePresets.json`` and
472 ``/path/to/source/CMakeUsersPresets.json`` without
473 generating a build tree.
475 Using presets in cmake-gui
476 --------------------------
478 If a project has presets available, either through
479 ``CMakePresets.json`` or ``CMakeUserPresets.json``, the
480 list of presets will appear in a drop-down menu in
481 :manual:`cmake-gui(1)` between the source directory and
482 the binary directory. Choosing a preset sets the binary
483 directory, generator, environment variables, and cache
484 variables, but all of these options can be overridden after
485 a preset is selected.
487 Invoking the Buildsystem
488 ========================
490 After generating the buildsystem, the software can be
491 built by invoking the particular build tool. In the
492 case of the IDE generators, this can involve loading
493 the generated project file into the IDE to invoke the
496 CMake is aware of the specific build tool needed to invoke
497 a build so in general, to build a buildsystem or project
498 from the command line after generating, the following
499 command may be invoked in the build directory:
501 .. code-block:: console
505 The ``--build`` flag enables a particular mode of
506 operation for the :manual:`cmake(1)` tool. It invokes
507 the :variable:`CMAKE_MAKE_PROGRAM` command associated
508 with the :manual:`generator <cmake-generators(7)>`, or
509 the build tool configured by the user.
511 The ``--build`` mode also accepts the parameter
512 ``--target`` to specify a particular target to build,
513 for example a particular library, executable or
514 custom target, or a particular special target like
517 .. code-block:: console
519 $ cmake --build . --target myexe
521 The ``--build`` mode also accepts a ``--config`` parameter
522 in the case of multi-config generators to specify which
523 particular configuration to build:
525 .. code-block:: console
527 $ cmake --build . --target myexe --config Release
529 The ``--config`` option has no effect if the generator
530 generates a buildsystem specific to a configuration which
531 is chosen when invoking cmake with the
532 :variable:`CMAKE_BUILD_TYPE` variable.
534 Some buildsystems omit details of command lines invoked
535 during the build. The ``--verbose`` flag can be used to
536 cause those command lines to be shown:
538 .. code-block:: console
540 $ cmake --build . --target myexe --verbose
542 The ``--build`` mode can also pass particular command
543 line options to the underlying build tool by listing
544 them after ``--``. This can be useful to specify
545 options to the build tool, such as to continue the
546 build after a failed job, where CMake does not
547 provide a high-level user interface.
549 For all generators, it is possible to run the underlying
550 build tool after invoking CMake. For example, ``make``
551 may be executed after generating with the
552 :generator:`Unix Makefiles` generator to invoke the build,
553 or ``ninja`` after generating with the :generator:`Ninja`
554 generator etc. The IDE buildsystems usually provide
555 command line tooling for building a project which can
561 Each executable and library described in the CMake files
562 is a build target, and the buildsystem may describe
563 custom targets, either for internal use, or for user
564 consumption, for example to create documentation.
566 CMake provides some built-in targets for all buildsystems
567 providing CMake files.
570 The default target used by ``Makefile`` and ``Ninja``
571 generators. Builds all targets in the buildsystem,
572 except those which are excluded by their
573 :prop_tgt:`EXCLUDE_FROM_ALL` target property or
574 :prop_dir:`EXCLUDE_FROM_ALL` directory property. The
575 name ``ALL_BUILD`` is used for this purpose for the
576 Xcode and Visual Studio generators.
578 Lists the targets available for build. This target is
579 available when using the :generator:`Unix Makefiles` or
580 :generator:`Ninja` generator, and the exact output is
583 Delete built object files and other output files. The
584 ``Makefile`` based generators create a ``clean`` target
585 per directory, so that an individual directory can be
586 cleaned. The ``Ninja`` tool provides its own granular
589 Runs tests. This target is only automatically available
590 if the CMake files provide CTest-based tests. See also
593 Installs the software. This target is only automatically
594 available if the software defines install rules with the
595 :command:`install` command. See also
596 `Software Installation`_.
598 Creates a binary package. This target is only
599 automatically available if the CMake files provide
600 CPack-based packages.
602 Creates a source package. This target is only
603 automatically available if the CMake files provide
604 CPack-based packages.
606 For ``Makefile`` based systems, ``/fast`` variants of binary
607 build targets are provided. The ``/fast`` variants are used
608 to build the specified target without regard for its
609 dependencies. The dependencies are not checked and
610 are not rebuilt if out of date. The :generator:`Ninja`
611 generator is sufficiently fast at dependency checking that
612 such targets are not provided for that generator.
614 ``Makefile`` based systems also provide build-targets to
615 preprocess, assemble and compile individual files in a
616 particular directory.
618 .. code-block:: console
624 The file extension is built into the name of the target
625 because another file with the same name but a different
626 extension may exist. However, build-targets without the
627 file extension are also provided.
629 .. code-block:: console
635 In buildsystems which contain ``foo.c`` and ``foo.cpp``,
636 building the ``foo.i`` target will preprocess both files.
638 Specifying a Build Program
639 --------------------------
641 The program invoked by the ``--build`` mode is determined
642 by the :variable:`CMAKE_MAKE_PROGRAM` variable. For most
643 generators, the particular program does not need to be
646 ===================== =========================== ===========================
647 Generator Default make program Alternatives
648 ===================== =========================== ===========================
650 Unix Makefiles ``make``
651 NMake Makefiles ``nmake`` ``jom``
652 NMake Makefiles JOM ``jom`` ``nmake``
653 MinGW Makefiles ``mingw32-make``
654 MSYS Makefiles ``make``
656 Visual Studio ``msbuild``
657 Watcom WMake ``wmake``
658 ===================== =========================== ===========================
660 The ``jom`` tool is capable of reading makefiles of the
661 ``NMake`` flavor and building in parallel, while the
662 ``nmake`` tool always builds serially. After generating
663 with the :generator:`NMake Makefiles` generator a user
664 can run ``jom`` instead of ``nmake``. The ``--build``
665 mode would also use ``jom`` if the
666 :variable:`CMAKE_MAKE_PROGRAM` was set to ``jom`` while
667 using the :generator:`NMake Makefiles` generator, and
668 as a convenience, the :generator:`NMake Makefiles JOM`
669 generator is provided to find ``jom`` in the normal way
670 and use it as the :variable:`CMAKE_MAKE_PROGRAM`. For
671 completeness, ``nmake`` is an alternative tool which
672 can process the output of the
673 :generator:`NMake Makefiles JOM` generator, but doing
674 so would be a pessimisation.
676 Software Installation
677 =====================
679 The :variable:`CMAKE_INSTALL_PREFIX` variable can be
680 set in the CMake cache to specify where to install the
681 provided software. If the provided software has install
682 rules, specified using the :command:`install` command,
683 they will install artifacts into that prefix. On Windows,
684 the default installation location corresponds to the
685 ``ProgramFiles`` system directory which may be
686 architecture specific. On Unix hosts, ``/usr/local`` is
687 the default installation location.
689 The :variable:`CMAKE_INSTALL_PREFIX` variable always
690 refers to the installation prefix on the target
693 In cross-compiling or packaging scenarios where the
694 sysroot is read-only or where the sysroot should otherwise
695 remain pristine, the :variable:`CMAKE_STAGING_PREFIX`
696 variable can be set to a location to actually install
701 .. code-block:: console
703 $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local \
704 -DCMAKE_SYSROOT=$HOME/root \
705 -DCMAKE_STAGING_PREFIX=/tmp/package
707 $ cmake --build . --target install
709 result in files being installed to paths such
710 as ``/tmp/package/lib/libfoo.so`` on the host machine.
711 The ``/usr/local`` location on the host machine is
714 Some provided software may specify ``uninstall`` rules,
715 but CMake does not generate such rules by default itself.
720 The :manual:`ctest(1)` tool is shipped with the CMake
721 distribution to execute provided tests and report
722 results. The ``test`` build-target is provided to run
723 all available tests, but the :manual:`ctest(1)` tool
724 allows granular control over which tests to run, how to
725 run them, and how to report results. Executing
726 :manual:`ctest(1)` in the build directory is equivalent
727 to running the ``test`` target:
729 .. code-block:: console
733 A regular expression can be passed to run only tests
734 which match the expression. To run only tests with
735 ``Qt`` in their name:
737 .. code-block:: console
741 Tests can be excluded by regular expression too. To
742 run only tests without ``Qt`` in their name:
744 .. code-block:: console
748 Tests can be run in parallel by passing ``-j`` arguments
749 to :manual:`ctest(1)`:
751 .. code-block:: console
755 The environment variable :envvar:`CTEST_PARALLEL_LEVEL`
756 can alternatively be set to avoid the need to pass
759 By default :manual:`ctest(1)` does not print the output
760 from the tests. The command line argument ``-V`` (or
761 ``--verbose``) enables verbose mode to print the
762 output from all tests.
763 The ``--output-on-failure`` option prints the test
764 output for failing tests only. The environment variable
765 :envvar:`CTEST_OUTPUT_ON_FAILURE`
766 can be set to ``1`` as an alternative to passing the
767 ``--output-on-failure`` option to :manual:`ctest(1)`.