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]]
}}

'''CMake''' is a free, [[cross-platform]], [[software development tool]] for [[build automation|building]] [[application software|applications]] via [[compiler]]-independent instructions. It also can [[automation|automate]] [[software testing|testing]], [[package (package management system)|packaging]] and [[Installation (computer programs)|installation]]. It runs on a variety of [[computing platform|platforms]] and supports many [[programming languages]].<ref>{{Cite web|url=https://cmake.org/|title=CMake}}</ref>

As a meta-build tool, CMake configures [[Native (computing)|native]] build tools which in turn build the [[codebase]]. CMake generates [[configuration file]]s for other build tools based on CMake-specific configuration files. The other tools are responsible for more directly building; using the generated files. A single set of CMake-specific configuration files can be used to build a codebase using the native build tools of multiple platforms.<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> 

Notable native build tools supported by CMake include: [[make (software)|Make]], [[Qt Creator]], [[Ninja (build system)|Ninja]], [[Android Studio]], [[Xcode]], and [[Microsoft Visual Studio|Visual Studio]].<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==

Initial development began in 1999 at [[Kitware]] with funding from the [[United States National Library of Medicine]] as part of the [[Visible Human Project]].<ref name=":1" /> CMake was first released in 2000.

CMake was developed to support building the [[Insight Segmentation and Registration Toolkit]] (ITK) for multiple platforms. Stated goals included addressing weaknesses while maintaining strengths of contemporary tools such as [[autoconf]] and [[libtool]], and to align with state of the art build technology of the time: [[configure script]]s and [[Make (software)|Make]] files for [[Unix]] platforms, and [[Visual Studio]] project files for [[Microsoft Windows|Windows]].<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" />

CMake was inspired by multiple contemporary tools. pcmaker {{endash}} developed by Ken Martin and others to support building the [[VTK|Visualization Toolkit (VTK)]] {{endash}} converted Unix Make files into NMake files for building on Windows.<ref name=":1" /> gmake supported Unix and Windows compilers, but its design led to issues that were hard to resolve. Both tools were working examples of a build tool that supported both Unix and Windows, but they suffered from a serious flaw: they required Windows developers to use the command line even though many prefer to use an integrated development environment (IDE) such as Visual Studio.

CMake was to provide similar cross-platform support but to better satisfy the preferences of the developers on each platform.

The design goals of the first version included:<ref name=":1" />

* Depend only on host C++ compiler; no other third-party tools or libraries required
* Generate Visual Studio project files (as well as Unix files)
* Support building targets: [[computer program|program]], [[static library]], [[shared library]]
* Run build-time code generators
* Support separate [[directory tree]]s for [[source code|source]] vs. build files
* Support host computer capability introspection
* Support automatic dependency scanning of C/C++ header files
* All features must work consistently and equally well on all supported platforms

For various reasons, CMake developers chose to develop a scripting language for CMake instead of using [[Tcl]] {{endash}} a popular language for building at the time. Use of Tcl would have then added a dependency to the host machine which is counter to the goal of no dependencies other than a compiler. Also, Tcl was not well supported on Windows and some Unix systems at the time of initial development.<ref name=":1" />

Subsequent 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.

==Name==

CMake developer Brad King 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==

=== Generators and IDE support ===
CMake can generate project files for [[Integrated development environment|IDE]]s like [[Microsoft Visual Studio]], [[Xcode]], [[Eclipse (software)|Eclipse CDT]] and 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 by specifying generator for a platform-specific build tool. By default, CMake automatically determines default generator for the host environment it runs on. Command line option {{code|-G}} can be used to specify alternative generator. E.g. {{code|-G Unix Makefiles}} forces CMake to create build scripts for [[Make (software)|make]].<ref name=":1" />

CMake does not support custom generators without modifying the CMake implementation. None-the-less, the CMake source code could be modified to include a custom generator.

=== Build targets ===
CMake supports building executables, libraries (e.g. {{Code|libxyz}}, {{Code|xyz.dll}} etc.), [[object file]] libraries and 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>

Target generation can be configured via target properties. With older versions, this was done via {{code|CMAKE_}}-prefixed global variables, but this approach is deprecated.<ref name=":0" /><ref name="effective-cmake">{{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>

=== Hierarchical configuration ===

CMake configuration files can be structured according the hierarchical structure of the source code; the source tree. A {{code|CMakeLists.txt}} in a root source directory serves as the root of the configuration. It may include sub-directories which each contain a {{code|CMakeLists.txt}}. Repeating this, results in a hierarchical structure of configuration that follows the structure of the source code.<ref name=":0" /><ref name="effective-cmake" />

=== Separate build tree ===

CMake can store generated files (both by CMake and the native build tools) in a [[directory tree]] that is separate from the source tree.<ref name=":1" />

This enables multiple builds from the same source tree since each has non-overlapping file system space. This may be leveraged to build different or even incompatible configurations such as for different platforms. 

This also simplifies file management by allowing removing generated files by deleting a single directory tree instead of removing multiple files and directories throughout the source tree. This tends to prevent accidentally deleting source files or accidentally adding generated files to [[source control]].

=== Dependency management ===
CMake ensures that downstream components are re-built when its sources are changed or built.<ref name=":1" />

=== 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>

=== 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>

=== Compiler support ===
CMake supports many 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 ===
CMake can produce packages that can be consumed both by end-user and third-party cmake-based project. Via CPack, built files may be packed into an [[archive file]] for a target system's package manager (e.g. [[dpkg]]) or [[Installation (computer programs)#Installer|installer]] supported by the target platform.<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 name=":2">{{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> CMake provides functions for pulling packages from a remote server that can be used as part of the build process or link previously installed cmake packages.<ref name=":2" />

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

=== Precompiled headers and modules ===
It's possible to generate [[precompiled header]]s via 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> As of version 3.28, CMake can also compile [[Precompiled header#Modules|modules]], but not header units.

=== 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>

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

CMake includes an [[interpreter (computing)|interpreter]] for a relatively simple, custom, imperative [[scripting language]] that supports variables, string manipulation, arrays, function and macro declaration, and module inclusion (importing). 

The interpreter reads CMake language commands from files named {{code|CMakeLists.txt}} which specify source files and build preferences. CMake uses this information to generate native tool configuration files. Additionally, files with suffix {{code|.cmake}} can be used for storing additional script.<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>

=== Command syntax ===
CMake language commands are formatted as:

 ''name''(''argument'' ...)

Arguments are [[Whitespace character|whitespace]]-separated&nbsp;and can include keywords to separate groups of arguments. For instance, in the following command, the keyword {{code|COMPILE_FLAGS}} delimits a list of source files from compiler flags.<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>

 set_source_file_properties(''filename'' ... COMPILE_FLAGS ''compile_flag'' ...)

==Implementation==
The CMake scripting language is implemented via [[Yacc]] and [[Lex (software)|Lex]] generators.

The executable programs CMake, CPack, and CTest are written in [[C++]].

Much of CMake's functionality is implemented in modules 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>

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

==Additional tools==
CMake ships with numerous {{code|.cmake}} script files and development tools that facilitate tasks such as finding dependencies (both built-in and external, e.g. {{code|FindXYZ}} modules), testing the toolchain environment and executables, packaging releases (CPack), and managing dependencies on external projects ({{code|ExternalProject}} module). Additional development tools include:<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>

* '''ccmake''' and  '''cmake-gui''' — for updating configuration variables intended for a native build tool
* '''CPack''' — for packaging software as Linux [[RPM package|RPM]], [[Debian package|deb]], and [[gzip]] packages, [[Nullsoft Scriptable Install System|NSIS]] files (for Windows), and [[macOS]] packages <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>
* '''CTest''' and '''CDash''' — for software testing and reporting

== 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>

==Build process==
Building via CMake has a two major stages.<ref name=":1" /> First, native build tool configuration files are generated from CMake configuration files {{endash}} written in the CMake scripting language. The command line syntax is {{code|cmake <dir>}} where <dir> is a directory that contains a {{code|CMakeLists.txt}} file. Then, the native build tools are invoked either via CMake ({{code|cmake --build <dir>}}) or directly via the native tool's interface. The native build tools use the generated files.<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>

==Examples==
===Hello world===
The following demonstrates configuring CMake to build a [[C++#Language|hello world]] program written in C++, and using CMake to build the program.

hello.cpp:

<syntaxhighlight lang="c++">
#include <iostream>
int main() {
    std::cout << "Hello, world!" << std::endl;
    return 0;
}

</syntaxhighlight>

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

To build via CMake, first cd to the directory containing the two files above. Then, generate the native build config files via the cross-platform CMake command:

<syntaxhighlight lang="bash">
cmake -B out .
</syntaxhighlight>

All generated files will be under the directory ''out'' as specified via {{code|-B out}}.

Then, build via the native build tool as supported thru CMake:

<syntaxhighlight lang="bash">
cmake --build out
</syntaxhighlight>

The program is then available for running. Via [[Bash (shell)|Bash]], the command is like {{code|./out/hello}}. On Windows, the output file ends with {{code|.exe}}.

===Include===

This example demonstrates configuring the preprocessor include path.

hello.cpp:
<syntaxhighlight lang="c++">
#include "hello.h"
#include <iostream>
int main() {
    for (int i = 0; i < Times; i++) {
        std::cout << "Hello, world!" << std::endl;
    }
    return 0;
}
</syntaxhighlight>

hello.h:
<syntaxhighlight lang="c++">
const int Times = 10;
</syntaxhighlight>

CMakeLists.txt:
<syntaxhighlight lang="CMake">
cmake_minimum_required(VERSION 3.22)
project(HelloWorld CXX)
include_directories(${PROJECT_SOURCE_DIR})
add_executable(hello hello.cpp)
</syntaxhighlight>

==See also==
{{Portal|Free and open-source software}}
* {{section link|List of build automation software|meta-build}}

==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]]