You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
692 lines
24 KiB
692 lines
24 KiB
User Interaction Guide
|
|
**********************
|
|
|
|
.. only:: html
|
|
|
|
.. contents::
|
|
|
|
Introduction
|
|
============
|
|
|
|
Where a software package supplies a CMake-based buildsystem
|
|
with the source of their software, the consumer of the
|
|
software is required to run a CMake user interaction tool
|
|
in order to build it.
|
|
|
|
Well-behaved CMake-based buildsystems do not create any
|
|
output in the source directory, so typically, the user
|
|
performs an out-of-source build and performs the build
|
|
there. First, CMake must be instructed to generate a
|
|
suitable buildsystem, then the user invokes a build tool
|
|
to process that generated buildsystem. The generated
|
|
buildsystem is specific to the machine used to generate
|
|
it and is not redistributable. Each consumer of a provided
|
|
source software package is required to use CMake to
|
|
generate a buildsystem specific to their system.
|
|
|
|
Generated buildsystems should generally be treated as
|
|
read-only. The CMake files as a primary artifact should
|
|
completely specify the buildsystem and there should be no
|
|
reason to populate properties manually in an IDE for
|
|
example after generating the buildsystem. CMake will
|
|
periodically rewrite the generated buildsystem, so
|
|
modifications by users will be overwritten.
|
|
|
|
The features and user interfaces described in this manual
|
|
are available for all CMake-based build systems by virtue
|
|
of providing CMake files.
|
|
|
|
The CMake tooling may report errors to the user when
|
|
processing provided CMake files, such as reporting that
|
|
the compiler is not supported, or the compiler does not
|
|
support a required compile option, or a dependency can
|
|
not be found. These errors must be resolved by the user
|
|
by choosing a different compiler,
|
|
:guide:`installing dependencies <Using Dependencies Guide>`,
|
|
or instructing CMake where to find them, etc.
|
|
|
|
Command Line cmake tool
|
|
-----------------------
|
|
|
|
A simple but typical use of :manual:`cmake(1)` with a fresh
|
|
copy of software source code is to create a build directory
|
|
and invoke cmake there:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd some_software-1.4.2
|
|
$ mkdir build
|
|
$ cd build
|
|
$ cmake .. -DCMAKE_INSTALL_PREFIX=/opt/the/prefix
|
|
$ cmake --build .
|
|
$ cmake --build . --target install
|
|
|
|
It is recommended to build in a separate directory to the
|
|
source because that keeps the source directory pristine,
|
|
allows for building a single source with multiple
|
|
toolchains, and allows easy clearing of build artifacts by
|
|
simply deleting the build directory.
|
|
|
|
The CMake tooling may report warnings which are intended
|
|
for the provider of the software, not intended for the
|
|
consumer of the software. Such warnings end with "This
|
|
warning is for project developers". Users may disable
|
|
such warnings by passing the ``-Wno-dev`` flag to
|
|
:manual:`cmake(1)`.
|
|
|
|
cmake-gui tool
|
|
--------------
|
|
|
|
Users more accustomed to GUI interfaces may use the
|
|
:manual:`cmake-gui(1)` tool to invoke CMake and generate
|
|
a buildsystem.
|
|
|
|
The source and binary directories must first be
|
|
populated. It is always advised to use different
|
|
directories for the source and the build.
|
|
|
|
.. image:: /guide/user-interaction/GUI-Source-Binary.png
|
|
:alt: Choosing source and binary directories
|
|
|
|
Generating a Buildsystem
|
|
========================
|
|
|
|
There are several user interface tools which may be used
|
|
to generate a buildsystem from CMake files. The
|
|
:manual:`ccmake(1)` and :manual:`cmake-gui(1)` tools guide
|
|
the user through setting the various necessary options.
|
|
The :manual:`cmake(1)` tool can be invoked to specify
|
|
options on the command line. This manual describes options
|
|
which may be set using any of the user interface tools,
|
|
though the mode of setting an option is different for each
|
|
tool.
|
|
|
|
Command line environment
|
|
------------------------
|
|
|
|
When invoking :manual:`cmake(1)` with a command line
|
|
buildsystem such as ``Makefiles`` or ``Ninja``, it is
|
|
necessary to use the correct build environment to
|
|
ensure that build tools are available. CMake must be
|
|
able to find the appropriate
|
|
:variable:`build tool <CMAKE_MAKE_PROGRAM>`,
|
|
compiler, linker and other tools as needed.
|
|
|
|
On Linux systems, the appropriate tools are often
|
|
provided in system-wide locations and may be readily
|
|
installed through the system package manager. Other
|
|
toolchains provided by the user or installed in
|
|
non-default locations can also be used.
|
|
|
|
When cross-compiling, some platforms may require
|
|
environment variables to be set or may provide
|
|
scripts to set the environment.
|
|
|
|
Visual Studio ships multiple command prompts and
|
|
``vcvarsall.bat`` scripts for setting up the
|
|
correct environments for command line buildsystems. While
|
|
not strictly necessary to use a corresponding
|
|
command line environment when using a Visual Studio
|
|
generator, doing so has no disadvantages.
|
|
|
|
When using Xcode, there can be more than one Xcode
|
|
version installed. Which one to use can be selected
|
|
in a number of different ways, but the most common
|
|
methods are:
|
|
|
|
* Setting the default version in the preferences
|
|
of the Xcode IDE.
|
|
* Setting the default version via the ``xcode-select``
|
|
command line tool.
|
|
* Overriding the default version by setting the
|
|
``DEVELOPER_DIR`` environment variable when running
|
|
CMake and the build tool.
|
|
|
|
Command line ``-G`` option
|
|
--------------------------
|
|
|
|
CMake chooses a generator by default based on the
|
|
platform. Usually, the default generator is sufficient
|
|
to allow the user to proceed to build the software.
|
|
|
|
The user may override the default generator with
|
|
the ``-G`` option:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cmake .. -G Ninja
|
|
|
|
The output of ``cmake --help`` includes a list of
|
|
:manual:`generators <cmake-generators(7)>` available
|
|
for the user to choose from. Note that generator
|
|
names are case sensitive.
|
|
|
|
On Unix-like systems (including Mac OS X), the
|
|
:generator:`Unix Makefiles` generator is used by
|
|
default. A variant of that generator can also be used
|
|
on Windows in various environments, such as the
|
|
:generator:`NMake Makefiles` and
|
|
:generator:`MinGW Makefiles` generator. These generators
|
|
generate a ``Makefile`` variant which can be executed
|
|
with ``make``, ``gmake``, ``nmake`` or similar tools.
|
|
See the individual generator documentation for more
|
|
information on targeted environments and tools.
|
|
|
|
The :generator:`Ninja` generator is available on all
|
|
major platforms. ``ninja`` is a build tool similar
|
|
in use-cases to ``make``, but with a focus on
|
|
performance and efficiency.
|
|
|
|
On Windows, :manual:`cmake(1)` can be used to generate
|
|
solutions for the Visual Studio IDE. Visual Studio
|
|
versions may be specified by the product name of the
|
|
IDE, which includes a four-digit year. Aliases are
|
|
provided for other means by which Visual Studio
|
|
versions are sometimes referred to, such as two
|
|
digits which correspond to the product version of the
|
|
VisualC++ compiler, or a combination of the two:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cmake .. -G "Visual Studio 2019"
|
|
$ cmake .. -G "Visual Studio 16"
|
|
$ cmake .. -G "Visual Studio 16 2019"
|
|
|
|
Visual Studio generators can target different architectures.
|
|
One can specify the target architecture using the `-A` option:
|
|
|
|
.. code-block:: console
|
|
|
|
cmake .. -G "Visual Studio 2019" -A x64
|
|
cmake .. -G "Visual Studio 16" -A ARM
|
|
cmake .. -G "Visual Studio 16 2019" -A ARM64
|
|
|
|
On Apple, the :generator:`Xcode` generator may be used to
|
|
generate project files for the Xcode IDE.
|
|
|
|
Some IDEs such as KDevelop4, QtCreator and CLion have
|
|
native support for CMake-based buildsystems. Those IDEs
|
|
provide user interface for selecting an underlying
|
|
generator to use, typically a choice between a ``Makefile``
|
|
or a ``Ninja`` based generator.
|
|
|
|
Note that it is not possible to change the generator
|
|
with ``-G`` after the first invocation of CMake. To
|
|
change the generator, the build directory must be
|
|
deleted and the build must be started from scratch.
|
|
|
|
When generating Visual Studio project and solutions
|
|
files several other options are available to use when
|
|
initially running :manual:`cmake(1)`.
|
|
|
|
The Visual Studio toolset can be specified with the
|
|
``-T`` option:
|
|
|
|
.. code-block:: console
|
|
|
|
$ # Build with the clang-cl toolset
|
|
$ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T LLVM
|
|
$ # Build targeting Windows XP
|
|
$ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T v120_xp
|
|
|
|
Whereas the ``-A`` option specifies the _target_
|
|
architecture, the ``-T`` option can be used to specify
|
|
details of the toolchain used. For example, `-Thost=x64`
|
|
can be given to select the 64-bit version of the host
|
|
tools. The following demonstrates how to use 64-bit
|
|
tools and also build for a 64-bit target architecture:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cmake .. -G "Visual Studio 16 2019" -A x64 -Thost=x64
|
|
|
|
Choosing a generator in cmake-gui
|
|
---------------------------------
|
|
|
|
The "Configure" button triggers a new dialog to
|
|
select the CMake generator to use.
|
|
|
|
.. image:: /guide/user-interaction/GUI-Configure-Dialog.png
|
|
:alt: Configuring a generator
|
|
|
|
All generators available on the command line are also
|
|
available in :manual:`cmake-gui(1)`.
|
|
|
|
.. image:: /guide/user-interaction/GUI-Choose-Generator.png
|
|
:alt: Choosing a generator
|
|
|
|
When choosing a Visual Studio generator, further options
|
|
are available to set an architecture to generate for.
|
|
|
|
.. image:: /manual/VS-Choose-Arch.png
|
|
:alt: Choosing an architecture for Visual Studio generators
|
|
|
|
.. _`Setting Build Variables`:
|
|
|
|
Setting Build Variables
|
|
=======================
|
|
|
|
Software projects often require variables to be
|
|
set on the command line when invoking CMake. Some of
|
|
the most commonly used CMake variables are listed in
|
|
the table below:
|
|
|
|
========================================== ============================================================
|
|
Variable Meaning
|
|
========================================== ============================================================
|
|
:variable:`CMAKE_PREFIX_PATH` Path to search for
|
|
:guide:`dependent packages <Using Dependencies Guide>`
|
|
:variable:`CMAKE_MODULE_PATH` Path to search for additional CMake modules
|
|
:variable:`CMAKE_BUILD_TYPE` Build configuration, such as
|
|
``Debug`` or ``Release``, determining
|
|
debug/optimization flags. This is only
|
|
relevant for single-configuration buildsystems such
|
|
as ``Makefile`` and ``Ninja``. Multi-configuration
|
|
buildsystems such as those for Visual Studio and Xcode
|
|
ignore this setting.
|
|
:variable:`CMAKE_INSTALL_PREFIX` Location to install the
|
|
software to with the
|
|
``install`` build target
|
|
:variable:`CMAKE_TOOLCHAIN_FILE` File containing cross-compiling
|
|
data such as
|
|
:manual:`toolchains and sysroots <cmake-toolchains(7)>`.
|
|
:variable:`BUILD_SHARED_LIBS` Whether to build shared
|
|
instead of static libraries
|
|
for :command:`add_library`
|
|
commands used without a type
|
|
:variable:`CMAKE_EXPORT_COMPILE_COMMANDS` Generate a ``compile_commands.json``
|
|
file for use with clang-based tools
|
|
========================================== ============================================================
|
|
|
|
Other project-specific variables may be available
|
|
to control builds, such as enabling or disabling
|
|
components of the project.
|
|
|
|
There is no convention provided by CMake for how
|
|
such variables are named between different
|
|
provided buildsystems, except that variables with
|
|
the prefix ``CMAKE_`` usually refer to options
|
|
provided by CMake itself and should not be used
|
|
in third-party options, which should use
|
|
their own prefix instead. The
|
|
:manual:`cmake-gui(1)` tool can display options
|
|
in groups defined by their prefix, so it makes
|
|
sense for third parties to ensure that they use a
|
|
self-consistent prefix.
|
|
|
|
Setting variables on the command line
|
|
-------------------------------------
|
|
|
|
CMake variables can be set on the command line either
|
|
when creating the initial build:
|
|
|
|
.. code-block:: console
|
|
|
|
$ mkdir build
|
|
$ cd build
|
|
$ cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug
|
|
|
|
or later on a subsequent invocation of
|
|
:manual:`cmake(1)`:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd build
|
|
$ cmake . -DCMAKE_BUILD_TYPE=Debug
|
|
|
|
The ``-U`` flag may be used to unset variables
|
|
on the :manual:`cmake(1)` command line:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd build
|
|
$ cmake . -UMyPackage_DIR
|
|
|
|
A CMake buildsystem which was initially created
|
|
on the command line can be modified using the
|
|
:manual:`cmake-gui(1)` and vice-versa.
|
|
|
|
The :manual:`cmake(1)` tool allows specifying a
|
|
file to use to populate the initial cache using
|
|
the ``-C`` option. This can be useful to simplify
|
|
commands and scripts which repeatedly require the
|
|
same cache entries.
|
|
|
|
Setting variables with cmake-gui
|
|
--------------------------------
|
|
|
|
Variables may be set in the cmake-gui using the "Add Entry"
|
|
button. This triggers a new dialog to set the value of
|
|
the variable.
|
|
|
|
.. image:: /guide/user-interaction/GUI-Add-Entry.png
|
|
:alt: Editing a cache entry
|
|
|
|
The main view of the :manual:`cmake-gui(1)` user interface
|
|
can be used to edit existing variables.
|
|
|
|
The CMake Cache
|
|
---------------
|
|
|
|
When CMake is executed, it needs to find the locations of
|
|
compilers, tools and dependencies. It also needs to be
|
|
able to consistently re-generate a buildsystem to use the
|
|
same compile/link flags and paths to dependencies. Such
|
|
parameters are also required to be configurable by the
|
|
user because they are paths and options specific to the
|
|
users system.
|
|
|
|
When it is first executed, CMake generates a
|
|
``CMakeCache.txt`` file in the build directory containing
|
|
key-value pairs for such artifacts. The cache file can be
|
|
viewed or edited by the user by running the
|
|
:manual:`cmake-gui(1)` or :manual:`ccmake(1)` tool. The
|
|
tools provide an interactive interface for re-configuring
|
|
the provided software and re-generating the buildsystem,
|
|
as is needed after editing cached values. Each cache
|
|
entry may have an associated short help text which is
|
|
displayed in the user interface tools.
|
|
|
|
The cache entries may also have a type to signify how it
|
|
should be presented in the user interface. For example,
|
|
a cache entry of type ``BOOL`` can be edited by a
|
|
checkbox in a user interface, a ``STRING`` can be edited
|
|
in a text field, and a ``FILEPATH`` while similar to a
|
|
``STRING`` should also provide a way to locate filesystem
|
|
paths using a file dialog. An entry of type ``STRING``
|
|
may provide a restricted list of allowed values which are
|
|
then provided in a drop-down menu in the
|
|
:manual:`cmake-gui(1)` user interface (see the
|
|
:prop_cache:`STRINGS` cache property).
|
|
|
|
The CMake files shipped with a software package may also
|
|
define boolean toggle options using the :command:`option`
|
|
command. The command creates a cache entry which has a
|
|
help text and a default value. Such cache entries are
|
|
typically specific to the provided software and affect
|
|
the configuration of the build, such as whether tests
|
|
and examples are built, whether to build with exceptions
|
|
enabled etc.
|
|
|
|
Invoking the Buildsystem
|
|
========================
|
|
|
|
After generating the buildsystem, the software can be
|
|
built by invoking the particular build tool. In the
|
|
case of the IDE generators, this can involve loading
|
|
the generated project file into the IDE to invoke the
|
|
build.
|
|
|
|
CMake is aware of the specific build tool needed to invoke
|
|
a build so in general, to build a buildsystem or project
|
|
from the command line after generating, the following
|
|
command may be invoked in the build directory:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cmake --build .
|
|
|
|
The ``--build`` flag enables a particular mode of
|
|
operation for the :manual:`cmake(1)` tool. It invokes
|
|
the :variable:`CMAKE_MAKE_PROGRAM` command associated
|
|
with the :manual:`generator <cmake-generators(7)>`, or
|
|
the build tool configured by the user.
|
|
|
|
The ``--build`` mode also accepts the parameter
|
|
``--target`` to specify a particular target to build,
|
|
for example a particular library, executable or
|
|
custom target, or a particular special target like
|
|
``install``:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cmake --build . --target myexe
|
|
|
|
The ``--build`` mode also accepts a ``--config`` parameter
|
|
in the case of multi-config generators to specify which
|
|
particular configuration to build:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cmake --build . --target myexe --config Release
|
|
|
|
The ``--config`` option has no effect if the generator
|
|
generates a buildsystem specific to a configuration which
|
|
is chosen when invoking cmake with the
|
|
:variable:`CMAKE_BUILD_TYPE` variable.
|
|
|
|
Some buildsystems omit details of command lines invoked
|
|
during the build. The ``--verbose`` flag can be used to
|
|
cause those command lines to be shown:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cmake --build . --target myexe --verbose
|
|
|
|
The ``--build`` mode can also pass particular command
|
|
line options to the underlying build tool by listing
|
|
them after ``--``. This can be useful to specify
|
|
options to the build tool, such as to continue the
|
|
build after a failed job, where CMake does not
|
|
provide a high-level user interface.
|
|
|
|
For all generators, it is possible to run the underlying
|
|
build tool after invoking CMake. For example, ``make``
|
|
may be executed after generating with the
|
|
:generator:`Unix Makefiles` generator to invoke the build,
|
|
or ``ninja`` after generating with the :generator:`Ninja`
|
|
generator etc. The IDE buildsystems usually provide
|
|
command line tooling for building a project which can
|
|
also be invoked.
|
|
|
|
Selecting a Target
|
|
------------------
|
|
|
|
Each executable and library described in the CMake files
|
|
is a build target, and the buildsystem may describe
|
|
custom targets, either for internal use, or for user
|
|
consumption, for example to create documentation.
|
|
|
|
CMake provides some built-in targets for all buildsystems
|
|
providing CMake files.
|
|
|
|
``all``
|
|
The default target used by ``Makefile`` and ``Ninja``
|
|
generators. Builds all targets in the buildsystem,
|
|
except those which are excluded by their
|
|
:prop_tgt:`EXCLUDE_FROM_ALL` target property or
|
|
:prop_dir:`EXCLUDE_FROM_ALL` directory property. The
|
|
name ``ALL_BUILD`` is used for this purpose for the
|
|
Xcode and Visual Studio generators.
|
|
``help``
|
|
Lists the targets available for build. This target is
|
|
available when using the :generator:`Unix Makefiles` or
|
|
:generator:`Ninja` generator, and the exact output is
|
|
tool-specific.
|
|
``clean``
|
|
Delete built object files and other output files. The
|
|
``Makefile`` based generators create a ``clean`` target
|
|
per directory, so that an individual directory can be
|
|
cleaned. The ``Ninja`` tool provides its own granular
|
|
``-t clean`` system.
|
|
``test``
|
|
Runs tests. This target is only automatically available
|
|
if the CMake files provide CTest-based tests. See also
|
|
`Running Tests`_.
|
|
``install``
|
|
Installs the software. This target is only automatically
|
|
available if the software defines install rules with the
|
|
:command:`install` command. See also
|
|
`Software Installation`_.
|
|
``package``
|
|
Creates a binary package. This target is only
|
|
automatically available if the CMake files provide
|
|
CPack-based packages.
|
|
``package_source``
|
|
Creates a source package. This target is only
|
|
automatically available if the CMake files provide
|
|
CPack-based packages.
|
|
|
|
For ``Makefile`` based systems, ``/fast`` variants of binary
|
|
build targets are provided. The ``/fast`` variants are used
|
|
to build the specified target without regard for its
|
|
dependencies. The dependencies are not checked and
|
|
are not rebuilt if out of date. The :generator:`Ninja`
|
|
generator is sufficiently fast at dependency checking that
|
|
such targets are not provided for that generator.
|
|
|
|
``Makefile`` based systems also provide build-targets to
|
|
preprocess, assemble and compile individual files in a
|
|
particular directory.
|
|
|
|
.. code-block:: console
|
|
|
|
$ make foo.cpp.i
|
|
$ make foo.cpp.s
|
|
$ make foo.cpp.o
|
|
|
|
The file extension is built into the name of the target
|
|
because another file with the same name but a different
|
|
extension may exist. However, build-targets without the
|
|
file extension are also provided.
|
|
|
|
.. code-block:: console
|
|
|
|
$ make foo.i
|
|
$ make foo.s
|
|
$ make foo.o
|
|
|
|
In buildsystems which contain ``foo.c`` and ``foo.cpp``,
|
|
building the ``foo.i`` target will preprocess both files.
|
|
|
|
Specifying a Build Program
|
|
--------------------------
|
|
|
|
The program invoked by the ``--build`` mode is determined
|
|
by the :variable:`CMAKE_MAKE_PROGRAM` variable. For most
|
|
generators, the particular program does not need to be
|
|
configured.
|
|
|
|
===================== =========================== ===========================
|
|
Generator Default make program Alternatives
|
|
===================== =========================== ===========================
|
|
XCode ``xcodebuild``
|
|
Unix Makefiles ``make``
|
|
NMake Makefiles ``nmake`` ``jom``
|
|
NMake Makefiles JOM ``jom`` ``nmake``
|
|
MinGW Makefiles ``mingw32-make``
|
|
MSYS Makefiles ``make``
|
|
Ninja ``ninja``
|
|
Visual Studio ``msbuild``
|
|
Watcom WMake ``wmake``
|
|
===================== =========================== ===========================
|
|
|
|
The ``jom`` tool is capable of reading makefiles of the
|
|
``NMake`` flavor and building in parallel, while the
|
|
``nmake`` tool always builds serially. After generating
|
|
with the :generator:`NMake Makefiles` generator a user
|
|
can run ``jom`` instead of ``nmake``. The ``--build``
|
|
mode would also use ``jom`` if the
|
|
:variable:`CMAKE_MAKE_PROGRAM` was set to ``jom`` while
|
|
using the :generator:`NMake Makefiles` generator, and
|
|
as a convenience, the :generator:`NMake Makefiles JOM`
|
|
generator is provided to find ``jom`` in the normal way
|
|
and use it as the :variable:`CMAKE_MAKE_PROGRAM`. For
|
|
completeness, ``nmake`` is an alternative tool which
|
|
can process the output of the
|
|
:generator:`NMake Makefiles JOM` generator, but doing
|
|
so would be a pessimisation.
|
|
|
|
Software Installation
|
|
=====================
|
|
|
|
The :variable:`CMAKE_INSTALL_PREFIX` variable can be
|
|
set in the CMake cache to specify where to install the
|
|
provided software. If the provided software has install
|
|
rules, specified using the :command:`install` command,
|
|
they will install artifacts into that prefix. On Windows,
|
|
the default installation location corresponds to the
|
|
``ProgramFiles`` system directory which may be
|
|
architecture specific. On Unix hosts, ``/usr/local`` is
|
|
the default installation location.
|
|
|
|
The :variable:`CMAKE_INSTALL_PREFIX` variable always
|
|
refers to the installation prefix on the target
|
|
filesystem.
|
|
|
|
In cross-compiling or packaging scenarios where the
|
|
sysroot is read-only or where the sysroot should otherwise
|
|
remain pristine, the :variable:`CMAKE_STAGING_PREFIX`
|
|
variable can be set to a location to actually install
|
|
the files.
|
|
|
|
The commands:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local \
|
|
-DCMAKE_SYSROOT=$HOME/root \
|
|
-DCMAKE_STAGING_PREFIX=/tmp/package
|
|
$ cmake --build .
|
|
$ cmake --build . --target install
|
|
|
|
result in files being installed to paths such
|
|
as ``/tmp/package/lib/libfoo.so`` on the host machine.
|
|
The ``/usr/local`` location on the host machine is
|
|
not affected.
|
|
|
|
Some provided software may specify ``uninstall`` rules,
|
|
but CMake does not generate such rules by default itself.
|
|
|
|
Running Tests
|
|
=============
|
|
|
|
The :manual:`ctest(1)` tool is shipped with the CMake
|
|
distribution to execute provided tests and report
|
|
results. The ``test`` build-target is provided to run
|
|
all available tests, but the :manual:`ctest(1)` tool
|
|
allows granular control over which tests to run, how to
|
|
run them, and how to report results. Executing
|
|
:manual:`ctest(1)` in the build directory is equivalent
|
|
to running the ``test`` target:
|
|
|
|
.. code-block:: console
|
|
|
|
$ ctest
|
|
|
|
A regular expression can be passed to run only tests
|
|
which match the expression. To run only tests with
|
|
``Qt`` in their name:
|
|
|
|
.. code-block:: console
|
|
|
|
$ ctest -R Qt
|
|
|
|
Tests can be excluded by regular expression too. To
|
|
run only tests without ``Qt`` in their name:
|
|
|
|
.. code-block:: console
|
|
|
|
$ ctest -E Qt
|
|
|
|
Tests can be run in parallel by passing ``-j`` arguments
|
|
to :manual:`ctest(1)`:
|
|
|
|
.. code-block:: console
|
|
|
|
$ ctest -R Qt -j8
|
|
|
|
The environment variable :envvar:`CTEST_PARALLEL_LEVEL`
|
|
can alternatively be set to avoid the need to pass
|
|
``-j``.
|
|
|
|
By default :manual:`ctest(1)` does not print the output
|
|
from the tests. The command line argument ``-V`` (or
|
|
``--verbose``) enables verbose mode to print the
|
|
output from all tests.
|
|
The ``--output-on-failure`` option prints the test
|
|
output for failing tests only. The environment variable
|
|
:envvar:`CTEST_OUTPUT_ON_FAILURE`
|
|
can be set to ``1`` as an alternative to passing the
|
|
``--output-on-failure`` option to :manual:`ctest(1)`.
|