diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/manual/cmake-generators.7.rst | 4 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 137 |
2 files changed, 120 insertions, 21 deletions
diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 0287767..1de10c4 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -27,6 +27,8 @@ when creating a new build tree. CMake Generators ================ +.. _`Command-Line Build Tool Generators`: + Command-Line Build Tool Generators ---------------------------------- @@ -58,6 +60,8 @@ Ninja Generator /generator/Ninja +.. _`IDE Build Tool Generators`: + IDE Build Tool Generators ------------------------- diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index c7f3537..915e0d4 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -9,7 +9,8 @@ Synopsis .. parsed-literal:: `Generate a Project Buildsystem`_ - cmake [<options>] {<path-to-source> | <path-to-existing-build>} + cmake [<options>] <path-to-source> + cmake [<options>] <path-to-existing-build> cmake [<options>] -S <path-to-source> -B <path-to-build> `Build a Project`_ @@ -33,37 +34,131 @@ Synopsis Description =========== -The **cmake** executable is the CMake command-line interface. It may be -used to configure projects in scripts. Project configuration settings -may be specified on the command line with the -D option. - -CMake is a cross-platform build system generator. Projects specify -their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. -Users build a project by using CMake to generate a build system for a -native tool on their platform. +The **cmake** executable is the command-line interface of the cross-platform +buildsystem generator CMake. The above `Synopsis`_ lists various actions +the tool can perform as described in sections below. + +To build a software project with CMake, `Generate a Project Buildsystem`_. +Optionally use **cmake** to `Build a Project`_ or just run the +corresponding build tool (e.g. ``make``) directly. **cmake** can also +be used to `View Help`_. + +The other actions are meant for use by software developers writing +scripts in the :manual:`CMake language <cmake-language(7)>` to support +their builds. + +For graphical user interfaces that may be used in place of **cmake**, +see :manual:`ccmake <ccmake(1)>` and :manual:`cmake-gui <cmake-gui(1)>`. +For command-line interfaces to the CMake testing and packaging facilities, +see :manual:`ctest <ctest(1)>` and :manual:`cpack <cpack(1)>`. + +For more information on CMake at large, `see also`_ the links at the end +of this manual. + + +Introduction to CMake Buildsystems +================================== + +A *buildsystem* describes how to build a project's executables and libraries +from its source code using a *build tool* to automate the process. For +example, a buildsystem may be a ``Makefile`` for use with a command-line +``make`` tool or a project file for an Integrated Development Environment +(IDE). In order to avoid maintaining multiple such buildsystems, a project +may specify its buildsystem abstractly using files written in the +:manual:`CMake language <cmake-language(7)>`. From these files CMake +generates a preferred buildsystem locally for each user through a backend +called a *generator*. + +To generate a buildsystem with CMake, the following must be selected: + +Source Tree + The top-level directory containing source files provided by the project. + The project specifies its buildsystem using files as described in the + :manual:`cmake-language(7)` manual, starting with a top-level file named + ``CMakeLists.txt``. These files specify build targets and their + dependencies as described in the :manual:`cmake-buildsystem(7)` manual. + +Build Tree + The top-level directory in which buildsystem files and build output + artifacts (e.g. executables and libraries) are to be stored. + CMake will write a ``CMakeCache.txt`` file to identify the directory + as a build tree and store persistent information such as buildsystem + configuration options. + + To maintain a pristine source tree, perform an *out-of-source* build + by using a separate dedicated build tree. An *in-source* build in + which the build tree is placed in the same directory as the source + tree is also supported, but discouraged. + +Generator + This chooses the kind of buildsystem to generate. See the + :manual:`cmake-generators(7)` manual for documentation of all generators. + Run ``cmake --help`` to see a list of generators available locally. + Optionally use the ``-G`` option below to specify a generator, or simply + accept the default CMake chooses for the current platform. + + When using one of the :ref:`Command-Line Build Tool Generators` + CMake expects that the environment needed by the compiler toolchain + is already configured in the shell. When using one of the + :ref:`IDE Build Tool Generators`, no particular environment is needed. Generate a Project Buildsystem ============================== -.. code-block:: shell +Run CMake with one of the following command signatures to specify the +source and build trees and generate a buildsystem: - cmake [<options>] {<path-to-source> | <path-to-existing-build>} - cmake [<options>] -S <path-to-source> -B <path-to-build> +``cmake [<options>] <path-to-source>`` + Uses the current working directory as the build tree, and + ``<path-to-source>`` as the source tree. The specified path may + be absolute or relative to the current working directory. + The source tree must contain a ``CMakeLists.txt`` file and must + *not* contain a ``CMakeCache.txt`` file because the latter + identifies an existing build tree. For example: + + .. code-block:: console + + $ mkdir build ; cd build + $ cmake ../src + +``cmake [<options>] <path-to-existing-build>`` + Uses ``<path-to-existing-build>`` as the build tree, and loads the + path to the source tree from its ``CMakeCache.txt`` file, which must + have already been generated by a previous run of CMake. The specified + path may be absolute or relative to the current working directory. + For example: + + .. code-block:: console -The parameter ``<path-to-source>`` must be the relative or absolute path -of the source directory that contains the top-level ``CMakeLists.txt`` file. -Alternatively, if the named directory contains ``CMakeCache.txt`` it will -be treated as ``<path-to-existing-build>`` and the path to the source will -be loaded from the cache. + $ cd build + $ cmake . -By default, **cmake** writes the generated Makefiles and all other output -to the directory from where it was invoked. This behavior can be changed -by the variant with the parameter ``<path-to-build>``. +``cmake [<options>] -S <path-to-source> -B <path-to-build>`` + Uses ``<path-to-build>`` as the build tree and ``<path-to-source>`` + as the source tree. The specified paths may be absolute or relative + to the current working directory. The source tree must contain a + ``CMakeLists.txt`` file. The build tree will be created automatically + if it does not already exist. For example: + + .. code-block:: console + + $ cmake -S src -B build In all cases the ``<options>`` may be zero or more of the `Options`_ below. +After generating a buildsystem one may use the corresponding native +build tool to build the project. For example, after using the +:generator:`Unix Makefiles` generator one may run ``make`` directly: + + .. code-block:: console + + $ make + $ make install + +Alternatively, one may use **cmake** to `Build a Project`_ by +automatically choosing and invoking the appropriate native build tool. + .. _`CMake Options`: Options |