View source for CMake

{{short description|Cross-platform build tool for configuring platform-specific builds}}
{{Use dmy dates|date=January 2022}}
{{Infobox software
| name = CMake
| logo = CMake logo.svg
| logo size = 96px
| screenshot = Cmake with Clang screenshot.png
| developer = Andy Cedilnik, Bill Hoffman, Brad King, Ken Martin, Alexander Neundorf
| released = {{Start date and age|2000}}
| latest release version = {{wikidata|property|preferred|references|edit|Q1023904|P348|P548=Q2804309}}
| latest release date = {{wikidata|qualifier|preferred|single|Q1023904|P348|P548=Q2804309|P577}}
| latest preview version = {{wikidata|property|preferred|references|edit|Q1023904|P348|P548=Q1072356}}
| latest preview date = {{wikidata|qualifier|preferred|single|Q1023904|P348|P548=Q1072356|P577}}
| programming language = [[C (programming language)|C]], [[C++]]<ref>{{cite web
 | url         = https://www.openhub.net/p/cmake
 | title       = The CMake Open Source Project on OpenHub
 | publisher   = OpenHub
 | access-date = 2016-04-09}}</ref>
| operating system = [[Cross-platform]]
| genre = [[Software development tools]]
| license = [[BSD licenses|BSD-3-Clause]]
}}

In [[software development]], '''CMake''' is [[cross-platform]] [[free and open-source software]] for [[build automation]], [[software testing|testing]], [[package (package management system)|packaging]] and [[Installation (computer programs)|installation]] of software by using a [[compiler]]-independent method.<ref>{{Cite web|url=https://cmake.org/|title=CMake}}</ref> CMake is not a build system itself; it generates another system's build files.<ref name=":1">{{Cite web |title=The Architecture of Open Source Applications (Volume 1)CMake |url=https://aosabook.org/en/v1/cmake.html |access-date=2023-06-11 |website=aosabook.org}}</ref> It supports directory hierarchies and applications that depend on multiple libraries. It can invoke native build environments such as [[make (software)|Make]], [[Qt Creator]], [[Ninja (build system)|Ninja]], [[Android Studio]], Apple's [[Xcode]], and [[Microsoft Visual Studio]].<ref name=":1" /> It has minimal dependencies, requiring only a [[C++]] compiler on its own build system.<ref name=":1" />

CMake is distributed as [[free and open-source software]] under a permissive [[BSD licenses|BSD-3-Clause]] license.<ref>{{Cite web|title=Licenses · master · CMake / CMake|url=https://gitlab.kitware.com/cmake/cmake/-/tree/master/Licenses|access-date=2020-11-13|website=GitLab|language=en}}</ref>

==History==
CMake development began in 1999, in response to the need for a cross-platform build environment for the [[Insight Segmentation and Registration Toolkit]] (ITK).<ref>{{cite web |title = FLOSS Weekly 111: CMake |url = http://twit.tv/floss111 |work = podcast |publisher = TWiT Network |access-date = 27 February 2011}}</ref><ref name=":1" /> The project is funded by the [[United States National Library of Medicine]] as part of the [[Visible Human Project]].<ref name=":1" /> It was partially inspired by {{Code|pcmaker}}, a predecessor to CMake, which was made by Ken Martin and other developers to support building of the [[VTK|Visualization Toolkit (VTK)]]. pcmaker was a C program that converted Make files into MS Windows' NMake counterparts.<ref name=":1" /> At [[Kitware]], Bill Hoffman blended components of pcmaker with his own ideas, striving to mimic the functionality of [[Unix]] [[configure script]]s. CMake was first implemented in 2000 and further developed in 2001.

Historically CMake was conceived with the following major features in mind:<ref name=":1" />

* depending only on system C++ compiler, meaning no third-party libraries
* to be able to generate Visual Studio IDE input files
* capable of producing executable and linkable binary libraries (static and shared)
* to be able to run build-time code generators
* separate source/build file trees
* system checks and introspection (similar to [[GNU Autotools|Autotools]]): what system could and could not do
* automatically scan C/C++ dependencies
* cross-platform

Because of these constraints CMake didn't choose to use [[Tcl]] (popular at the time) scripting language as its default and instead, developers decided to create a simpler scripting language.<ref name=":1" />

Continued development and improvements were fueled by the incorporation of CMake into developers’ own systems, including the [[VXL]] Project,{{clarify|date=August 2016}} the CABLE<ref>{{Cite web |url=http://public.kitware.com/Cable/HTML/Index.html |title=The CABLE |access-date=2010-11-10 |archive-url=https://web.archive.org/web/20130619224333/http://public.kitware.com/Cable/HTML/Index.html |archive-date=2013-06-19 |url-status=dead }}</ref> features added by Brad King,{{clarify|date=August 2016}} and [[GE Global Research|GE Corporate R&D]] for support of DART.{{clarify|date=August 2016}} Additional features were created when VTK transitioned to CMake for its build environment and for supporting [[ParaView]].

Version 3.0 was released in June 2014.<ref>{{Cite web|url=https://cmake.org/pipermail/cmake/2014-June/057793.html|title=[CMake] [ANNOUNCE] CMake 3.0.0 Released.|first=Robert|last=Maynard|date=June 10, 2014}}</ref> It has been described as the beginning of "Modern CMake".<ref>{{Cite web|url=https://gist.github.com/mbinna/c61dbb39bca0e4fb7d1f73b0d66a4fd1|title=Effective Modern CMake|website=Gist}}</ref> Experts now advise to avoid variables in favor of ''targets'' and ''properties''.<ref name=":0">{{Cite web |last=Binna |first=Manuel |date=Jul 22, 2018 |title=Effective Modern CMake |url=https://gist.github.com/mbinna/c61dbb39bca0e4fb7d1f73b0d66a4fd1}}</ref> The commands {{code|add_compile_options}}, {{code|include_directories}}, {{code|link_directories}}, {{code|link_libraries}} that were at the core of CMake 2 should now be replaced by target-specific commands.

Developer Brad King has stated that "the 'C' in CMake stands for 'cross-platform{{' "}}.<ref>https://public.kitware.com/Bug/view.php?id=14012#c32631 {{Bare URL inline|date=August 2024}}</ref>

==Features==

=== Separate build tree ===
One of its major features is the ability to place compiler outputs (such as object files) into a build tree which is located outside of the source tree.<ref name=":1" /> This enables multiple builds from the same source tree and [[cross-compilation]]. Separate source and build files ensure that removing a build directory will not affect source files and prevents clutter which might confuse version control systems.<ref name=":1" /> 

=== Dependency management ===
CMake keeps track and recompiles all the upstream dependencies of a given sub-module if its sources are changed.<ref name=":1" />{{Efn|Upstream dependencies - dependent sources that depend upon a modified source file}}

=== Flexible project structure ===
CMake can locate system-wide and user-specified executables, files, and libraries. These locations are stored in a [[cache (computing)|cache]], which can then be tailored before generating the target build files. The cache can be edited with a graphical editor, which is shipped with CMake.

Complicated directory hierarchies and applications that rely on several libraries are well supported by CMake. For instance, CMake is able to accommodate a project that has multiple toolkits, or libraries that each have multiple directories. In addition, CMake can work with projects that require executables to be created before generating code to be compiled for the final application. Its open-source, extensible design allows CMake to be adapted as necessary for specific projects.<ref name="kde">{{cite web |url = https://lwn.net/Articles/188693/ |title = Why the KDE project switched to CMake—and how |publisher = [[LWN.net]] |date = 2006-06-21 |last = Neundorf |first = Alexander}}</ref>

=== IDE configuration support ===
CMake can generate project files for several popular [[Integrated development environment|IDE]]s, such as [[Microsoft Visual Studio]], [[Xcode]], and [[Eclipse (software)|Eclipse CDT]]. It can also produce build scripts for MSBuild or NMake on Windows; [[Make (software)|Unix Make]] on Unix-like platforms such as [[Linux]], [[macOS]], and [[Cygwin]]; and [[Ninja (build system)|Ninja]] on both Windows and Unix-like platforms.

=== Compiler feature detection ===
CMake allows specification of features that the compiler is required to support in order to get the target program or library compiled.<ref>{{Cite web|date=2020-11-15|title=CMake compiler feature detect|url=https://www.scivision.dev/cmake-compiler-language-feature-detect/|access-date=2022-01-22|website=www.scivision.dev|language=en-us}}</ref>

=== Compilers ===
CMake supports an extensive list of compilers, including: Apple Clang, [[Clang]], [[GNU GCC]], [[Microsoft Visual C++|MSVC]], [[Oracle Developer Studio]], and [[Intel C++ Compiler]].<ref>{{Cite web|title=Supported Compilers|url=https://cmake.org/cmake/help/latest/manual/cmake-compile-features.7.html#supported-compilers|website=CMake Documentation|access-date=January 22, 2022}}</ref>

=== Packaging system ===
Even though CMake is not a [[package manager]], it provides basic modules (see CPack) functions for installing binaries and package information declared by the {{code|CMakeLists.txt}} script to be used by consumer CMake projects. The package may also be packed into an [[archive file]] for package manager or [[Installation (computer programs)#Installer|installer]] supported by a target platform. Third-party packages may also be imported via configured CMake files which are either provided by the same third-party or created manually.<ref>{{Cite book |last=Berner |first=Dominik |url=https://www.worldcat.org/oclc/1319218167 |title=CMake Best Practices : Discover Proven Techniques for Creating and Maintaining Programming Projects with CMake |date=2022 |publisher=Packt Publishing, Limited |others=Mustafa Kemal Gilor |isbn=978-1-80324-424-2 |location=Birmingham |oclc=1319218167}}</ref>{{Rp|pages=132,142}}<ref>{{Cite web |title=cmake-packages(7) — CMake 3.24.1 Documentation |url=https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html |access-date=2022-09-11 |website=cmake.org}}</ref><ref>{{Cite web |title=Exposing a module's configuration (advanced) — CMake build procedure 1.0 documentation |url=https://docs.salome-platform.org/latest/dev/cmake/html/config.html |access-date=2022-09-11 |website=docs.salome-platform.org}}</ref>

=== GUI ===
Cmake may be run by using a [[ncurses]] program like {{Code|ccmake}} that can be used to configure projects via command-line interface.

==Build process==
The build of a program or library with CMake is a two-stage process.<ref name=":1" /> First, build files (usually scripts) are created (generated) from configuration files (CMakeLists.txt scripts) written in [[#Language|CMake language]]. Then the platform's native build tools that can read these build files (native toolchain) are invoked either manually externally or via {{code|cmake --build}} for actual building of programs (build targets).<ref name="kde" /><ref>{{Cite web|title=cmake-toolchains(7) — CMake 3.19.0-rc2 Documentation|url=https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html|access-date=2020-10-29|website=cmake.org}}</ref> The generator specified by the user on the commandline determines which build tool chain to use.<ref name=":1" />

=== Generators ===
The build files are configured depending on the generator used (e.g. ''Unix Makefiles'' for [[Make (software)|make]]) and associated toolchain files. Advanced users can also create and incorporate additional makefile generators to support their specific compiler and OS needs. Generated files are typically placed (by using {{code|cmake}}'s flag) into a folder outside of the source's one (out of source build), e.g., {{code|build/}}.

Each build project in turn contains its own{{code|CMakeCache.txt}} file and {{code|CMakeFiles}} directory in every project (sub-)directory of included by the {{code|add_subdirectory(...)}} command, helping to avoid or speed up regeneration when it is run repeatedly.

The generation process and the output can be fine-tuned via target properties. Previously it was done via {{code|CMAKE_...}}-prefixed global  variables that are also used to configure CMake itself and to set up initial defaults.<ref name=":0" /><ref>{{Cite conference |last=Pfeifer |first=Daniel |date=May 19, 2017 |title=Effective Cmake |url=https://github.com/boostcon/cppnow_presentations_2017/blob/master/05-19-2017_friday/effective_cmake__daniel_pfeifer__cppnow_05-19-2017.pdf |conference=CPPNow}}</ref> The older approach is discouraged now.

=== Types of build targets ===
Depending on CMakeLists.txt configuration the build files may be either executables, libraries (e.g. {{Code|libxyz}}, {{Code|xyz.dll}} etc.), [[object file]] libraries or pseudo-targets (including aliases). CMake can produce object files that can be linked against by executable binaries/libraries, avoiding dynamic (run-time) linking and using static (compile-time) linking instead. This enables flexibility in configuration of various optimizations.<ref>{{Cite web|title=cmake-buildsystem(7) — CMake 3.19.0-rc3 Documentation|url=https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#object-libraries|access-date=2020-11-14|website=cmake.org}}</ref>

Build dependencies may be determined automatically.

=== Precompiled headers ===
It's possible to generate [[precompiled header]]s by using CMake since version 3.6.<ref>{{Cite web|title=target_precompile_headers — CMake 3.21.20210925-gb818e3c Documentation|url=https://cmake.org/cmake/help/git-stage/command/target_precompile_headers.html|access-date=2021-09-25|website=cmake.org}}</ref>

== {{Anchor|CMake language}}Language ==

=== CMakeLists.txt ===
CMake has a relatively simple [[Interpreted language|interpreted]], imperative scripting language. It supports variables, string manipulation methods, arrays, function/macro declarations, and module inclusion (importing). CMake Language commands (or directives) are read by {{code|cmake}} from a file named {{code|CMakeLists.txt}}.  This file specifies the source files and build parameters, which CMake will place in the project's build specification (such as a Makefile). Additionally, {{code|.cmake}}-suffixed files can contain scripts used by CMake.<ref>{{Cite web|title=cmake-language(7) — CMake 3.19.0-rc2 Documentation|url=https://cmake.org/cmake/help/latest/manual/cmake-language.7.html|access-date=2020-10-29|website=cmake.org}}</ref>

To generate a project's build files, one invokes {{code|cmake}} in terminal and specifies the directory that contains {{code|CMakeLists.txt}}. This file contains one or more commands in the form of {{code|COMMAND(argument ...)}}.

=== Command syntax ===
The arguments of the commands are [[Whitespace character|whitespace]]-separated&nbsp;and can include keywords to separate groups of arguments. Commands can take keywords. For instance, in the command {{code|SET_SOURCE_FILE_PROPERTIES(source_file ... COMPILE_FLAGS compiler_option ...)|lang=cmake}} the keyword is {{code|COMPILE_FLAGS}}. It serves as a delimiter between the list of source files and some other options.<ref>{{cite web|access-date=2021-01-29|url=https://www.linuxjournal.com/article/6700|title=Cross-Platform Software Development Using CMake Software|first=Andrej|last=Cedilnik|publisher=Linux Journal|publication-date=2003-10-30}}</ref>

Examples of commands that CMake offers to specify targets and their dependencies and which serve as the starting point of the CMakeLists.txt:<ref>{{Cite web|title=add_executable — CMake 3.19.0-rc1 Documentation|url=https://cmake.org/cmake/help/latest/command/add_executable.html|access-date=2020-10-25|website=cmake.org}}</ref><ref>{{Cite web|title=add_library — CMake 3.19.0-rc1 Documentation|url=https://cmake.org/cmake/help/latest/command/add_library.html|access-date=2020-10-25|website=cmake.org}}</ref><ref>{{Cite web|title=target_link_directories — CMake 3.20.2 Documentation|url=https://cmake.org/cmake/help/latest/command/target_link_directories.html|access-date=2021-05-10|website=cmake.org}}</ref>

* {{code|add_executable(...)|lang=cmake}}— declares an executable binary target with sources (depend on language chosen) to be built
* {{code|add_library(...)|lang=cmake}} — the same but for a library
* {{Code|target_link_libraries(...)||lang=cmake}} —  adds dependencies etc.

=== JSON strings ===
CMake supports extracting values into variables from [[JSON]]-data strings (since version 3.19).<ref>{{Cite web|title=CMake 3.19 Release Notes — CMake 3.19.7 Documentation|url=https://cmake.org/cmake/help/v3.19/release/3.19.html|access-date=2021-03-15|website=cmake.org}}</ref>

==Internals==
The CMake scripting language is implemented by using [[Yacc]] and [[Lex (software)|Lex]] generators.{{Efn|As evident from the CMake source code repository.|name=n0:}}

The executable programs CMake, CPack, and CTest are written in the [[C++]] programming language.{{Efn|name=n0:}}

Much of CMake's functionality is implemented in modules that are written in the [[#Language|CMake language]].<ref>{{Cite web|title=cmake-language(7) — CMake 3.19.0-rc1 Documentation|url=https://cmake.org/cmake/help/latest/manual/cmake-language.7.html|access-date=2020-10-25|website=cmake.org}}</ref>

Since release 3.0, CMake's documentation uses [[reStructuredText]] markup. HTML pages and man pages are generated by the [[Sphinx (documentation generator)|Sphinx]] documentation generator.

== Modules and tools ==
CMake ships with numerous {{code|.cmake}} modules and tools. These facilitate work such as finding dependencies (both built-in and external, e.g. {{code|FindXYZ}} modules), testing the toolchain environment and executables, packaging releases ({{code|CPack}} module and {{code|cpack}} command), and managing dependencies on external projects ({{code|ExternalProject}} module):<ref>{{Cite web |title=cmake-modules(7) — CMake 3.14.7 Documentation |url=https://cmake.org/cmake/help/v3.14/manual/cmake-modules.7.html |access-date=2020-10-24 |website=cmake.org}}</ref><ref>{{Cite web |title=ExternalProject — CMake 3.14.7 Documentation |url=https://cmake.org/cmake/help/v3.14/module/ExternalProject.html |access-date=2020-10-24 |website=cmake.org}}</ref>
* '''ctest''' — is used for target testing commands specified by CMakeLists.txt
* '''ccmake''' and  '''cmake-gui''' — tweaks and updates configuration variables intended for the native build system
* '''cpack''' — helps to package software

===CPack===
'''CPack''' is a packaging system for software distributions. It is tightly integrated with CMake but can function without it.
<ref>{{cite web |title=Packaging With CPack |url=https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/Packaging-With-CPack |website=CMake Community Wiki |language=en}}</ref><ref>{{man|1|cpack|ManKier}}.</ref>

It can be used to generate:
* Linux [[RPM package|RPM]], [[Debian package|deb]], and [[gzip]] packages (for both [[Binary file|binaries]] and [[source code]]).
* [[Nullsoft Scriptable Install System|NSIS]] files (for [[Microsoft Windows]]).
* [[macOS]] packages.

== Adoption ==
CMake has been very widely adopted among commercial, open source, and academic software projects. A few notable users include 
[[Android NDK]], [[Netflix]], [[Inria]],  [[MySQL]], [[Boost (C++ libraries)]], [[KeePassXC]], [[KDE]], [[KiCad|KiCAD]], [[FreeCAD]], [[WebKit|Webkit]], [[Blender (software)|Blender]],<ref>{{Cite web|title=Building Blender - Blender Developer Wiki|url=https://wiki.blender.org/wiki/Building_Blender|access-date=2021-07-01|website=wiki.blender.org}}</ref> Biicode, [[ReactOS]], [[Apache Qpid]], the [[ATLAS experiment]],<ref>{{Cite web|year=2017|title=Large Scale Software Building with CMake in ATLAS|url=https://cds.cern.ch/record/2243765/files/ATL-SOFT-PROC-2017-033.pdf|url-status=live|publisher=CERN
|first1=J|last1=Elmsheuser
|first2=A|last2=Krasznahorkay
|first3=E|last3=Obreshkov
|first4=A|last4=Undrus|archive-url=https://web.archive.org/web/20180728080455/http://cds.cern.ch/record/2243765/files/ATL-SOFT-PROC-2017-033.pdf |archive-date=28 July 2018 }}</ref> and [[Second Life]].<ref>{{cite web |url=https://cmake.org/success/ |title=CMake Success |date=2011 |website=cmake.org |publisher=Kitware |access-date=March 12, 2022}}</ref>

==Examples==
===Hello world===
The following source code files demonstrate how to build a simple [[C++#Language|hello world]] program written in C++ by using CMake.

====Example 1====

<syntaxhighlight lang="c++">
// hello.cpp
#include <iostream>

int main()
{
    std::cout << "Hello, world!" << std::endl;

    return 0;
}

</syntaxhighlight>

<syntaxhighlight lang="CMake">
# CMakeLists.txt
cmake_minimum_required(VERSION 3.5)
project(HelloWorld CXX)
add_executable(hello hello.cpp)
</syntaxhighlight>

====Example 2====

<syntaxhighlight lang="c++">
// hello.cpp
#include "hello_heading.h"
#include <iostream>

int main()
{
    for (int i = 0; i < Times; i++)
    {
        std::cout << "Hello, world!" << std::endl;
    }

    return 0;
}

</syntaxhighlight>
<syntaxhighlight lang="c++">
// hello_heading.h
#ifndef HELLO_HEADING_H_
#define HELLO_HEADING_H_
const int Times = 10;
#endif
</syntaxhighlight>
<syntaxhighlight lang="CMake">
# CMakeLists.txt
cmake_minimum_required(VERSION 3.5)
project(HelloWorld CXX)
include_directories(${PROJECT_SOURCE_DIR})
add_executable(hello hello.cpp)
</syntaxhighlight>

[[Bash (shell)|Shell]] commands to run CMake on a [[Linux]] system (to be entered in the directory that contains the two files above):
<syntaxhighlight lang="bash">
cmake -B build .          # Configure the build directory.
cmake --build build       # Build the program in the build directory.
./build/hello             # Run the program (outputs "Hello, world!")
</syntaxhighlight>

<!-- TODO: Add script for windows and other platforms to show true power of CMake  -->

==See also==
{{Portal|Free and open-source software}}
* {{section link|List of build automation software|Build script generation}}
* [[configure script]]
*[[Make_(software)|Make]]
*[[Monorepo]]
*[[Qmake]]

== Notes ==
{{Notelist}}

==References==
{{Reflist|30em}}

==External links==
* {{Official website}}


[[Category:2000 software]]
[[Category:Build automation]]
[[Category:Compiling tools]]
[[Category:Software that uses Qt]]
[[Category:Software using the BSD license]]