daftaupe/opt
1
0
Fork 0
forked from ports/opt
Code Pull Requests Activity

Revert "cmake: 3.17.0 -> 3.17.1"

Browse Source 
This reverts commit 783e34eef87d95f3091bf5fe0793f7f86e21042c.
This commit is contained in:
Fredrik Rinnestam 2020-04-29 14:34:04 +02:00
parent ddad1ea08b
commit 4c0e32cc48
25 changed files with 8 additions and 71204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
cmake/.footprint
View File

@ -4,31 +4,6 @@ drwxr-xr-x root/root usr/bin/
-rwxr-xr-x root/root usr/bin/cmake
-rwxr-xr-x root/root usr/bin/cpack
-rwxr-xr-x root/root usr/bin/ctest
drwxr-xr-x root/root usr/man/
drwxr-xr-x root/root usr/man/man1/
-rw-r--r-- root/root usr/man/man1/ccmake.1.gz
-rw-r--r-- root/root usr/man/man1/cmake.1.gz
-rw-r--r-- root/root usr/man/man1/cpack.1.gz
-rw-r--r-- root/root usr/man/man1/ctest.1.gz
drwxr-xr-x root/root usr/man/man7/
-rw-r--r-- root/root usr/man/man7/cmake-buildsystem.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-commands.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-compile-features.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-developer.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-env-variables.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-file-api.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-generator-expressions.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-generators.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-language.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-modules.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-packages.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-policies.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-properties.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-qt.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-server.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-toolchains.7.gz
-rw-r--r-- root/root usr/man/man7/cmake-variables.7.gz
-rw-r--r-- root/root usr/man/man7/cpack-generators.7.gz
drwxr-xr-x root/root usr/share/
drwxr-xr-x root/root usr/share/aclocal/
-rw-r--r-- root/root usr/share/aclocal/cmake.m4
@ -2406,7 +2381,7 @@ drwxr-xr-x root/root usr/share/cmake/Modules/Platform/
-rw-r--r-- root/root usr/share/cmake/Modules/Platform/AIX-XLClang.cmake
-rw-r--r-- root/root usr/share/cmake/Modules/Platform/AIX.cmake
drwxr-xr-x root/root usr/share/cmake/Modules/Platform/AIX/
-rwxr-xr-x root/root usr/share/cmake/Modules/Platform/AIX/ExportImportList
-rw-r--r-- root/root usr/share/cmake/Modules/Platform/AIX/ExportImportList
-rw-r--r-- root/root usr/share/cmake/Modules/Platform/ARTOS-GNU-C.cmake
-rw-r--r-- root/root usr/share/cmake/Modules/Platform/ARTOS.cmake
-rw-r--r-- root/root usr/share/cmake/Modules/Platform/Android-Clang-ASM.cmake

30
cmake/.signature
View File

@ -1,27 +1,5 @@
untrusted comment: verify with /etc/ports/opt.pub
RWSE3ohX2g5d/fY8rBO0m3PaMfoxstc7bVgOnqucxhLCMlM1s/88ULqNW4EwlCvzxH4j7WoCkvf7rRv8lm7dkL7vZrA7N780qAY=
SHA256 (Pkgfile) = b3f0536e60adfc9ce297bc0f199f319cf9393666665844b9c6879a3c89af3b1d
SHA256 (.footprint) = fe9fe1aebf941188549e26b90d2e014d7207f120f953083a55c30c717ac51586
SHA256 (cmake-3.17.1.tar.gz) = 3aa9114485da39cbd9665a0bfe986894a282d5f0882b1dea960a739496620727
SHA256 (ccmake.1) = 504f6a477566791a2bdddcc4d84ae04dbe8f5bacdf9cc7d4137568419d061c9d
SHA256 (cmake.1) = 3afa1d15205e1f0996ba6adf71c02ce6567d868d37cdaa9c72b37b085d4fa8f0
SHA256 (cpack.1) = cefc74edc2cfe813d804e1ed0697ce513229cdcbfe2136d694bf52943db51dca
SHA256 (ctest.1) = 9c8fc78438f7907ea618675e36cd31c88fe911fdcf0d2d9f6f6a588be0ca8450
SHA256 (cmake-buildsystem.7) = 634169b67c9bdfd48a12cc89988a1a6478c6dd452e49a5cffb30896fbeb96443
SHA256 (cmake-commands.7) = 7d17518a47afb87a699e507af966e5672b8d4436fa8f0449e329199dc76ea7d1
SHA256 (cmake-compile-features.7) = d30026a223baed7203bb8220ffa9d20608713ec10cb485d8470433b8389464db
SHA256 (cmake-developer.7) = 397d29dee6c5be930fd677515b98d7cd9143b1b75454bb0e7f71e55179b74d89
SHA256 (cmake-env-variables.7) = 30e9702b761a44bb24426cab5227ad7c1942af0fd2c697aa5aba0be53c5644c4
SHA256 (cmake-file-api.7) = b928d24541300e5e6432d862b54c1d564d57dd4e10c5d680a6d4caeff9625dcb
SHA256 (cmake-generator-expressions.7) = f060548971afd5ca1568ea351c0cc0a01de9ae97df321aefa4a82014e86e70cb
SHA256 (cmake-generators.7) = daf2bbe3d6f28fa244bef7cb6112cef67681909b90a130f27b16c665cc53e89c
SHA256 (cmake-language.7) = 5bf0ba4ee61d3d17f43f71f4f5942fbe97a92a8a63c99cac7486b3b2ab7af343
SHA256 (cmake-modules.7) = 659183a80cf71534c9f2634f01abb796a943448b84c10809ed4b51cb351c732e
SHA256 (cmake-packages.7) = 173ffc363d2406af88539a37cf24a8cfa77270d8b9ed3869b252653fbc7d48fe
SHA256 (cmake-policies.7) = 52199074e920a5e06eaceac3c6e13bca12cb973712a372220ff58a6d7c3c6d7e
SHA256 (cmake-properties.7) = 0c7663d4d9da7e1a30cd9c8e3dba03d34d7f06b86145ff3d092bbb54bd308532
SHA256 (cmake-qt.7) = 12189fab3b9614467e33f113c244d953634f766171a8b620b7ca3c72b7ed6d28
SHA256 (cmake-server.7) = 35af091bf535bfe164a8e7d229af3af9c5e335c0d5ccd0c4d261afb997f7afb6
SHA256 (cmake-toolchains.7) = 8373c19863ac21a250be9a1c7305cf3274ec86929eed9c8c6ef969bf6ef64c2d
SHA256 (cmake-variables.7) = 751bc3ff7822f82064ad18ba26a0cc44d62561c32b3babb3099a13fdffe8d6a5
SHA256 (cpack-generators.7) = 197faed55df8ac33cd71a7f415dddf855eb0bf9af696f7a255c3635534ac09c4
RWSE3ohX2g5d/VlJTD25NjoM2FWqHhz0oPxKK657buGhF4FSuENm/jvsKwdzuspfkZrrNS07P1mCP4KYywP9iKkQ1Csh7elhkw4=
SHA256 (Pkgfile) = f3dbb81a9e4e6dc6d840dfd027d66e794654d027275f497d03e5e83486309890
SHA256 (.footprint) = 1ba598a2be2720e475399c590284ec2db439af580211374c82bf30dfac5d83c2
SHA256 (cmake-3.17.0.tar.gz) = b74c05b55115eacc4fa2b77a814981dbda05cdc95a53e279fe16b7b272f00847

22
cmake/Pkgfile
View File

@ -2,28 +2,19 @@
# URL: http://www.cmake.org/
# Maintainer: Fredrik Rinnestam, fredrik at crux dot nu
# Depends on: curl libarchive expat ncurses
# Optional: python3-sphinx
name=cmake
version=3.17.1
version=3.17.0
release=1
source=(https://cmake.org/files/v${version%.*}/$name-$version.tar.gz
ccmake.1 cmake.1 cpack.1 ctest.1 cmake-buildsystem.7 cmake-commands.7
cmake-compile-features.7 cmake-developer.7 cmake-env-variables.7
cmake-file-api.7 cmake-generator-expressions.7 cmake-generators.7
cmake-language.7 cmake-modules.7 cmake-packages.7 cmake-policies.7
cmake-properties.7 cmake-qt.7 cmake-server.7 cmake-toolchains.7
cmake-variables.7 cpack-generators.7)
source=(https://www.cmake.org/files/v${version%.*}/$name-$version.tar.gz)
build() {
cd $name-$version
[ -e '/usr/bin/sphinx-autogen' ] && PKGMK_CMAKE+=' -sphinx-man'
sed -i Source/CMakeInstallDestinations.cmake \
-e 's|share/cmake-${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}|share/cmake|'
./bootstrap ${PKGMK_CMAKE} \
./bootstrap \
--prefix=/usr \
--system-curl \
--system-expat \
@ -31,16 +22,9 @@ build() {
--system-bzip2 \
--system-libarchive \
--no-system-librhash
make
make DESTDIR=$PKG install
rm -r $PKG/usr/doc
ln -sf $name $PKG/usr/share/$name-${version%.*}
if [ ! -e '/usr/bin/sphinx-autogen' ]; then
install -dm755 $PKG/usr/man/man{1,7}
install -m644 -t $PKG/usr/man/man1 $SRC/{ccmake,cmake,cpack,ctest}.1
install -m644 -t $PKG/usr/man/man7 $SRC/*.7
fi
}

347
cmake/ccmake.1
View File

@ -1,347 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CCMAKE" "1" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
ccmake \- CMake Curses Dialog Command-Line Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ccmake [<options>] {<path\-to\-source> | <path\-to\-existing\-build>}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
The \fBccmake\fP executable is the CMake curses interface. Project
configuration settings may be specified interactively through this
GUI. Brief instructions are provided at the bottom of the terminal
when the program is running.
.sp
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 \fBCMakeLists.txt\fP\&.
Users build a project by using CMake to generate a build system for a
native tool on their platform.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-S <path\-to\-source>\fP
Path to root directory of the CMake project to build.
.TP
.B \fB\-B <path\-to\-build>\fP
Path to directory which CMake will use as the root of build directory.
.sp
If the directory doesn\(aqt already exist CMake will make it.
.TP
.B \fB\-C <initial\-cache>\fP
Pre\-load a script to populate the cache.
.sp
When CMake is first run in an empty build tree, it creates a
\fBCMakeCache.txt\fP file and populates it with customizable settings for
the project. This option may be used to specify a file from which
to load cache entries before the first pass through the project\(aqs
CMake listfiles. The loaded entries take priority over the
project\(aqs default values. The given file should be a CMake script
containing \fBset()\fP commands that use the \fBCACHE\fP option, not a
cache\-format file.
.sp
References to \fBCMAKE_SOURCE_DIR\fP and \fBCMAKE_BINARY_DIR\fP
within the script evaluate to the top\-level source and build tree.
.TP
.B \fB\-D <var>:<type>=<value>, \-D <var>=<value>\fP
Create or update a CMake \fBCACHE\fP entry.
.sp
When CMake is first run in an empty build tree, it creates a
\fBCMakeCache.txt\fP file and populates it with customizable settings for
the project. This option may be used to specify a setting that
takes priority over the project\(aqs default value. The option may be
repeated for as many \fBCACHE\fP entries as desired.
.sp
If the \fB:<type>\fP portion is given it must be one of the types
specified by the \fBset()\fP command documentation for its
\fBCACHE\fP signature.
If the \fB:<type>\fP portion is omitted the entry will be created
with no type if it does not exist with a type already. If a
command in the project sets the type to \fBPATH\fP or \fBFILEPATH\fP
then the \fB<value>\fP will be converted to an absolute path.
.sp
This option may also be given as a single argument:
\fB\-D<var>:<type>=<value>\fP or \fB\-D<var>=<value>\fP\&.
.TP
.B \fB\-U <globbing_expr>\fP
Remove matching entries from CMake \fBCACHE\fP\&.
.sp
This option may be used to remove one or more variables from the
\fBCMakeCache.txt\fP file, globbing expressions using \fB*\fP and \fB?\fP are
supported. The option may be repeated for as many \fBCACHE\fP entries as
desired.
.sp
Use with care, you can make your \fBCMakeCache.txt\fP non\-working.
.TP
.B \fB\-G <generator\-name>\fP
Specify a build system generator.
.sp
CMake may support multiple native build systems on certain
platforms. A generator is responsible for generating a particular
build system. Possible generator names are specified in the
\fBcmake\-generators(7)\fP manual.
.sp
If not specified, CMake checks the \fBCMAKE_GENERATOR\fP environment
variable and otherwise falls back to a builtin default selection.
.TP
.B \fB\-T <toolset\-spec>\fP
Toolset specification for the generator, if supported.
.sp
Some CMake generators support a toolset specification to tell
the native build system how to choose a compiler. See the
\fBCMAKE_GENERATOR_TOOLSET\fP variable for details.
.TP
.B \fB\-A <platform\-name>\fP
Specify platform name if supported by generator.
.sp
Some CMake generators support a platform name to be given to the
native build system to choose a compiler or SDK. See the
\fBCMAKE_GENERATOR_PLATFORM\fP variable for details.
.TP
.B \fB\-Wno\-dev\fP
Suppress developer warnings.
.sp
Suppress warnings that are meant for the author of the
\fBCMakeLists.txt\fP files. By default this will also turn off
deprecation warnings.
.TP
.B \fB\-Wdev\fP
Enable developer warnings.
.sp
Enable warnings that are meant for the author of the \fBCMakeLists.txt\fP
files. By default this will also turn on deprecation warnings.
.TP
.B \fB\-Werror=dev\fP
Make developer warnings errors.
.sp
Make warnings that are meant for the author of the \fBCMakeLists.txt\fP files
errors. By default this will also turn on deprecated warnings as errors.
.TP
.B \fB\-Wno\-error=dev\fP
Make developer warnings not errors.
.sp
Make warnings that are meant for the author of the \fBCMakeLists.txt\fP files not
errors. By default this will also turn off deprecated warnings as errors.
.TP
.B \fB\-Wdeprecated\fP
Enable deprecated functionality warnings.
.sp
Enable warnings for usage of deprecated functionality, that are meant
for the author of the \fBCMakeLists.txt\fP files.
.TP
.B \fB\-Wno\-deprecated\fP
Suppress deprecated functionality warnings.
.sp
Suppress warnings for usage of deprecated functionality, that are meant
for the author of the \fBCMakeLists.txt\fP files.
.TP
.B \fB\-Werror=deprecated\fP
Make deprecated macro and function warnings errors.
.sp
Make warnings for usage of deprecated macros and functions, that are meant
for the author of the \fBCMakeLists.txt\fP files, errors.
.TP
.B \fB\-Wno\-error=deprecated\fP
Make deprecated macro and function warnings not errors.
.sp
Make warnings for usage of deprecated macros and functions, that are meant
for the author of the \fBCMakeLists.txt\fP files, not errors.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-\-help,\-help,\-usage,\-h,\-H,/?\fP
Print usage information and exit.
.sp
Usage describes the basic command line interface and its options.
.TP
.B \fB\-\-version,\-version,/V [<f>]\fP
Show program name/version banner and exit.
.sp
If a file is specified, the version is written into it.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-full [<f>]\fP
Print all help manuals and exit.
.sp
All manuals are printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-manual <man> [<f>]\fP
Print one help manual and exit.
.sp
The specified manual is printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-manual\-list [<f>]\fP
List help manuals available and exit.
.sp
The list contains all manuals for which help may be obtained by
using the \fB\-\-help\-manual\fP option followed by a manual name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-command <cmd> [<f>]\fP
Print help for one command and exit.
.sp
The \fBcmake\-commands(7)\fP manual entry for \fB<cmd>\fP is
printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-command\-list [<f>]\fP
List commands with help available and exit.
.sp
The list contains all commands for which help may be obtained by
using the \fB\-\-help\-command\fP option followed by a command name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-commands [<f>]\fP
Print cmake\-commands manual and exit.
.sp
The \fBcmake\-commands(7)\fP manual is printed in a
human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-module <mod> [<f>]\fP
Print help for one module and exit.
.sp
The \fBcmake\-modules(7)\fP manual entry for \fB<mod>\fP is printed
in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-module\-list [<f>]\fP
List modules with help available and exit.
.sp
The list contains all modules for which help may be obtained by
using the \fB\-\-help\-module\fP option followed by a module name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-modules [<f>]\fP
Print cmake\-modules manual and exit.
.sp
The \fBcmake\-modules(7)\fP manual is printed in a human\-readable
text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-policy <cmp> [<f>]\fP
Print help for one policy and exit.
.sp
The \fBcmake\-policies(7)\fP manual entry for \fB<cmp>\fP is
printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-policy\-list [<f>]\fP
List policies with help available and exit.
.sp
The list contains all policies for which help may be obtained by
using the \fB\-\-help\-policy\fP option followed by a policy name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-policies [<f>]\fP
Print cmake\-policies manual and exit.
.sp
The \fBcmake\-policies(7)\fP manual is printed in a
human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-property <prop> [<f>]\fP
Print help for one property and exit.
.sp
The \fBcmake\-properties(7)\fP manual entries for \fB<prop>\fP are
printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-property\-list [<f>]\fP
List properties with help available and exit.
.sp
The list contains all properties for which help may be obtained by
using the \fB\-\-help\-property\fP option followed by a property name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-properties [<f>]\fP
Print cmake\-properties manual and exit.
.sp
The \fBcmake\-properties(7)\fP manual is printed in a
human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-variable <var> [<f>]\fP
Print help for one variable and exit.
.sp
The \fBcmake\-variables(7)\fP manual entry for \fB<var>\fP is
printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-variable\-list [<f>]\fP
List variables with help available and exit.
.sp
The list contains all variables for which help may be obtained by
using the \fB\-\-help\-variable\fP option followed by a variable name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-variables [<f>]\fP
Print cmake\-variables manual and exit.
.sp
The \fBcmake\-variables(7)\fP manual is printed in a
human\-readable text format.
The help is printed to a named <f>ile if given.
.UNINDENT
.SH SEE ALSO
.sp
The following resources are available to get help using CMake:
.INDENT 0.0
.TP
.B Home Page
\fI\%https://cmake.org\fP
.sp
The primary starting point for learning about CMake.
.TP
.B Online Documentation and Community Resources
\fI\%https://cmake.org/documentation\fP
.sp
Links to available documentation and community resources may be
found on this web page.
.TP
.B Discourse Forum
\fI\%https://discourse.cmake.org\fP
.sp
The Discourse Forum hosts discussion and questions about CMake.
.UNINDENT
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

1196
cmake/cmake-buildsystem.7
View File

File diff suppressed because it is too large Load Diff

12281
cmake/cmake-commands.7
View File

File diff suppressed because it is too large Load Diff

481
cmake/cmake-compile-features.7
View File

@ -1,481 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CMAKE-COMPILE-FEATURES" "7" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
cmake-compile-features \- CMake Compile Features Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH INTRODUCTION
.sp
Project source code may depend on, or be conditional on, the availability
of certain features of the compiler. There are three use\-cases which arise:
\fI\%Compile Feature Requirements\fP, \fI\%Optional Compile Features\fP
and \fI\%Conditional Compilation Options\fP\&.
.sp
While features are typically specified in programming language standards,
CMake provides a primary user interface based on granular handling of
the features, not the language standard that introduced the feature.
.sp
The \fBCMAKE_C_KNOWN_FEATURES\fP, \fBCMAKE_CUDA_KNOWN_FEATURES\fP,
and \fBCMAKE_CXX_KNOWN_FEATURES\fP global properties contain all the
features known to CMake, regardless of compiler support for the feature.
The \fBCMAKE_C_COMPILE_FEATURES\fP, \fBCMAKE_CUDA_COMPILE_FEATURES\fP
, and \fBCMAKE_CXX_COMPILE_FEATURES\fP variables contain all features
CMake knows are known to the compiler, regardless of language standard
or compile flags needed to use them.
.sp
Features known to CMake are named mostly following the same convention
as the Clang feature test macros. There are some exceptions, such as
CMake using \fBcxx_final\fP and \fBcxx_override\fP instead of the single
\fBcxx_override_control\fP used by Clang.
.sp
Note that there are no separate compile features properties or variables for
the \fBOBJC\fP or \fBOBJCXX\fP languages. These are based off \fBC\fP or \fBC++\fP
respectively, so the properties and variables for their corresponding base
language should be used instead.
.SH COMPILE FEATURE REQUIREMENTS
.sp
Compile feature requirements may be specified with the
\fBtarget_compile_features()\fP command. For example, if a target must
be compiled with compiler support for the
\fBcxx_constexpr\fP feature:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
add_library(mylib requires_constexpr.cpp)
target_compile_features(mylib PRIVATE cxx_constexpr)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In processing the requirement for the \fBcxx_constexpr\fP feature,
\fBcmake(1)\fP will ensure that the in\-use C++ compiler is capable
of the feature, and will add any necessary flags such as \fB\-std=gnu++11\fP
to the compile lines of C++ files in the \fBmylib\fP target. A
\fBFATAL_ERROR\fP is issued if the compiler is not capable of the
feature.
.sp
The exact compile flags and language standard are deliberately not part
of the user interface for this use\-case. CMake will compute the
appropriate compile flags to use by considering the features specified
for each target.
.sp
Such compile flags are added even if the compiler supports the
particular feature without the flag. For example, the GNU compiler
supports variadic templates (with a warning) even if \fB\-std=gnu++98\fP is
used. CMake adds the \fB\-std=gnu++11\fP flag if \fBcxx_variadic_templates\fP
is specified as a requirement.
.sp
In the above example, \fBmylib\fP requires \fBcxx_constexpr\fP when it
is built itself, but consumers of \fBmylib\fP are not required to use a
compiler which supports \fBcxx_constexpr\fP\&. If the interface of
\fBmylib\fP does require the \fBcxx_constexpr\fP feature (or any other
known feature), that may be specified with the \fBPUBLIC\fP or
\fBINTERFACE\fP signatures of \fBtarget_compile_features()\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
add_library(mylib requires_constexpr.cpp)
# cxx_constexpr is a usage\-requirement
target_compile_features(mylib PUBLIC cxx_constexpr)
# main.cpp will be compiled with \-std=gnu++11 on GNU for cxx_constexpr.
add_executable(myexe main.cpp)
target_link_libraries(myexe mylib)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Feature requirements are evaluated transitively by consuming the link
implementation. See \fBcmake\-buildsystem(7)\fP for more on
transitive behavior of build properties and usage requirements.
.SS Requiring Language Standards
.sp
In projects that use a large number of commonly available features from
a particular language standard (e.g. C++ 11) one may specify a
meta\-feature (e.g. \fBcxx_std_11\fP) that requires use of a compiler mode
that is at minimum aware of that standard, but could be greater.
This is simpler than specifying all the features individually, but does
not guarantee the existence of any particular feature.
Diagnosis of use of unsupported features will be delayed until compile time.
.sp
For example, if C++ 11 features are used extensively in a project\(aqs
header files, then clients must use a compiler mode that is no less
than C++ 11. This can be requested with the code:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
target_compile_features(mylib PUBLIC cxx_std_11)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example, CMake will ensure the compiler is invoked in a mode
of at\-least C++ 11 (or C++ 14, C++ 17, ...), adding flags such as
\fB\-std=gnu++11\fP if necessary. This applies to sources within \fBmylib\fP
as well as any dependents (that may include headers from \fBmylib\fP).
.SS Availability of Compiler Extensions
.sp
Because the \fBCXX_EXTENSIONS\fP target property is \fBON\fP by default,
CMake uses extended variants of language dialects by default, such as
\fB\-std=gnu++11\fP instead of \fB\-std=c++11\fP\&. That target property may be
set to \fBOFF\fP to use the non\-extended variant of the dialect flag. Note
that because most compilers enable extensions by default, this could
expose cross\-platform bugs in user code or in the headers of third\-party
dependencies.
.SH OPTIONAL COMPILE FEATURES
.sp
Compile features may be preferred if available, without creating a hard
requirement. For example, a library may provides alternative
implementations depending on whether the \fBcxx_variadic_templates\fP
feature is available:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
template<int I, int... Is>
struct Interface;
template<int I>
struct Interface<I>
{
static int accumulate()
{
return I;
}
};
template<int I, int... Is>
struct Interface
{
static int accumulate()
{
return I + Interface<Is...>::accumulate();
}
};
#else
template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
struct Interface
{
static int accumulate() { return I1 + I2 + I3 + I4; }
};
#endif
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Such an interface depends on using the correct preprocessor defines for the
compiler features. CMake can generate a header file containing such
defines using the \fBWriteCompilerDetectionHeader\fP module. The
module contains the \fBwrite_compiler_detection_header\fP function which
accepts parameters to control the content of the generated header file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
write_compiler_detection_header(
FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
PREFIX Foo
COMPILERS GNU
FEATURES
cxx_variadic_templates
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Such a header file may be used internally in the source code of a project,
and it may be installed and used in the interface of library code.
.sp
For each feature listed in \fBFEATURES\fP, a preprocessor definition
is created in the header file, and defined to either \fB1\fP or \fB0\fP\&.
.sp
Additionally, some features call for additional defines, such as the
\fBcxx_final\fP and \fBcxx_override\fP features. Rather than being used in
\fB#ifdef\fP code, the \fBfinal\fP keyword is abstracted by a symbol
which is defined to either \fBfinal\fP, a compiler\-specific equivalent, or
to empty. That way, C++ code can be written to unconditionally use the
symbol, and compiler support determines what it is expanded to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
struct Interface {
virtual void Execute() = 0;
};
struct Concrete Foo_FINAL {
void Execute() Foo_OVERRIDE;
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this case, \fBFoo_FINAL\fP will expand to \fBfinal\fP if the
compiler supports the keyword, or to empty otherwise.
.sp
In this use\-case, the CMake code will wish to enable a particular language
standard if available from the compiler. The \fBCXX_STANDARD\fP
target property variable may be set to the desired language standard
for a particular target, and the \fBCMAKE_CXX_STANDARD\fP may be
set to influence all following targets:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
write_compiler_detection_header(
FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
PREFIX Foo
COMPILERS GNU
FEATURES
cxx_final cxx_override
)
# Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
# which will expand to \(aqfinal\(aq if the compiler supports the requested
# CXX_STANDARD.
add_library(foo foo.cpp)
set_property(TARGET foo PROPERTY CXX_STANDARD 11)
# Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
# which will expand to \(aqfinal\(aq if the compiler supports the feature,
# even though CXX_STANDARD is not set explicitly. The requirement of
# cxx_constexpr causes CMake to set CXX_STANDARD internally, which
# affects the compile flags.
add_library(foo_impl foo_impl.cpp)
target_compile_features(foo_impl PRIVATE cxx_constexpr)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBwrite_compiler_detection_header\fP function also creates compatibility
code for other features which have standard equivalents. For example, the
\fBcxx_static_assert\fP feature is emulated with a template and abstracted
via the \fB<PREFIX>_STATIC_ASSERT\fP and \fB<PREFIX>_STATIC_ASSERT_MSG\fP
function\-macros.
.SH CONDITIONAL COMPILATION OPTIONS
.sp
Libraries may provide entirely different header files depending on
requested compiler features.
.sp
For example, a header at \fBwith_variadics/interface.h\fP may contain:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
template<int I, int... Is>
struct Interface;
template<int I>
struct Interface<I>
{
static int accumulate()
{
return I;
}
};
template<int I, int... Is>
struct Interface
{
static int accumulate()
{
return I + Interface<Is...>::accumulate();
}
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
while a header at \fBno_variadics/interface.h\fP may contain:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
struct Interface
{
static int accumulate() { return I1 + I2 + I3 + I4; }
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It would be possible to write a abstraction \fBinterface.h\fP header
containing something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include "foo_compiler_detection.h"
#if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
#include "with_variadics/interface.h"
#else
#include "no_variadics/interface.h"
#endif
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
However this could be unmaintainable if there are many files to
abstract. What is needed is to use alternative include directories
depending on the compiler capabilities.
.sp
CMake provides a \fBCOMPILE_FEATURES\fP
\fBgenerator expression\fP to implement
such conditions. This may be used with the build\-property commands such as
\fBtarget_include_directories()\fP and \fBtarget_link_libraries()\fP
to set the appropriate \fBbuildsystem\fP
properties:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
add_library(foo INTERFACE)
set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics)
set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics)
target_include_directories(foo
INTERFACE
"$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>"
"$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>"
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Consuming code then simply links to the \fBfoo\fP target as usual and uses
the feature\-appropriate include directory
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
add_executable(consumer_with consumer_with.cpp)
target_link_libraries(consumer_with foo)
set_property(TARGET consumer_with CXX_STANDARD 11)
add_executable(consumer_no consumer_no.cpp)
target_link_libraries(consumer_no foo)
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SUPPORTED COMPILERS
.sp
CMake is currently aware of the \fBC++ standards\fP
and \fBcompile features\fP available from
the following \fBcompiler ids\fP as of the
versions specified for each:
.INDENT 0.0
.IP \(bu 2
\fBAppleClang\fP: Apple Clang for Xcode versions 4.4+.
.IP \(bu 2
\fBClang\fP: Clang compiler versions 2.9+.
.IP \(bu 2
\fBGNU\fP: GNU compiler versions 4.4+.
.IP \(bu 2
\fBMSVC\fP: Microsoft Visual Studio versions 2010+.
.IP \(bu 2
\fBSunPro\fP: Oracle SolarisStudio versions 12.4+.
.IP \(bu 2
\fBIntel\fP: Intel compiler versions 12.1+.
.UNINDENT
.sp
CMake is currently aware of the \fBC standards\fP
and \fBcompile features\fP available from
the following \fBcompiler ids\fP as of the
versions specified for each:
.INDENT 0.0
.IP \(bu 2
all compilers and versions listed above for C++.
.IP \(bu 2
\fBGNU\fP: GNU compiler versions 3.4+
.UNINDENT
.sp
CMake is currently aware of the \fBC++ standards\fP and
their associated meta\-features (e.g. \fBcxx_std_11\fP) available from the
following \fBcompiler ids\fP as of the
versions specified for each:
.INDENT 0.0
.IP \(bu 2
\fBCray\fP: Cray Compiler Environment version 8.1+.
.IP \(bu 2
\fBPGI\fP: PGI version 12.10+.
.IP \(bu 2
\fBXL\fP: IBM XL version 10.1+.
.UNINDENT
.sp
CMake is currently aware of the \fBC standards\fP and
their associated meta\-features (e.g. \fBc_std_99\fP) available from the
following \fBcompiler ids\fP as of the
versions specified for each:
.INDENT 0.0
.IP \(bu 2
all compilers and versions listed above with only meta\-features for C++.
.IP \(bu 2
\fBTI\fP: Texas Instruments compiler.
.UNINDENT
.sp
CMake is currently aware of the \fBCUDA standards\fP and
their associated meta\-features (e.g. \fBcuda_std_11\fP) available from the
following \fBcompiler ids\fP as of the
versions specified for each:
.INDENT 0.0
.IP \(bu 2
\fBNVIDIA\fP: NVIDIA nvcc compiler 7.5+.
.UNINDENT
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

521
cmake/cmake-developer.7
View File

@ -1,521 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CMAKE-DEVELOPER" "7" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
cmake-developer \- CMake Developer Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH INTRODUCTION
.sp
This manual is intended for reference by developers working with
\fBcmake\-language(7)\fP code, whether writing their own modules,
authoring their own build systems, or working on CMake itself.
.sp
See \fI\%https://cmake.org/get\-involved/\fP to get involved in development of
CMake upstream. It includes links to contribution instructions, which
in turn link to developer guides for CMake itself.
.SH FIND MODULES
.sp
A "find module" is a \fBFind<PackageName>.cmake\fP file to be loaded
by the \fBfind_package()\fP command when invoked for \fB<PackageName>\fP\&.
.sp
The primary task of a find module is to determine whether a package
exists on the system, set the \fB<PackageName>_FOUND\fP variable to reflect
this and provide any variables, macros and imported targets required to
use the package. A find module is useful in cases where an upstream
library does not provide a
config file package\&.
.sp
The traditional approach is to use variables for everything, including
libraries and executables: see the \fI\%Standard Variable Names\fP section
below. This is what most of the existing find modules provided by CMake
do.
.sp
The more modern approach is to behave as much like
config file packages files as possible, by
providing imported target\&. This has the advantage
of propagating Target Usage Requirements to consumers.
.sp
In either case (or even when providing both variables and imported
targets), find modules should provide backwards compatibility with old
versions that had the same name.
.sp
A FindFoo.cmake module will typically be loaded by the command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(Foo [major[.minor[.patch[.tweak]]]]
[EXACT] [QUIET] [REQUIRED]
[[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[NO_POLICY_SCOPE])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See the \fBfind_package()\fP documentation for details on what
variables are set for the find module. Most of these are dealt with by
using \fBFindPackageHandleStandardArgs\fP\&.
.sp
Briefly, the module should only locate versions of the package
compatible with the requested version, as described by the
\fBFoo_FIND_VERSION\fP family of variables. If \fBFoo_FIND_QUIETLY\fP is
set to true, it should avoid printing messages, including anything
complaining about the package not being found. If \fBFoo_FIND_REQUIRED\fP
is set to true, the module should issue a \fBFATAL_ERROR\fP if the package
cannot be found. If neither are set to true, it should print a
non\-fatal message if it cannot find the package.
.sp
Packages that find multiple semi\-independent parts (like bundles of
libraries) should search for the components listed in
\fBFoo_FIND_COMPONENTS\fP if it is set , and only set \fBFoo_FOUND\fP to
true if for each searched\-for component \fB<c>\fP that was not found,
\fBFoo_FIND_REQUIRED_<c>\fP is not set to true. The \fBHANDLE_COMPONENTS\fP
argument of \fBfind_package_handle_standard_args()\fP can be used to
implement this.
.sp
If \fBFoo_FIND_COMPONENTS\fP is not set, which modules are searched for
and required is up to the find module, but should be documented.
.sp
For internal implementation, it is a generally accepted convention that
variables starting with underscore are for temporary use only.
.SS Standard Variable Names
.sp
For a \fBFindXxx.cmake\fP module that takes the approach of setting
variables (either instead of or in addition to creating imported
targets), the following variable names should be used to keep things
consistent between find modules. Note that all variables start with
\fBXxx_\fP to make sure they do not interfere with other find modules; the
same consideration applies to macros, functions and imported targets.
.INDENT 0.0
.TP
.B \fBXxx_INCLUDE_DIRS\fP
The final set of include directories listed in one variable for use by
client code. This should not be a cache entry.
.TP
.B \fBXxx_LIBRARIES\fP
The libraries to link against to use Xxx. These should include full
paths. This should not be a cache entry.
.TP
.B \fBXxx_DEFINITIONS\fP
Definitions to use when compiling code that uses Xxx. This really
shouldn\(aqt include options such as \fB\-DHAS_JPEG\fP that a client
source\-code file uses to decide whether to \fB#include <jpeg.h>\fP
.TP
.B \fBXxx_EXECUTABLE\fP
Where to find the Xxx tool.
.TP
.B \fBXxx_Yyy_EXECUTABLE\fP
Where to find the Yyy tool that comes with Xxx.
.TP
.B \fBXxx_LIBRARY_DIRS\fP
Optionally, the final set of library directories listed in one
variable for use by client code. This should not be a cache entry.
.TP
.B \fBXxx_ROOT_DIR\fP
Where to find the base directory of Xxx.
.TP
.B \fBXxx_VERSION_Yy\fP
Expect Version Yy if true. Make sure at most one of these is ever true.
.TP
.B \fBXxx_WRAP_Yy\fP
If False, do not try to use the relevant CMake wrapping command.
.TP
.B \fBXxx_Yy_FOUND\fP
If False, optional Yy part of Xxx system is not available.
.TP
.B \fBXxx_FOUND\fP
Set to false, or undefined, if we haven\(aqt found, or don\(aqt want to use
Xxx.
.TP
.B \fBXxx_NOT_FOUND_MESSAGE\fP
Should be set by config\-files in the case that it has set
\fBXxx_FOUND\fP to FALSE. The contained message will be printed by the
\fBfind_package()\fP command and by
\fBfind_package_handle_standard_args()\fP to inform the user about the
problem.
.TP
.B \fBXxx_RUNTIME_LIBRARY_DIRS\fP
Optionally, the runtime library search path for use when running an
executable linked to shared libraries. The list should be used by
user code to create the \fBPATH\fP on windows or \fBLD_LIBRARY_PATH\fP on
UNIX. This should not be a cache entry.
.TP
.B \fBXxx_VERSION\fP
The full version string of the package found, if any. Note that many
existing modules provide \fBXxx_VERSION_STRING\fP instead.
.TP
.B \fBXxx_VERSION_MAJOR\fP
The major version of the package found, if any.
.TP
.B \fBXxx_VERSION_MINOR\fP
The minor version of the package found, if any.
.TP
.B \fBXxx_VERSION_PATCH\fP
The patch version of the package found, if any.
.UNINDENT
.sp
The following names should not usually be used in CMakeLists.txt files, but
are typically cache variables for users to edit and control the
behaviour of find modules (like entering the path to a library manually)
.INDENT 0.0
.TP
.B \fBXxx_LIBRARY\fP
The path of the Xxx library (as used with \fBfind_library()\fP, for
example).
.TP
.B \fBXxx_Yy_LIBRARY\fP
The path of the Yy library that is part of the Xxx system. It may or
may not be required to use Xxx.
.TP
.B \fBXxx_INCLUDE_DIR\fP
Where to find headers for using the Xxx library.
.TP
.B \fBXxx_Yy_INCLUDE_DIR\fP
Where to find headers for using the Yy library of the Xxx system.
.UNINDENT
.sp
To prevent users being overwhelmed with settings to configure, try to
keep as many options as possible out of the cache, leaving at least one
option which can be used to disable use of the module, or locate a
not\-found library (e.g. \fBXxx_ROOT_DIR\fP). For the same reason, mark
most cache options as advanced. For packages which provide both debug
and release binaries, it is common to create cache variables with a
\fB_LIBRARY_<CONFIG>\fP suffix, such as \fBFoo_LIBRARY_RELEASE\fP and
\fBFoo_LIBRARY_DEBUG\fP\&.
.sp
While these are the standard variable names, you should provide
backwards compatibility for any old names that were actually in use.
Make sure you comment them as deprecated, so that no\-one starts using
them.
.SS A Sample Find Module
.sp
We will describe how to create a simple find module for a library \fBFoo\fP\&.
.sp
The top of the module should begin with a license notice, followed by
a blank line, and then followed by a Bracket Comment\&. The comment
should begin with \fB\&.rst:\fP to indicate that the rest of its content is
reStructuredText\-format documentation. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Distributed under the OSI\-approved BSD 3\-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#[=======================================================================[.rst:
FindFoo
\-\-\-\-\-\-\-
Finds the Foo library.
Imported Targets
^^^^^^^^^^^^^^^^
This module provides the following imported targets, if found:
\(ga\(gaFoo::Foo\(ga\(ga
The Foo library
Result Variables
^^^^^^^^^^^^^^^^
This will define the following variables:
\(ga\(gaFoo_FOUND\(ga\(ga
True if the system has the Foo library.
\(ga\(gaFoo_VERSION\(ga\(ga
The version of the Foo library which was found.
\(ga\(gaFoo_INCLUDE_DIRS\(ga\(ga
Include directories needed to use Foo.
\(ga\(gaFoo_LIBRARIES\(ga\(ga
Libraries needed to link to Foo.
Cache Variables
^^^^^^^^^^^^^^^
The following cache variables may also be set:
\(ga\(gaFoo_INCLUDE_DIR\(ga\(ga
The directory containing \(ga\(gafoo.h\(ga\(ga.
\(ga\(gaFoo_LIBRARY\(ga\(ga
The path to the Foo library.
#]=======================================================================]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The module documentation consists of:
.INDENT 0.0
.IP \(bu 2
An underlined heading specifying the module name.
.IP \(bu 2
A simple description of what the module finds.
More description may be required for some packages. If there are
caveats or other details users of the module should be aware of,
specify them here.
.IP \(bu 2
A section listing imported targets provided by the module, if any.
.IP \(bu 2
A section listing result variables provided by the module.
.IP \(bu 2
Optionally a section listing cache variables used by the module, if any.
.UNINDENT
.sp
If the package provides any macros or functions, they should be listed in
an additional section, but can be documented by additional \fB\&.rst:\fP
comment blocks immediately above where those macros or functions are defined.
.sp
The find module implementation may begin below the documentation block.
Now the actual libraries and so on have to be found. The code here will
obviously vary from module to module (dealing with that, after all, is the
point of find modules), but there tends to be a common pattern for libraries.
.sp
First, we try to use \fBpkg\-config\fP to find the library. Note that we
cannot rely on this, as it may not be available, but it provides a good
starting point.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(PkgConfig)
pkg_check_modules(PC_Foo QUIET Foo)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This should define some variables starting \fBPC_Foo_\fP that contain the
information from the \fBFoo.pc\fP file.
.sp
Now we need to find the libraries and include files; we use the
information from \fBpkg\-config\fP to provide hints to CMake about where to
look.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_path(Foo_INCLUDE_DIR
NAMES foo.h
PATHS ${PC_Foo_INCLUDE_DIRS}
PATH_SUFFIXES Foo
)
find_library(Foo_LIBRARY
NAMES foo
PATHS ${PC_Foo_LIBRARY_DIRS}
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you have a good way of getting the version (from a header file, for
example), you can use that information to set \fBFoo_VERSION\fP (although
note that find modules have traditionally used \fBFoo_VERSION_STRING\fP,
so you may want to set both). Otherwise, attempt to use the information
from \fBpkg\-config\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(Foo_VERSION ${PC_Foo_VERSION})
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now we can use \fBFindPackageHandleStandardArgs\fP to do most of the
rest of the work for us
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(Foo
FOUND_VAR Foo_FOUND
REQUIRED_VARS
Foo_LIBRARY
Foo_INCLUDE_DIR
VERSION_VAR Foo_VERSION
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will check that the \fBREQUIRED_VARS\fP contain values (that do not
end in \fB\-NOTFOUND\fP) and set \fBFoo_FOUND\fP appropriately. It will also
cache those values. If \fBFoo_VERSION\fP is set, and a required version
was passed to \fBfind_package()\fP, it will check the requested version
against the one in \fBFoo_VERSION\fP\&. It will also print messages as
appropriate; note that if the package was found, it will print the
contents of the first required variable to indicate where it was found.
.sp
At this point, we have to provide a way for users of the find module to
link to the library or libraries that were found. There are two
approaches, as discussed in the \fI\%Find Modules\fP section above. The
traditional variable approach looks like
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if(Foo_FOUND)
set(Foo_LIBRARIES ${Foo_LIBRARY})
set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR})
set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER})
endif()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If more than one library was found, all of them should be included in
these variables (see the \fI\%Standard Variable Names\fP section for more
information).
.sp
When providing imported targets, these should be namespaced (hence the
\fBFoo::\fP prefix); CMake will recognize that values passed to
\fBtarget_link_libraries()\fP that contain \fB::\fP in their name are
supposed to be imported targets (rather than just library names), and
will produce appropriate diagnostic messages if that target does not
exist (see policy \fBCMP0028\fP).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if(Foo_FOUND AND NOT TARGET Foo::Foo)
add_library(Foo::Foo UNKNOWN IMPORTED)
set_target_properties(Foo::Foo PROPERTIES
IMPORTED_LOCATION "${Foo_LIBRARY}"
INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}"
INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
)
endif()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
One thing to note about this is that the \fBINTERFACE_INCLUDE_DIRECTORIES\fP and
similar properties should only contain information about the target itself, and
not any of its dependencies. Instead, those dependencies should also be
targets, and CMake should be told that they are dependencies of this target.
CMake will then combine all the necessary information automatically.
.sp
The type of the \fBIMPORTED\fP target created in the
\fBadd_library()\fP command can always be specified as \fBUNKNOWN\fP
type. This simplifies the code in cases where static or shared variants may
be found, and CMake will determine the type by inspecting the files.
.sp
If the library is available with multiple configurations, the
\fBIMPORTED_CONFIGURATIONS\fP target property should also be
populated:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if(Foo_FOUND)
if (NOT TARGET Foo::Foo)
add_library(Foo::Foo UNKNOWN IMPORTED)
endif()
if (Foo_LIBRARY_RELEASE)
set_property(TARGET Foo::Foo APPEND PROPERTY
IMPORTED_CONFIGURATIONS RELEASE
)
set_target_properties(Foo::Foo PROPERTIES
IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}"
)
endif()
if (Foo_LIBRARY_DEBUG)
set_property(TARGET Foo::Foo APPEND PROPERTY
IMPORTED_CONFIGURATIONS DEBUG
)
set_target_properties(Foo::Foo PROPERTIES
IMPORTED_LOCATION_DEBUG "${Foo_LIBRARY_DEBUG}"
)
endif()
set_target_properties(Foo::Foo PROPERTIES
INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}"
INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
)
endif()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBRELEASE\fP variant should be listed first in the property
so that the variant is chosen if the user uses a configuration which is
not an exact match for any listed \fBIMPORTED_CONFIGURATIONS\fP\&.
.sp
Most of the cache variables should be hidden in the \fBccmake\fP interface unless
the user explicitly asks to edit them.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mark_as_advanced(
Foo_INCLUDE_DIR
Foo_LIBRARY
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If this module replaces an older version, you should set compatibility variables
to cause the least disruption possible.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# compatibility variables
set(Foo_VERSION_STRING ${Foo_VERSION})
.ft P
.fi
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

456
cmake/cmake-env-variables.7
View File

@ -1,456 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CMAKE-ENV-VARIABLES" "7" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
cmake-env-variables \- CMake Environment Variables Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
This page lists environment variables that have special
meaning to CMake.
.sp
For general information on environment variables, see the
Environment Variables
section in the cmake\-language manual.
.SH ENVIRONMENT VARIABLES THAT CONTROL THE BUILD
.SS CMAKE_BUILD_PARALLEL_LEVEL
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Specifies the maximum number of concurrent processes to use when building
using the \fBcmake \-\-build\fP command line
Build Tool Mode\&.
.sp
If this variable is defined empty the native build tool\(aqs default number is
used.
.SS CMAKE_CONFIG_TYPE
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
The default build configuration for Build Tool Mode and
\fBctest\fP build handler when there is no explicit configuration given.
.SS CMAKE_EXPORT_COMPILE_COMMANDS
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
The default value for \fBCMAKE_EXPORT_COMPILE_COMMANDS\fP when there
is no explicit configuration given on the first run while creating a new
build tree. On later runs in an existing build tree the value persists in
the cache as \fBCMAKE_EXPORT_COMPILE_COMMANDS\fP\&.
.SS CMAKE_GENERATOR
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Specifies the CMake default generator to use when no generator is supplied
with \fB\-G\fP\&. If the provided value doesn\(aqt name a generator known by CMake,
the internal default is used. Either way the resulting generator selection
is stored in the \fBCMAKE_GENERATOR\fP variable.
.sp
Some generators may be additionally configured using the environment
variables:
.INDENT 0.0
.IP \(bu 2
\fBCMAKE_GENERATOR_PLATFORM\fP
.IP \(bu 2
\fBCMAKE_GENERATOR_TOOLSET\fP
.IP \(bu 2
\fBCMAKE_GENERATOR_INSTANCE\fP
.UNINDENT
.SS CMAKE_GENERATOR_INSTANCE
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Default value for \fBCMAKE_GENERATOR_INSTANCE\fP if no Cache entry is
present. This value is only applied if \fBCMAKE_GENERATOR\fP is set.
.SS CMAKE_GENERATOR_PLATFORM
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Default value for \fBCMAKE_GENERATOR_PLATFORM\fP if no Cache entry
is present and no value is specified by \fBcmake(1)\fP \fB\-A\fP option.
This value is only applied if \fBCMAKE_GENERATOR\fP is set.
.SS CMAKE_GENERATOR_TOOLSET
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Default value for \fBCMAKE_GENERATOR_TOOLSET\fP if no Cache entry
is present and no value is specified by \fBcmake(1)\fP \fB\-T\fP option.
This value is only applied if \fBCMAKE_GENERATOR\fP is set.
.SS CMAKE_<LANG>_COMPILER_LAUNCHER
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Default compiler launcher to use for the specified language. Will only be used
by CMake to initialize the variable on the first configuration. Afterwards, it
is available through the cache setting of the variable of the same name. For
any configuration run (including the first), the environment variable will be
ignored if the \fBCMAKE_<LANG>_COMPILER_LAUNCHER\fP variable is defined.
.SS CMAKE_MSVCIDE_RUN_PATH
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Extra PATH locations for custom commands when using
\fBVisual Studio 9 2008\fP (or above) generators.
.sp
The \fBCMAKE_MSVCIDE_RUN_PATH\fP environment variable sets the default value for
the \fBCMAKE_MSVCIDE_RUN_PATH\fP variable if not already explicitly set.
.SS CMAKE_NO_VERBOSE
.sp
Disables verbose output from CMake when \fBVERBOSE\fP environment variable
is set.
.sp
Only your build tool of choice will still print verbose output when you start
to actually build your project.
.SS CMAKE_OSX_ARCHITECTURES
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Target specific architectures for macOS.
.sp
The \fBCMAKE_OSX_ARCHITECTURES\fP environment variable sets the default value for
the \fBCMAKE_OSX_ARCHITECTURES\fP variable. See
\fBOSX_ARCHITECTURES\fP for more information.
.SS DESTDIR
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
On UNIX one can use the \fBDESTDIR\fP mechanism in order to relocate the
whole installation. \fBDESTDIR\fP means DESTination DIRectory. It is
commonly used by makefile users in order to install software at
non\-default location. It is usually invoked like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make DESTDIR=/home/john install
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
which will install the concerned software using the installation
prefix, e.g. \fB/usr/local\fP prepended with the \fBDESTDIR\fP value which
finally gives \fB/home/john/usr/local\fP\&.
.sp
WARNING: \fBDESTDIR\fP may not be used on Windows because installation
prefix usually contains a drive letter like in \fBC:/Program Files\fP
which cannot be prepended with some other prefix.
.SS LDFLAGS
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Will only be used by CMake on the first configuration to determine the default
linker flags, after which the value for \fBLDFLAGS\fP is stored in the cache
as \fBCMAKE_EXE_LINKER_FLAGS_INIT\fP,
\fBCMAKE_SHARED_LINKER_FLAGS_INIT\fP, and
\fBCMAKE_MODULE_LINKER_FLAGS_INIT\fP\&. For any configuration run
(including the first), the environment variable will be ignored if the
equivalent \fBCMAKE_<TYPE>_LINKER_FLAGS_INIT\fP variable is defined.
.SS MACOSX_DEPLOYMENT_TARGET
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Specify the minimum version of macOS on which the target binaries are
to be deployed.
.sp
The \fBMACOSX_DEPLOYMENT_TARGET\fP environment variable sets the default value for
the \fBCMAKE_OSX_DEPLOYMENT_TARGET\fP variable.
.SS <PackageName>_ROOT
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Calls to \fBfind_package(<PackageName>)\fP will search in prefixes
specified by the \fB<PackageName>_ROOT\fP environment variable, where
\fB<PackageName>\fP is the name given to the \fBfind_package()\fP call
and \fB_ROOT\fP is literal. For example, \fBfind_package(Foo)\fP will search
prefixes specified in the \fBFoo_ROOT\fP environment variable (if set).
See policy \fBCMP0074\fP\&.
.sp
This variable may hold a single prefix or a list of prefixes separated
by \fB:\fP on UNIX or \fB;\fP on Windows (the same as the \fBPATH\fP environment
variable convention on those platforms).
.sp
See also the \fB<PackageName>_ROOT\fP CMake variable.
.SS VERBOSE
.sp
Activates verbose output from CMake and your build tools of choice when
you start to actually build your project.
.sp
Note that any given value is ignored. It\(aqs just checked for existence.
.sp
See also Build Tool Mode and
\fBCMAKE_NO_VERBOSE\fP environment variable
.SH ENVIRONMENT VARIABLES FOR LANGUAGES
.SS ASM<DIALECT>
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling a specific dialect of assembly language
files. \fBASM<DIALECT>\fP can be \fBASM\fP, \fBASM_NASM\fP (Netwide Assembler),
\fBASM_MASM\fP (Microsoft Assembler) or \fBASM\-ATT\fP (Assembler AT&T).
Will only be used by CMake on the first configuration to determine
\fBASM<DIALECT>\fP compiler, after which the value for \fBASM<DIALECT>\fP is stored
in the cache as
\fBCMAKE_ASM<DIALECT>_COMPILER\fP\&. For subsequent
configuration runs, the environment variable will be ignored in favor of
\fBCMAKE_ASM<DIALECT>_COMPILER\fP\&.
.SS ASM<DIALECT>FLAGS
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Default compilation flags to be used when compiling a specific dialect of an
assembly language. \fBASM<DIALECT>FLAGS\fP can be \fBASMFLAGS\fP, \fBASM_NASMFLAGS\fP,
\fBASM_MASMFLAGS\fP or \fBASM\-ATTFLAGS\fP\&. Will only be used by CMake on the
first configuration to determine \fBASM_<DIALECT>\fP default compilation
flags, after which the value for \fBASM<DIALECT>FLAGS\fP is stored in the cache
as \fBCMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>\fP\&. For any configuration
run (including the first), the environment variable will be ignored, if the
\fBCMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>\fP variable is defined.
.SS CC
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBC\fP language files. Will only be used by
CMake on the first configuration to determine \fBC\fP compiler, after which the
value for \fBCC\fP is stored in the cache as
\fBCMAKE_C_COMPILER\fP\&. For any configuration run
(including the first), the environment variable will be ignored if the
\fBCMAKE_C_COMPILER\fP variable is defined.
.SS CFLAGS
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Default compilation flags to be used when compiling \fBC\fP files. Will only be
used by CMake on the first configuration to determine \fBCC\fP default compilation
flags, after which the value for \fBCFLAGS\fP is stored in the cache
as \fBCMAKE_C_FLAGS\fP\&. For any configuration run
(including the first), the environment variable will be ignored if the
\fBCMAKE_C_FLAGS\fP variable is defined.
.SS CSFLAGS
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBCSharp\fP language files. Will only be
used by CMake on the first configuration to determine \fBCSharp\fP default
compilation flags, after which the value for \fBCSFLAGS\fP is stored in the cache
as \fBCMAKE_CSharp_FLAGS\fP\&. For any configuration
run (including the first), the environment variable will be ignored if the
\fBCMAKE_CSharp_FLAGS\fP variable is defined.
.SS CUDACXX
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBCUDA\fP language files. Will only be used by
CMake on the first configuration to determine \fBCUDA\fP compiler, after which the
value for \fBCUDA\fP is stored in the cache as
\fBCMAKE_CUDA_COMPILER\fP\&. For any configuration
run (including the first), the environment variable will be ignored if the
\fBCMAKE_CUDA_COMPILER\fP variable is defined.
.SS CUDAFLAGS
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Default compilation flags to be used when compiling \fBCUDA\fP files. Will only be
used by CMake on the first configuration to determine \fBCUDA\fP default
compilation flags, after which the value for \fBCUDAFLAGS\fP is stored in the
cache as \fBCMAKE_CUDA_FLAGS\fP\&. For any configuration
run (including the first), the environment variable will be ignored if
the \fBCMAKE_CUDA_FLAGS\fP variable is defined.
.SS CUDAHOSTCXX
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling host code when compiling \fBCUDA\fP
language files. Will only be used by CMake on the first configuration to
determine \fBCUDA\fP host compiler, after which the value for \fBCUDAHOSTCXX\fP is
stored in the cache as \fBCMAKE_CUDA_HOST_COMPILER\fP\&. For any
configuration run (including the first), the environment variable will be
ignored if the \fBCMAKE_CUDA_HOST_COMPILER\fP variable is defined.
.sp
This environment variable is primarily meant for use with projects that
enable \fBCUDA\fP as a first\-class language. The \fBFindCUDA\fP
module will also use it to initialize its \fBCUDA_HOST_COMPILER\fP setting.
.SS CXX
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBCXX\fP language files. Will only be used by
CMake on the first configuration to determine \fBCXX\fP compiler, after which the
value for \fBCXX\fP is stored in the cache as
\fBCMAKE_CXX_COMPILER\fP\&. For any configuration
run (including the first), the environment variable will be ignored if the
\fBCMAKE_CXX_COMPILER\fP variable is defined.
.SS CXXFLAGS
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Default compilation flags to be used when compiling \fBCXX\fP (C++) files. Will
only be used by CMake on the first configuration to determine \fBCXX\fP default
compilation flags, after which the value for \fBCXXFLAGS\fP is stored in the cache
as \fBCMAKE_CXX_FLAGS\fP\&. For any configuration run (
including the first), the environment variable will be ignored if
the \fBCMAKE_CXX_FLAGS\fP variable is defined.
.SS FC
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBFortran\fP language files. Will only be used
by CMake on the first configuration to determine \fBFortran\fP compiler, after
which the value for \fBFortran\fP is stored in the cache as
\fBCMAKE_Fortran_COMPILER\fP\&. For any
configuration run (including the first), the environment variable will be
ignored if the \fBCMAKE_Fortran_COMPILER\fP
variable is defined.
.SS FFLAGS
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Default compilation flags to be used when compiling \fBFortran\fP files. Will only
be used by CMake on the first configuration to determine \fBFortran\fP default
compilation flags, after which the value for \fBFFLAGS\fP is stored in the cache
as \fBCMAKE_Fortran_FLAGS\fP\&. For any configuration
run (including the first), the environment variable will be ignored if
the \fBCMAKE_Fortran_FLAGS\fP variable is defined.
.SS RC
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBresource\fP files. Will only be used by CMake
on the first configuration to determine \fBresource\fP compiler, after which the
value for \fBRC\fP is stored in the cache as
\fBCMAKE_RC_COMPILER\fP\&. For any configuration run
(including the first), the environment variable will be ignored if the
\fBCMAKE_RC_COMPILER\fP variable is defined.
.SS RCFLAGS
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Default compilation flags to be used when compiling \fBresource\fP files. Will
only be used by CMake on the first configuration to determine \fBresource\fP
default compilation flags, after which the value for \fBRCFLAGS\fP is stored in
the cache as \fBCMAKE_RC_FLAGS\fP\&. For any
configuration run (including the first), the environment variable will be ignored
if the \fBCMAKE_RC_FLAGS\fP variable is defined.
.SS SWIFTC
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Preferred executable for compiling \fBSwift\fP language files. Will only be used by
CMake on the first configuration to determine \fBSwift\fP compiler, after which the
value for \fBSWIFTC\fP is stored in the cache as
\fBCMAKE_Swift_COMPILER\fP\&. For any configuration run
(including the first), the environment variable will be ignored if the
\fBCMAKE_Swift_COMPILER\fP variable is defined.
.SH ENVIRONMENT VARIABLES FOR CTEST
.SS CTEST_INTERACTIVE_DEBUG_MODE
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Environment variable that will exist and be set to \fB1\fP when a test executed
by \fBctest(1)\fP is run in interactive mode.
.SS CTEST_OUTPUT_ON_FAILURE
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Boolean environment variable that controls if the output should be logged for
failed tests. Set the value to \fB1\fP, \fBTrue\fP, or \fBON\fP to enable output on failure.
See \fBctest(1)\fP for more information on controlling output of failed
tests.
.SS CTEST_PARALLEL_LEVEL
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Specify the number of tests for CTest to run in parallel. See \fBctest(1)\fP
for more information on parallel test execution.
.SS CTEST_PROGRESS_OUTPUT
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Boolean environment variable that affects how \fBctest\fP
command output reports overall progress. When set to \fB1\fP, \fBTRUE\fP, \fBON\fP or anything
else that evaluates to boolean true, progress is reported by repeatedly
updating the same line. This greatly reduces the overall verbosity, but is
only supported when output is sent directly to a terminal. If the environment
variable is not set or has a value that evaluates to false, output is reported
normally with each test having its own start and end lines logged to the
output.
.sp
The \fB\-\-progress\fP option to \fBctest\fP overrides this
environment variable if both are given.
.SS CTEST_USE_LAUNCHERS_DEFAULT
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Initializes the \fBCTEST_USE_LAUNCHERS\fP variable if not already defined.
.SS DASHBOARD_TEST_FROM_CTEST
.sp
This is a CMake Environment Variable\&. Its initial value is taken from
the calling process environment.
.sp
Environment variable that will exist when a test executed by \fBctest(1)\fP
is run in non\-interactive mode. The value will be equal to
\fBCMAKE_VERSION\fP\&.
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

1300
cmake/cmake-file-api.7
View File

File diff suppressed because it is too large Load Diff

830
cmake/cmake-generator-expressions.7
View File

@ -1,830 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CMAKE-GENERATOR-EXPRESSIONS" "7" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
cmake-generator-expressions \- CMake Generator Expressions
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH INTRODUCTION
.sp
Generator expressions are evaluated during build system generation to produce
information specific to each build configuration.
.sp
Generator expressions are allowed in the context of many target properties,
such as \fBLINK_LIBRARIES\fP, \fBINCLUDE_DIRECTORIES\fP,
\fBCOMPILE_DEFINITIONS\fP and others. They may also be used when using
commands to populate those properties, such as \fBtarget_link_libraries()\fP,
\fBtarget_include_directories()\fP, \fBtarget_compile_definitions()\fP
and others.
.sp
They enable conditional linking, conditional definitions used when compiling,
conditional include directories, and more. The conditions may be based on
the build configuration, target properties, platform information or any other
queryable information.
.sp
Generator expressions have the form \fB$<...>\fP\&. To avoid confusion, this page
deviates from most of the CMake documentation in that it omits angular brackets
\fB<...>\fP around placeholders like \fBcondition\fP, \fBstring\fP, \fBtarget\fP,
among others.
.sp
Generator expressions can be nested, as shown in most of the examples below.
.SH BOOLEAN GENERATOR EXPRESSIONS
.sp
Boolean expressions evaluate to either \fB0\fP or \fB1\fP\&.
They are typically used to construct the condition in a \fI\%conditional
generator expression\fP\&.
.sp
Available boolean expressions are:
.SS Logical Operators
.INDENT 0.0
.TP
.B \fB$<BOOL:string>\fP
Converts \fBstring\fP to \fB0\fP or \fB1\fP\&. Evaluates to \fB0\fP if any of the
following is true:
.INDENT 7.0
.IP \(bu 2
\fBstring\fP is empty,
.IP \(bu 2
\fBstring\fP is a case\-insensitive equal of
\fB0\fP, \fBFALSE\fP, \fBOFF\fP, \fBN\fP, \fBNO\fP, \fBIGNORE\fP, or \fBNOTFOUND\fP, or
.IP \(bu 2
\fBstring\fP ends in the suffix \fB\-NOTFOUND\fP (case\-sensitive).
.UNINDENT
.sp
Otherwise evaluates to \fB1\fP\&.
.TP
.B \fB$<AND:conditions>\fP
where \fBconditions\fP is a comma\-separated list of boolean expressions.
Evaluates to \fB1\fP if all conditions are \fB1\fP\&.
Otherwise evaluates to \fB0\fP\&.
.TP
.B \fB$<OR:conditions>\fP
where \fBconditions\fP is a comma\-separated list of boolean expressions.
Evaluates to \fB1\fP if at least one of the conditions is \fB1\fP\&.
Otherwise evaluates to \fB0\fP\&.
.TP
.B \fB$<NOT:condition>\fP
\fB0\fP if \fBcondition\fP is \fB1\fP, else \fB1\fP\&.
.UNINDENT
.SS String Comparisons
.INDENT 0.0
.TP
.B \fB$<STREQUAL:string1,string2>\fP
\fB1\fP if \fBstring1\fP and \fBstring2\fP are equal, else \fB0\fP\&.
The comparison is case\-sensitive. For a case\-insensitive comparison,
combine with a \fI\%string transforming generator expression\fP,
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
$<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ...
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B \fB$<EQUAL:value1,value2>\fP
\fB1\fP if \fBvalue1\fP and \fBvalue2\fP are numerically equal, else \fB0\fP\&.
.TP
.B \fB$<IN_LIST:string,list>\fP
\fB1\fP if \fBstring\fP is member of the semicolon\-separated \fBlist\fP, else \fB0\fP\&.
Uses case\-sensitive comparisons.
.TP
.B \fB$<VERSION_LESS:v1,v2>\fP
\fB1\fP if \fBv1\fP is a version less than \fBv2\fP, else \fB0\fP\&.
.TP
.B \fB$<VERSION_GREATER:v1,v2>\fP
\fB1\fP if \fBv1\fP is a version greater than \fBv2\fP, else \fB0\fP\&.
.TP
.B \fB$<VERSION_EQUAL:v1,v2>\fP
\fB1\fP if \fBv1\fP is the same version as \fBv2\fP, else \fB0\fP\&.
.TP
.B \fB$<VERSION_LESS_EQUAL:v1,v2>\fP
\fB1\fP if \fBv1\fP is a version less than or equal to \fBv2\fP, else \fB0\fP\&.
.TP
.B \fB$<VERSION_GREATER_EQUAL:v1,v2>\fP
\fB1\fP if \fBv1\fP is a version greater than or equal to \fBv2\fP, else \fB0\fP\&.
.UNINDENT
.SS Variable Queries
.INDENT 0.0
.TP
.B \fB$<TARGET_EXISTS:target>\fP
\fB1\fP if \fBtarget\fP exists, else \fB0\fP\&.
.TP
.B \fB$<CONFIG:cfg>\fP
\fB1\fP if config is \fBcfg\fP, else \fB0\fP\&. This is a case\-insensitive comparison.
The mapping in \fBMAP_IMPORTED_CONFIG_<CONFIG>\fP is also considered by
this expression when it is evaluated on a property on an \fBIMPORTED\fP
target.
.TP
.B \fB$<PLATFORM_ID:platform_ids>\fP
where \fBplatform_ids\fP is a comma\-separated list.
\fB1\fP if the CMake\(aqs platform id matches any one of the entries in
\fBplatform_ids\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_SYSTEM_NAME\fP variable.
.TP
.B \fB$<C_COMPILER_ID:compiler_ids>\fP
where \fBcompiler_ids\fP is a comma\-separated list.
\fB1\fP if the CMake\(aqs compiler id of the C compiler matches any one
of the entries in \fBcompiler_ids\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<CXX_COMPILER_ID:compiler_ids>\fP
where \fBcompiler_ids\fP is a comma\-separated list.
\fB1\fP if the CMake\(aqs compiler id of the CXX compiler matches any one
of the entries in \fBcompiler_ids\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<CUDA_COMPILER_ID:compiler_ids>\fP
where \fBcompiler_ids\fP is a comma\-separated list.
\fB1\fP if the CMake\(aqs compiler id of the CUDA compiler matches any one
of the entries in \fBcompiler_ids\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<OBJC_COMPILER_ID:compiler_ids>\fP
where \fBcompiler_ids\fP is a comma\-separated list.
\fB1\fP if the CMake\(aqs compiler id of the Objective\-C compiler matches any one
of the entries in \fBcompiler_ids\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<OBJCXX_COMPILER_ID:compiler_ids>\fP
where \fBcompiler_ids\fP is a comma\-separated list.
\fB1\fP if the CMake\(aqs compiler id of the Objective\-C++ compiler matches any one
of the entries in \fBcompiler_ids\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<Fortran_COMPILER_ID:compiler_ids>\fP
where \fBcompiler_ids\fP is a comma\-separated list.
\fB1\fP if the CMake\(aqs compiler id of the Fortran compiler matches any one
of the entries in \fBcompiler_ids\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<C_COMPILER_VERSION:version>\fP
\fB1\fP if the version of the C compiler matches \fBversion\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<CXX_COMPILER_VERSION:version>\fP
\fB1\fP if the version of the CXX compiler matches \fBversion\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<CUDA_COMPILER_VERSION:version>\fP
\fB1\fP if the version of the CXX compiler matches \fBversion\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<OBJC_COMPILER_VERSION:version>\fP
\fB1\fP if the version of the OBJC compiler matches \fBversion\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<OBJCXX_COMPILER_VERSION:version>\fP
\fB1\fP if the version of the OBJCXX compiler matches \fBversion\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<Fortran_COMPILER_VERSION:version>\fP
\fB1\fP if the version of the Fortran compiler matches \fBversion\fP, otherwise \fB0\fP\&.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<TARGET_POLICY:policy>\fP
\fB1\fP if the \fBpolicy\fP was NEW when the \(aqhead\(aq target was created,
else \fB0\fP\&. If the \fBpolicy\fP was not set, the warning message for the policy
will be emitted. This generator expression only works for a subset of
policies.
.TP
.B \fB$<COMPILE_FEATURES:features>\fP
where \fBfeatures\fP is a comma\-spearated list.
Evaluates to \fB1\fP if all of the \fBfeatures\fP are available for the \(aqhead\(aq
target, and \fB0\fP otherwise. If this expression is used while evaluating
the link implementation of a target and if any dependency transitively
increases the required \fBC_STANDARD\fP or \fBCXX_STANDARD\fP
for the \(aqhead\(aq target, an error is reported. See the
\fBcmake\-compile\-features(7)\fP manual for information on
compile features and a list of supported compilers.
.UNINDENT
.INDENT 0.0
.TP
.B \fB$<COMPILE_LANG_AND_ID:language,compiler_ids>\fP
\fB1\fP when the language used for compilation unit matches \fBlanguage\fP and
the CMake\(aqs compiler id of the language compiler matches any one of the
entries in \fBcompiler_ids\fP, otherwise \fB0\fP\&. This expression is a short form
for the combination of \fB$<COMPILE_LANGUAGE:language>\fP and
\fB$<LANG_COMPILER_ID:compiler_ids>\fP\&. This expression may be used to specify
compile options, compile definitions, and include directories for source files of a
particular language and compiler combination in a target. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
target_compile_definitions(myapp
PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
$<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
$<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This specifies the use of different compile definitions based on both
the compiler id and compilation language. This example will have a
\fBCOMPILING_CXX_WITH_CLANG\fP compile definition when Clang is the CXX
compiler, and \fBCOMPILING_CXX_WITH_INTEL\fP when Intel is the CXX compiler.
Likewise when the C compiler is Clang it will only see the \fBCOMPILING_C_WITH_CLANG\fP
definition.
.sp
Without the \fBCOMPILE_LANG_AND_ID\fP generator expression the same logic
would be expressed as:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
target_compile_definitions(myapp
PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
$<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
$<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
)
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B \fB$<COMPILE_LANGUAGE:languages>\fP
\fB1\fP when the language used for compilation unit matches any of the entries
in \fBlanguages\fP, otherwise \fB0\fP\&. This expression may be used to specify
compile options, compile definitions, and include directories for source files of a
particular language in a target. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
target_compile_options(myapp
PRIVATE $<$<COMPILE_LANGUAGE:CXX>:\-fno\-exceptions>
)
target_compile_definitions(myapp
PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
$<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
)
target_include_directories(myapp
PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers>
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This specifies the use of the \fB\-fno\-exceptions\fP compile option,
\fBCOMPILING_CXX\fP compile definition, and \fBcxx_headers\fP include
directory for C++ only (compiler id checks elided). It also specifies
a \fBCOMPILING_CUDA\fP compile definition for CUDA.
.sp
Note that with Visual Studio Generators and \fBXcode\fP there
is no way to represent target\-wide compile definitions or include directories
separately for \fBC\fP and \fBCXX\fP languages.
Also, with Visual Studio Generators there is no way to represent
target\-wide flags separately for \fBC\fP and \fBCXX\fP languages. Under these
generators, expressions for both C and C++ sources will be evaluated
using \fBCXX\fP if there are any C++ sources and otherwise using \fBC\fP\&.
A workaround is to create separate libraries for each source file language
instead:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
add_library(myapp_c foo.c)
add_library(myapp_cxx bar.cpp)
target_compile_options(myapp_cxx PUBLIC \-fno\-exceptions)
add_executable(myapp main.cpp)
target_link_libraries(myapp myapp_c myapp_cxx)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SH STRING-VALUED GENERATOR EXPRESSIONS
.sp
These expressions expand to some string.
For example,
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include_directories(/usr/include/$<CXX_COMPILER_ID>/)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
expands to \fB/usr/include/GNU/\fP or \fB/usr/include/Clang/\fP etc, depending on
the compiler identifier.
.sp
String\-valued expressions may also be combined with other expressions.
Here an example for a string\-valued expression within a boolean expressions
within a conditional expression:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
expands to \fBOLD_COMPILER\fP if the
\fBCMAKE_CXX_COMPILER_VERSION\fP is less
than 4.2.0.
.sp
And here two nested string\-valued expressions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, \-I>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
generates a string of the entries in the \fBINCLUDE_DIRECTORIES\fP target
property with each entry preceded by \fB\-I\fP\&.
.sp
Expanding on the previous example, if one first wants to check if the
\fBINCLUDE_DIRECTORIES\fP property is non\-empty, then it is advisable to
introduce a helper variable to keep the code readable:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable
$<$<BOOL:${prop}>:\-I$<JOIN:${prop}, \-I>>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following string\-valued generator expressions are available:
.SS Escaped Characters
.sp
String literals to escape the special meaning a character would otherwise have:
.INDENT 0.0
.TP
.B \fB$<ANGLE\-R>\fP
A literal \fB>\fP\&. Used for example to compare strings that contain a \fB>\fP\&.
.TP
.B \fB$<COMMA>\fP
A literal \fB,\fP\&. Used for example to compare strings which contain a \fB,\fP\&.
.TP
.B \fB$<SEMICOLON>\fP
A literal \fB;\fP\&. Used to prevent list expansion on an argument with \fB;\fP\&.
.UNINDENT
.SS Conditional Expressions
.sp
Conditional generator expressions depend on a boolean condition
that must be \fB0\fP or \fB1\fP\&.
.INDENT 0.0
.TP
.B \fB$<condition:true_string>\fP
Evaluates to \fBtrue_string\fP if \fBcondition\fP is \fB1\fP\&.
Otherwise evaluates to the empty string.
.TP
.B \fB$<IF:condition,true_string,false_string>\fP
Evaluates to \fBtrue_string\fP if \fBcondition\fP is \fB1\fP\&.
Otherwise evaluates to \fBfalse_string\fP\&.
.UNINDENT
.sp
Typically, the \fBcondition\fP is a \fI\%boolean generator expression\fP\&. For instance,
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$<$<CONFIG:Debug>:DEBUG_MODE>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
expands to \fBDEBUG_MODE\fP when the \fBDebug\fP configuration is used, and
otherwise expands to the empty string.
.SS String Transformations
.INDENT 0.0
.TP
.B \fB$<JOIN:list,string>\fP
Joins the list with the content of \fBstring\fP\&.
.TP
.B \fB$<REMOVE_DUPLICATES:list>\fP
Removes duplicated items in the given \fBlist\fP\&.
.TP
.B \fB$<FILTER:list,INCLUDE|EXCLUDE,regex>\fP
Includes or removes items from \fBlist\fP that match the regular expression \fBregex\fP\&.
.TP
.B \fB$<LOWER_CASE:string>\fP
Content of \fBstring\fP converted to lower case.
.TP
.B \fB$<UPPER_CASE:string>\fP
Content of \fBstring\fP converted to upper case.
.TP
.B \fB$<GENEX_EVAL:expr>\fP
Content of \fBexpr\fP evaluated as a generator expression in the current
context. This enables consumption of generator expressions whose
evaluation results itself in generator expressions.
.TP
.B \fB$<TARGET_GENEX_EVAL:tgt,expr>\fP
Content of \fBexpr\fP evaluated as a generator expression in the context of
\fBtgt\fP target. This enables consumption of custom target properties that
themselves contain generator expressions.
.sp
Having the capability to evaluate generator expressions is very useful when
you want to manage custom properties supporting generator expressions.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
add_library(foo ...)
set_property(TARGET foo PROPERTY
CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
)
add_custom_target(printFooKeys
COMMAND ${CMAKE_COMMAND} \-E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This naive implementation of the \fBprintFooKeys\fP custom command is wrong
because \fBCUSTOM_KEYS\fP target property is not evaluated and the content
is passed as is (i.e. \fB$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>\fP).
.sp
To have the expected result (i.e. \fBFOO_EXTRA_THINGS\fP if config is
\fBDebug\fP), it is required to evaluate the output of
\fB$<TARGET_PROPERTY:foo,CUSTOM_KEYS>\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
add_custom_target(printFooKeys
COMMAND ${CMAKE_COMMAND} \-E
echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Variable Queries
.INDENT 0.0
.TP
.B \fB$<CONFIG>\fP
Configuration name.
.TP
.B \fB$<CONFIGURATION>\fP
Configuration name. Deprecated since CMake 3.0. Use \fBCONFIG\fP instead.
.TP
.B \fB$<PLATFORM_ID>\fP
The current system\(aqs CMake platform id.
See also the \fBCMAKE_SYSTEM_NAME\fP variable.
.TP
.B \fB$<C_COMPILER_ID>\fP
The CMake\(aqs compiler id of the C compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<CXX_COMPILER_ID>\fP
The CMake\(aqs compiler id of the CXX compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<CUDA_COMPILER_ID>\fP
The CMake\(aqs compiler id of the CUDA compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<OBJC_COMPILER_ID>\fP
The CMake\(aqs compiler id of the OBJC compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<OBJCXX_COMPILER_ID>\fP
The CMake\(aqs compiler id of the OBJCXX compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<Fortran_COMPILER_ID>\fP
The CMake\(aqs compiler id of the Fortran compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.
.TP
.B \fB$<C_COMPILER_VERSION>\fP
The version of the C compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<CXX_COMPILER_VERSION>\fP
The version of the CXX compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<CUDA_COMPILER_VERSION>\fP
The version of the CUDA compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<OBJC_COMPILER_VERSION>\fP
The version of the OBJC compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<OBJCXX_COMPILER_VERSION>\fP
The version of the OBJCXX compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<Fortran_COMPILER_VERSION>\fP
The version of the Fortran compiler used.
See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.
.TP
.B \fB$<COMPILE_LANGUAGE>\fP
The compile language of source files when evaluating compile options.
See \fI\%the related boolean expression\fP
\fB$<COMPILE_LANGUAGE:language>\fP
for notes about the portability of this generator expression.
.UNINDENT
.SS Target\-Dependent Queries
.INDENT 0.0
.TP
.B \fB$<TARGET_NAME_IF_EXISTS:tgt>\fP
Expands to the \fBtgt\fP if the given target exists, an empty string
otherwise.
.TP
.B \fB$<TARGET_FILE:tgt>\fP
Full path to main file (.exe, .so.1.2, .a) where \fBtgt\fP is the name of a
target.
.TP
.B \fB$<TARGET_FILE_BASE_NAME:tgt>\fP
Base name of main file where \fBtgt\fP is the name of a target.
.sp
The base name corresponds to the target file name (see
\fB$<TARGET_FILE_NAME:tgt>\fP) without prefix and suffix. For example, if
target file name is \fBlibbase.so\fP, the base name is \fBbase\fP\&.
.sp
See also the \fBOUTPUT_NAME\fP, \fBARCHIVE_OUTPUT_NAME\fP,
\fBLIBRARY_OUTPUT_NAME\fP and \fBRUNTIME_OUTPUT_NAME\fP
target properties and their configuration specific variants
\fBOUTPUT_NAME_<CONFIG>\fP, \fBARCHIVE_OUTPUT_NAME_<CONFIG>\fP,
\fBLIBRARY_OUTPUT_NAME_<CONFIG>\fP and
\fBRUNTIME_OUTPUT_NAME_<CONFIG>\fP\&.
.sp
The \fB<CONFIG>_POSTFIX\fP and \fBDEBUG_POSTFIX\fP target
properties can also be considered.
.sp
Note that \fBtgt\fP is not added as a dependency of the target this
expression is evaluated on.
.TP
.B \fB$<TARGET_FILE_PREFIX:tgt>\fP
Prefix of main file where \fBtgt\fP is the name of a target.
.sp
See also the \fBPREFIX\fP target property.
.sp
Note that \fBtgt\fP is not added as a dependency of the target this
expression is evaluated on.
.TP
.B \fB$<TARGET_FILE_SUFFIX:tgt>\fP
Suffix of main file where \fBtgt\fP is the name of a target.
.sp
The suffix corresponds to the file extension (such as ".so" or ".exe").
.sp
See also the \fBSUFFIX\fP target property.
.sp
Note that \fBtgt\fP is not added as a dependency of the target this
expression is evaluated on.
.TP
.B \fB$<TARGET_FILE_NAME:tgt>\fP
Name of main file (.exe, .so.1.2, .a).
.TP
.B \fB$<TARGET_FILE_DIR:tgt>\fP
Directory of main file (.exe, .so.1.2, .a).
.TP
.B \fB$<TARGET_LINKER_FILE:tgt>\fP
File used to link (.a, .lib, .so) where \fBtgt\fP is the name of a target.
.TP
.B \fB$<TARGET_LINKER_FILE_BASE_NAME:tgt>\fP
Base name of file used to link where \fBtgt\fP is the name of a target.
.sp
The base name corresponds to the target linker file name (see
\fB$<TARGET_LINKER_FILE_NAME:tgt>\fP) without prefix and suffix. For example,
if target file name is \fBlibbase.a\fP, the base name is \fBbase\fP\&.
.sp
See also the \fBOUTPUT_NAME\fP, \fBARCHIVE_OUTPUT_NAME\fP,
and \fBLIBRARY_OUTPUT_NAME\fP target properties and their configuration
specific variants \fBOUTPUT_NAME_<CONFIG>\fP,
\fBARCHIVE_OUTPUT_NAME_<CONFIG>\fP and
\fBLIBRARY_OUTPUT_NAME_<CONFIG>\fP\&.
.sp
The \fB<CONFIG>_POSTFIX\fP and \fBDEBUG_POSTFIX\fP target
properties can also be considered.
.sp
Note that \fBtgt\fP is not added as a dependency of the target this
expression is evaluated on.
.TP
.B \fB$<TARGET_LINKER_FILE_PREFIX:tgt>\fP
Prefix of file used to link where \fBtgt\fP is the name of a target.
.sp
See also the \fBPREFIX\fP and \fBIMPORT_PREFIX\fP target
properties.
.sp
Note that \fBtgt\fP is not added as a dependency of the target this
expression is evaluated on.
.TP
.B \fB$<TARGET_LINKER_FILE_SUFFIX:tgt>\fP
Suffix of file used to link where \fBtgt\fP is the name of a target.
.sp
The suffix corresponds to the file extension (such as ".so" or ".lib").
.sp
See also the \fBSUFFIX\fP and \fBIMPORT_SUFFIX\fP target
properties.
.sp
Note that \fBtgt\fP is not added as a dependency of the target this
expression is evaluated on.
.TP
.B \fB$<TARGET_LINKER_FILE_NAME:tgt>\fP
Name of file used to link (.a, .lib, .so).
.TP
.B \fB$<TARGET_LINKER_FILE_DIR:tgt>\fP
Directory of file used to link (.a, .lib, .so).
.TP
.B \fB$<TARGET_SONAME_FILE:tgt>\fP
File with soname (.so.3) where \fBtgt\fP is the name of a target.
.TP
.B \fB$<TARGET_SONAME_FILE_NAME:tgt>\fP
Name of file with soname (.so.3).
.TP
.B \fB$<TARGET_SONAME_FILE_DIR:tgt>\fP
Directory of with soname (.so.3).
.TP
.B \fB$<TARGET_PDB_FILE:tgt>\fP
Full path to the linker generated program database file (.pdb)
where \fBtgt\fP is the name of a target.
.sp
See also the \fBPDB_NAME\fP and \fBPDB_OUTPUT_DIRECTORY\fP
target properties and their configuration specific variants
\fBPDB_NAME_<CONFIG>\fP and \fBPDB_OUTPUT_DIRECTORY_<CONFIG>\fP\&.
.TP
.B \fB$<TARGET_PDB_FILE_BASE_NAME:tgt>\fP
Base name of the linker generated program database file (.pdb)
where \fBtgt\fP is the name of a target.
.sp
The base name corresponds to the target PDB file name (see
\fB$<TARGET_PDB_FILE_NAME:tgt>\fP) without prefix and suffix. For example,
if target file name is \fBbase.pdb\fP, the base name is \fBbase\fP\&.
.sp
See also the \fBPDB_NAME\fP target property and its configuration
specific variant \fBPDB_NAME_<CONFIG>\fP\&.
.sp
The \fB<CONFIG>_POSTFIX\fP and \fBDEBUG_POSTFIX\fP target
properties can also be considered.
.sp
Note that \fBtgt\fP is not added as a dependency of the target this
expression is evaluated on.
.TP
.B \fB$<TARGET_PDB_FILE_NAME:tgt>\fP
Name of the linker generated program database file (.pdb).
.TP
.B \fB$<TARGET_PDB_FILE_DIR:tgt>\fP
Directory of the linker generated program database file (.pdb).
.TP
.B \fB$<TARGET_BUNDLE_DIR:tgt>\fP
Full path to the bundle directory (\fBmy.app\fP, \fBmy.framework\fP, or
\fBmy.bundle\fP) where \fBtgt\fP is the name of a target.
.TP
.B \fB$<TARGET_BUNDLE_CONTENT_DIR:tgt>\fP
Full path to the bundle content directory where \fBtgt\fP is the name of a
target. For the macOS SDK it leads to \fBmy.app/Contents\fP, \fBmy.framework\fP,
or \fBmy.bundle/Contents\fP\&. For all other SDKs (e.g. iOS) it leads to
\fBmy.app\fP, \fBmy.framework\fP, or \fBmy.bundle\fP due to the flat bundle
structure.
.TP
.B \fB$<TARGET_PROPERTY:tgt,prop>\fP
Value of the property \fBprop\fP on the target \fBtgt\fP\&.
.sp
Note that \fBtgt\fP is not added as a dependency of the target this
expression is evaluated on.
.TP
.B \fB$<TARGET_PROPERTY:prop>\fP
Value of the property \fBprop\fP on the target on which the generator
expression is evaluated. Note that for generator expressions in
Target Usage Requirements this is the value of the property
on the consuming target rather than the target specifying the
requirement.
.TP
.B \fB$<INSTALL_PREFIX>\fP
Content of the install prefix when the target is exported via
\fBinstall(EXPORT)\fP, or when evaluated in
\fBINSTALL_NAME_DIR\fP, and empty otherwise.
.UNINDENT
.SS Output\-Related Expressions
.INDENT 0.0
.TP
.B \fB$<TARGET_NAME:...>\fP
Marks \fB\&...\fP as being the name of a target. This is required if exporting
targets to multiple dependent export sets. The \fB\&...\fP must be a literal
name of a target\- it may not contain generator expressions.
.TP
.B \fB$<LINK_ONLY:...>\fP
Content of \fB\&...\fP except when evaluated in a link interface while
propagating Target Usage Requirements, in which case it is the
empty string.
Intended for use only in an \fBINTERFACE_LINK_LIBRARIES\fP target
property, perhaps via the \fBtarget_link_libraries()\fP command,
to specify private link dependencies without other usage requirements.
.TP
.B \fB$<INSTALL_INTERFACE:...>\fP
Content of \fB\&...\fP when the property is exported using \fBinstall(EXPORT)\fP,
and empty otherwise.
.TP
.B \fB$<BUILD_INTERFACE:...>\fP
Content of \fB\&...\fP when the property is exported using \fBexport()\fP, or
when the target is used by another target in the same buildsystem. Expands to
the empty string otherwise.
.TP
.B \fB$<MAKE_C_IDENTIFIER:...>\fP
Content of \fB\&...\fP converted to a C identifier. The conversion follows the
same behavior as \fBstring(MAKE_C_IDENTIFIER)\fP\&.
.TP
.B \fB$<TARGET_OBJECTS:objLib>\fP
List of objects resulting from build of \fBobjLib\fP\&.
.TP
.B \fB$<SHELL_PATH:...>\fP
Content of \fB\&...\fP converted to shell path style. For example, slashes are
converted to backslashes in Windows shells and drive letters are converted
to posix paths in MSYS shells. The \fB\&...\fP must be an absolute path.
The \fB\&...\fP may be a semicolon\-separated list
of paths, in which case each path is converted individually and a result
list is generated using the shell path separator (\fB:\fP on POSIX and
\fB;\fP on Windows). Be sure to enclose the argument containing this genex
in double quotes in CMake source code so that \fB;\fP does not split arguments.
.UNINDENT
.SH DEBUGGING
.sp
Since generator expressions are evaluated during generation of the buildsystem,
and not during processing of \fBCMakeLists.txt\fP files, it is not possible to
inspect their result with the \fBmessage()\fP command.
.sp
One possible way to generate debug messages is to add a custom target,
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} \-E echo "$<...>")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The shell command \fBmake genexdebug\fP (invoked after execution of \fBcmake\fP)
would then print the result of \fB$<...>\fP\&.
.sp
Another way is to write debug messages to a file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file(GENERATE OUTPUT filename CONTENT "$<...>")
.ft P
.fi
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

889
cmake/cmake-generators.7
View File

@ -1,889 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CMAKE-GENERATORS" "7" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
cmake-generators \- CMake Generators Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH INTRODUCTION
.sp
A \fICMake Generator\fP is responsible for writing the input files for
a native build system. Exactly one of the \fI\%CMake Generators\fP must be
selected for a build tree to determine what native build system is to
be used. Optionally one of the \fI\%Extra Generators\fP may be selected
as a variant of some of the \fI\%Command\-Line Build Tool Generators\fP to
produce project files for an auxiliary IDE.
.sp
CMake Generators are platform\-specific so each may be available only
on certain platforms. The \fBcmake(1)\fP command\-line tool \fB\-\-help\fP
output lists available generators on the current platform. Use its \fB\-G\fP
option to specify the generator for a new build tree.
The \fBcmake\-gui(1)\fP offers interactive selection of a generator
when creating a new build tree.
.SH CMAKE GENERATORS
.SS Command\-Line Build Tool Generators
.sp
These generators support command\-line build tools. In order to use them,
one must launch CMake from a command\-line prompt whose environment is
already configured for the chosen compiler and build tool.
.SS Makefile Generators
.SS Borland Makefiles
.sp
Generates Borland makefiles.
.SS MSYS Makefiles
.sp
Generates makefiles for use with MSYS (Minimal SYStem)
\fBmake\fP under the MSYS shell.
.sp
Use this generator in a MSYS shell prompt and using \fBmake\fP as the build
tool. The generated makefiles use \fB/bin/sh\fP as the shell to launch build
rules. They are not compatible with a Windows command prompt.
.sp
To build under a Windows command prompt, use the
\fBMinGW Makefiles\fP generator.
.SS MinGW Makefiles
.sp
Generates makefiles for use with \fBmingw32\-make\fP under a Windows command
prompt.
.sp
Use this generator under a Windows command prompt with
MinGW (Minimalist GNU for Windows) in the \fBPATH\fP
and using \fBmingw32\-make\fP as the build tool. The generated makefiles use
\fBcmd.exe\fP as the shell to launch build rules. They are not compatible with
MSYS or a unix shell.
.sp
To build under the MSYS shell, use the \fBMSYS Makefiles\fP generator.
.SS NMake Makefiles
.sp
Generates NMake makefiles.
.SS NMake Makefiles JOM
.sp
Generates JOM makefiles.
.SS Unix Makefiles
.sp
Generates standard UNIX makefiles.
.sp
A hierarchy of UNIX makefiles is generated into the build tree. Use
any standard UNIX\-style make program to build the project through
the \fBall\fP target and install the project through the \fBinstall\fP
(or \fBinstall/strip\fP) target.
.sp
For each subdirectory \fBsub/dir\fP of the project a UNIX makefile will
be created, containing the following targets:
.INDENT 0.0
.TP
.B \fBall\fP
Depends on all targets required by the subdirectory.
.TP
.B \fBinstall\fP
Runs the install step in the subdirectory, if any.
.TP
.B \fBinstall/strip\fP
Runs the install step in the subdirectory followed by a \fBCMAKE_STRIP\fP command,
if any.
.sp
The \fBCMAKE_STRIP\fP variable will contain the platform\(aqs \fBstrip\fP utility, which
removes symbols information from generated binaries.
.TP
.B \fBtest\fP
Runs the test step in the subdirectory, if any.
.TP
.B \fBpackage\fP
Runs the package step in the subdirectory, if any.
.UNINDENT
.SS Watcom WMake
.sp
Generates Watcom WMake makefiles.
.SS Ninja Generators
.SS Ninja
.sp
Generates \fBbuild.ninja\fP files.
.sp
A \fBbuild.ninja\fP file is generated into the build tree. Use the ninja
program to build the project through the \fBall\fP target and install the
project through the \fBinstall\fP (or \fBinstall/strip\fP) target.
.sp
For each subdirectory \fBsub/dir\fP of the project, additional targets
are generated:
.INDENT 0.0
.TP
.B \fBsub/dir/all\fP
Depends on all targets required by the subdirectory.
.TP
.B \fBsub/dir/install\fP
Runs the install step in the subdirectory, if any.
.TP
.B \fBsub/dir/install/strip\fP
Runs the install step in the subdirectory followed by a \fBCMAKE_STRIP\fP command,
if any.
.sp
The \fBCMAKE_STRIP\fP variable will contain the platform\(aqs \fBstrip\fP utility, which
removes symbols information from generated binaries.
.TP
.B \fBsub/dir/test\fP
Runs the test step in the subdirectory, if any.
.TP
.B \fBsub/dir/package\fP
Runs the package step in the subdirectory, if any.
.UNINDENT
.SS Fortran Support
.sp
The \fBNinja\fP generator conditionally supports Fortran when the \fBninja\fP
tool has the required features. As of this version of CMake the needed
features have not been integrated into upstream Ninja. Kitware maintains
a branch of Ninja with the required features on \fI\%github.com/Kitware/ninja\fP\&.
.SS See Also
.sp
The \fBNinja Multi\-Config\fP generator is similar to the \fBNinja\fP
generator, but generates multiple configurations at once.
.SS Ninja Multi\-Config
.sp
Generates multiple \fBbuild\-<Config>.ninja\fP files.
.sp
This generator is very much like the \fBNinja\fP generator, but with
some key differences. Only these differences will be discussed in this
document.
.sp
Unlike the \fBNinja\fP generator, \fBNinja Multi\-Config\fP generates
multiple configurations at once with \fBCMAKE_CONFIGURATION_TYPES\fP
instead of only one configuration with \fBCMAKE_BUILD_TYPE\fP\&. One
\fBbuild\-<Config>.ninja\fP file will be generated for each of these
configurations (with \fB<Config>\fP being the configuration name.) These files
are intended to be run with \fBninja \-f build\-<Config>.ninja\fP\&. A
\fBbuild.ninja\fP file is also generated, using the configuration from either
\fBCMAKE_DEFAULT_BUILD_TYPE\fP or the first item from
\fBCMAKE_CONFIGURATION_TYPES\fP\&.
.sp
\fBcmake \-\-build . \-\-config <Config>\fP will always use \fBbuild\-<Config>.ninja\fP
to build. If no \fB\-\-config\fP argument is specified, \fBcmake \-\-build .\fP will
default to \fBbuild\-Debug.ninja\fP, unless a \fBbuild.ninja\fP is generated (see
below), in which case that will be used instead.
.sp
Each \fBbuild\-<Config>.ninja\fP file contains \fB<target>\fP targets as well as
\fB<target>:<Config>\fP targets, where \fB<Config>\fP is the same as the
configuration specified in \fBbuild\-<Config>.ninja\fP Additionally, if
cross\-config mode is enabled, \fBbuild\-<Config>.ninja\fP may contain
\fB<target>:<OtherConfig>\fP targets, where \fB<OtherConfig>\fP is a cross\-config,
as well as \fB<target>:all\fP, which builds the target in all cross\-configs. See
below for how to enable cross\-config mode.
.sp
The \fBNinja Multi\-Config\fP generator recognizes the following variables:
.INDENT 0.0
.TP
.B \fBCMAKE_CONFIGURATION_TYPES\fP
Specifies the total set of configurations to build.
.TP
.B \fBCMAKE_CROSS_CONFIGS\fP
Specifies a semicolon\-separated list of
configurations available from all \fBbuild\-<Config>.ninja\fP files.
.TP
.B \fBCMAKE_DEFAULT_BUILD_TYPE\fP
Specifies the configuration to use by default in a \fBbuild.ninja\fP file.
.TP
.B \fBCMAKE_DEFAULT_CONFIGS\fP
Specifies a semicolon\-separated list of
configurations to build for a target in \fBbuild.ninja\fP
if no \fB:<Config>\fP suffix is specified.
.UNINDENT
.sp
Consider the following example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmake_minimum_required(VERSION 3.16)
project(MultiConfigNinja C)
add_executable(generator generator.c)
add_custom_command(OUTPUT generated.c COMMAND generator generated.c)
add_library(generated ${CMAKE_BINARY_DIR}/generated.c)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now assume you configure the project with \fBNinja Multi\-Config\fP and run one of
the following commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ninja \-f build\-Debug.ninja generated
# OR
cmake \-\-build . \-\-config Debug \-\-target generated
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This would build the \fBDebug\fP configuration of \fBgenerator\fP, which would be
used to generate \fBgenerated.c\fP, which would be used to build the \fBDebug\fP
configuration of \fBgenerated\fP\&.
.sp
But if \fBCMAKE_CROSS_CONFIGS\fP is set to \fBall\fP, and you run the
following instead:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ninja \-f build\-Release.ninja generated:Debug
# OR
cmake \-\-build . \-\-config Release \-\-target generated:Debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This would build the \fBRelease\fP configuration of \fBgenerator\fP, which would be
used to generate \fBgenerated.c\fP, which would be used to build the \fBDebug\fP
configuration of \fBgenerated\fP\&. This is useful for running a release\-optimized
version of a generator utility while still building the debug version of the
targets built with the generated code.
.SS IDE Build Tool Generators
.sp
These generators support Integrated Development Environment (IDE)
project files. Since the IDEs configure their own environment
one may launch CMake from any environment.
.SS Visual Studio Generators
.SS Visual Studio 6
.sp
Removed. This once generated Visual Studio 6 project files, but the
generator has been removed since CMake 3.6. It is still possible to
build with VS 6 tools using the \fBNMake Makefiles\fP generator.
.SS Visual Studio 7
.sp
Removed. This once generated Visual Studio .NET 2002 project files, but
the generator has been removed since CMake 3.6. It is still possible to
build with VS 7.0 tools using the \fBNMake Makefiles\fP generator.
.SS Visual Studio 7 .NET 2003
.sp
Removed. This once generated Visual Studio .NET 2003 project files, but
the generator has been removed since CMake 3.9. It is still possible to
build with VS 7.1 tools using the \fBNMake Makefiles\fP generator.
.SS Visual Studio 8 2005
.sp
Removed. This once generated Visual Studio 8 2005 project files, but
the generator has been removed since CMake 3.12. It is still possible to
build with VS 2005 tools using the \fBNMake Makefiles\fP generator.
.SS Visual Studio 9 2008
.sp
Generates Visual Studio 9 2008 project files.
.SS Platform Selection
.sp
The default target platform name (architecture) is \fBWin32\fP\&.
.sp
The \fBCMAKE_GENERATOR_PLATFORM\fP variable may be set, perhaps
via the \fBcmake(1)\fP \fB\-A\fP option, to specify a target platform
name (architecture). For example:
.INDENT 0.0
.IP \(bu 2
\fBcmake \-G "Visual Studio 9 2008" \-A Win32\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 9 2008" \-A x64\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 9 2008" \-A Itanium\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 9 2008" \-A <WinCE\-SDK>\fP
(Specify a target platform matching a Windows CE SDK name.)
.UNINDENT
.sp
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of the generator name.
This is supported only for:
.INDENT 0.0
.TP
.B \fBVisual Studio 9 2008 Win64\fP
Specify target platform \fBx64\fP\&.
.TP
.B \fBVisual Studio 9 2008 IA64\fP
Specify target platform \fBItanium\fP\&.
.TP
.B \fBVisual Studio 9 2008 <WinCE\-SDK>\fP
Specify target platform matching a Windows CE SDK name.
.UNINDENT
.SS Visual Studio 10 2010
.sp
Generates Visual Studio 10 (VS 2010) project files.
.sp
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name \fBVisual Studio 10\fP without the year component.
.SS Project Types
.sp
Only Visual C++ and C# projects may be generated. Other types of
projects (Database, Website, etc.) are not supported.
.SS Platform Selection
.sp
The default target platform name (architecture) is \fBWin32\fP\&.
.sp
The \fBCMAKE_GENERATOR_PLATFORM\fP variable may be set, perhaps
via the \fBcmake(1)\fP \fB\-A\fP option, to specify a target platform
name (architecture). For example:
.INDENT 0.0
.IP \(bu 2
\fBcmake \-G "Visual Studio 10 2010" \-A Win32\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 10 2010" \-A x64\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 10 2010" \-A Itanium\fP
.UNINDENT
.sp
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of the generator name.
This is supported only for:
.INDENT 0.0
.TP
.B \fBVisual Studio 10 2010 Win64\fP
Specify target platform \fBx64\fP\&.
.TP
.B \fBVisual Studio 10 2010 IA64\fP
Specify target platform \fBItanium\fP\&.
.UNINDENT
.SS Toolset Selection
.sp
The \fBv100\fP toolset that comes with Visual Studio 10 2010 is selected by
default. The \fBCMAKE_GENERATOR_TOOLSET\fP option may be set, perhaps
via the \fBcmake(1)\fP \fB\-T\fP option, to specify another toolset.
.SS Visual Studio 11 2012
.sp
Generates Visual Studio 11 (VS 2012) project files.
.sp
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name "Visual Studio 11" without the year component.
.SS Project Types
.sp
Only Visual C++ and C# projects may be generated. Other types of
projects (JavaScript, Database, Website, etc.) are not supported.
.SS Platform Selection
.sp
The default target platform name (architecture) is \fBWin32\fP\&.
.sp
The \fBCMAKE_GENERATOR_PLATFORM\fP variable may be set, perhaps
via the \fBcmake(1)\fP \fB\-A\fP option, to specify a target platform
name (architecture). For example:
.INDENT 0.0
.IP \(bu 2
\fBcmake \-G "Visual Studio 11 2012" \-A Win32\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 11 2012" \-A x64\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 11 2012" \-A ARM\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 11 2012" \-A <WinCE\-SDK>\fP
(Specify a target platform matching a Windows CE SDK name.)
.UNINDENT
.sp
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of the generator name.
This is supported only for:
.INDENT 0.0
.TP
.B \fBVisual Studio 11 2012 Win64\fP
Specify target platform \fBx64\fP\&.
.TP
.B \fBVisual Studio 11 2012 ARM\fP
Specify target platform \fBARM\fP\&.
.TP
.B \fBVisual Studio 11 2012 <WinCE\-SDK>\fP
Specify target platform matching a Windows CE SDK name.
.UNINDENT
.SS Toolset Selection
.sp
The \fBv110\fP toolset that comes with Visual Studio 11 2012 is selected by
default. The \fBCMAKE_GENERATOR_TOOLSET\fP option may be set, perhaps
via the \fBcmake(1)\fP \fB\-T\fP option, to specify another toolset.
.SS Visual Studio 12 2013
.sp
Generates Visual Studio 12 (VS 2013) project files.
.sp
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name "Visual Studio 12" without the year component.
.SS Project Types
.sp
Only Visual C++ and C# projects may be generated. Other types of
projects (JavaScript, Powershell, Python, etc.) are not supported.
.SS Platform Selection
.sp
The default target platform name (architecture) is \fBWin32\fP\&.
.sp
The \fBCMAKE_GENERATOR_PLATFORM\fP variable may be set, perhaps
via the \fBcmake(1)\fP \fB\-A\fP option, to specify a target platform
name (architecture). For example:
.INDENT 0.0
.IP \(bu 2
\fBcmake \-G "Visual Studio 12 2013" \-A Win32\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 12 2013" \-A x64\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 12 2013" \-A ARM\fP
.UNINDENT
.sp
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of the generator name.
This is supported only for:
.INDENT 0.0
.TP
.B \fBVisual Studio 12 2013 Win64\fP
Specify target platform \fBx64\fP\&.
.TP
.B \fBVisual Studio 12 2013 ARM\fP
Specify target platform \fBARM\fP\&.
.UNINDENT
.SS Toolset Selection
.sp
The \fBv120\fP toolset that comes with Visual Studio 12 2013 is selected by
default. The \fBCMAKE_GENERATOR_TOOLSET\fP option may be set, perhaps
via the \fBcmake(1)\fP \fB\-T\fP option, to specify another toolset.
.sp
For each toolset that comes with this version of Visual Studio, there are
variants that are themselves compiled for 32\-bit (\fBx86\fP) and
64\-bit (\fBx64\fP) hosts (independent of the architecture they target).
By default this generator uses the 32\-bit variant even on a 64\-bit host.
One may explicitly request use of either the 32\-bit or 64\-bit host tools
by adding either \fBhost=x86\fP or \fBhost=x64\fP to the toolset specification.
See the \fBCMAKE_GENERATOR_TOOLSET\fP variable for details.
.SS Visual Studio 14 2015
.sp
Generates Visual Studio 14 (VS 2015) project files.
.SS Project Types
.sp
Only Visual C++ and C# projects may be generated. Other types of
projects (JavaScript, Powershell, Python, etc.) are not supported.
.SS Platform Selection
.sp
The default target platform name (architecture) is \fBWin32\fP\&.
.sp
The \fBCMAKE_GENERATOR_PLATFORM\fP variable may be set, perhaps
via the \fBcmake(1)\fP \fB\-A\fP option, to specify a target platform
name (architecture). For example:
.INDENT 0.0
.IP \(bu 2
\fBcmake \-G "Visual Studio 14 2015" \-A Win32\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 14 2015" \-A x64\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 14 2015" \-A ARM\fP
.UNINDENT
.sp
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of the generator name.
This is supported only for:
.INDENT 0.0
.TP
.B \fBVisual Studio 14 2015 Win64\fP
Specify target platform \fBx64\fP\&.
.TP
.B \fBVisual Studio 14 2015 ARM\fP
Specify target platform \fBARM\fP\&.
.UNINDENT
.SS Toolset Selection
.sp
The \fBv140\fP toolset that comes with Visual Studio 14 2015 is selected by
default. The \fBCMAKE_GENERATOR_TOOLSET\fP option may be set, perhaps
via the \fBcmake(1)\fP \fB\-T\fP option, to specify another toolset.
.sp
For each toolset that comes with this version of Visual Studio, there are
variants that are themselves compiled for 32\-bit (\fBx86\fP) and
64\-bit (\fBx64\fP) hosts (independent of the architecture they target).
By default this generator uses the 32\-bit variant even on a 64\-bit host.
One may explicitly request use of either the 32\-bit or 64\-bit host tools
by adding either \fBhost=x86\fP or \fBhost=x64\fP to the toolset specification.
See the \fBCMAKE_GENERATOR_TOOLSET\fP variable for details.
.SS Visual Studio 15 2017
.sp
Generates Visual Studio 15 (VS 2017) project files.
.SS Project Types
.sp
Only Visual C++ and C# projects may be generated. Other types of
projects (JavaScript, Powershell, Python, etc.) are not supported.
.SS Instance Selection
.sp
VS 2017 supports multiple installations on the same machine.
The \fBCMAKE_GENERATOR_INSTANCE\fP variable may be set as a
cache entry containing the absolute path to a Visual Studio instance.
If the value is not specified explicitly by the user or a toolchain file,
CMake queries the Visual Studio Installer to locate VS instances, chooses
one, and sets the variable as a cache entry to hold the value persistently.
.sp
When CMake first chooses an instance, if the \fBVS150COMNTOOLS\fP environment
variable is set and points to the \fBCommon7/Tools\fP directory within
one of the instances, that instance will be used. Otherwise, if more
than one instance is installed we do not define which one is chosen
by default.
.SS Platform Selection
.sp
The default target platform name (architecture) is \fBWin32\fP\&.
.sp
The \fBCMAKE_GENERATOR_PLATFORM\fP variable may be set, perhaps
via the \fBcmake(1)\fP \fB\-A\fP option, to specify a target platform
name (architecture). For example:
.INDENT 0.0
.IP \(bu 2
\fBcmake \-G "Visual Studio 15 2017" \-A Win32\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 15 2017" \-A x64\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 15 2017" \-A ARM\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 15 2017" \-A ARM64\fP
.UNINDENT
.sp
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of the generator name.
This is supported only for:
.INDENT 0.0
.TP
.B \fBVisual Studio 15 2017 Win64\fP
Specify target platform \fBx64\fP\&.
.TP
.B \fBVisual Studio 15 2017 ARM\fP
Specify target platform \fBARM\fP\&.
.UNINDENT
.SS Toolset Selection
.sp
The \fBv141\fP toolset that comes with Visual Studio 15 2017 is selected by
default. The \fBCMAKE_GENERATOR_TOOLSET\fP option may be set, perhaps
via the \fBcmake(1)\fP \fB\-T\fP option, to specify another toolset.
.sp
For each toolset that comes with this version of Visual Studio, there are
variants that are themselves compiled for 32\-bit (\fBx86\fP) and
64\-bit (\fBx64\fP) hosts (independent of the architecture they target).
By default this generator uses the 32\-bit variant even on a 64\-bit host.
One may explicitly request use of either the 32\-bit or 64\-bit host tools
by adding either \fBhost=x86\fP or \fBhost=x64\fP to the toolset specification.
See the \fBCMAKE_GENERATOR_TOOLSET\fP variable for details.
.SS Visual Studio 16 2019
.sp
Generates Visual Studio 16 (VS 2019) project files.
.SS Project Types
.sp
Only Visual C++ and C# projects may be generated. Other types of
projects (JavaScript, Powershell, Python, etc.) are not supported.
.SS Instance Selection
.sp
VS 2019 supports multiple installations on the same machine.
The \fBCMAKE_GENERATOR_INSTANCE\fP variable may be set as a
cache entry containing the absolute path to a Visual Studio instance.
If the value is not specified explicitly by the user or a toolchain file,
CMake queries the Visual Studio Installer to locate VS instances, chooses
one, and sets the variable as a cache entry to hold the value persistently.
.sp
When CMake first chooses an instance, if the \fBVS160COMNTOOLS\fP environment
variable is set and points to the \fBCommon7/Tools\fP directory within
one of the instances, that instance will be used. Otherwise, if more
than one instance is installed we do not define which one is chosen
by default.
.SS Platform Selection
.sp
The default target platform name (architecture) is that of the host
and is provided in the \fBCMAKE_VS_PLATFORM_NAME_DEFAULT\fP variable.
.sp
The \fBCMAKE_GENERATOR_PLATFORM\fP variable may be set, perhaps
via the \fBcmake(1)\fP \fB\-A\fP option, to specify a target platform
name (architecture). For example:
.INDENT 0.0
.IP \(bu 2
\fBcmake \-G "Visual Studio 16 2019" \-A Win32\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 16 2019" \-A x64\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 16 2019" \-A ARM\fP
.IP \(bu 2
\fBcmake \-G "Visual Studio 16 2019" \-A ARM64\fP
.UNINDENT
.SS Toolset Selection
.sp
The \fBv142\fP toolset that comes with Visual Studio 16 2019 is selected by
default. The \fBCMAKE_GENERATOR_TOOLSET\fP option may be set, perhaps
via the \fBcmake(1)\fP \fB\-T\fP option, to specify another toolset.
.sp
For each toolset that comes with this version of Visual Studio, there are
variants that are themselves compiled for 32\-bit (\fBx86\fP) and
64\-bit (\fBx64\fP) hosts (independent of the architecture they target).
By default this generator uses the 64\-bit variant on x64 hosts and
the 32\-bit variant otherwise.
One may explicitly request use of either the 32\-bit or 64\-bit host tools
by adding either \fBhost=x86\fP or \fBhost=x64\fP to the toolset specification.
See the \fBCMAKE_GENERATOR_TOOLSET\fP variable for details.
.SS Other Generators
.SS Green Hills MULTI
.sp
Generates Green Hills MULTI project files (experimental, work\-in\-progress).
.sp
The buildsystem has predetermined build\-configuration settings that can be controlled
via the \fBCMAKE_BUILD_TYPE\fP variable.
.sp
Customizations that are used to pick toolset and target system:
.sp
The \fB\-A <arch>\fP can be supplied for setting the target architecture.
\fB<arch>\fP usually is one of \fBarm\fP, \fBppc\fP, \fB86\fP, etcetera.
If the target architecture is not specified then
the default architecture of \fBarm\fP will be used.
.sp
The \fB\-T <toolset>\fP option can be used to set the directory location of the toolset.
Both absolute and relative paths are valid. Relative paths use \fBGHS_TOOLSET_ROOT\fP
as the root. If the toolset is not specified then the latest toolset found in
\fBGHS_TOOLSET_ROOT\fP will be used.
.sp
Cache variables that are used for toolset and target system customization:
.INDENT 0.0
.IP \(bu 2
\fBGHS_TARGET_PLATFORM\fP
.nf
Defaults to \fBintegrity\fP\&.
Usual values are \fBintegrity\fP, \fBthreadx\fP, \fBuvelosity\fP, \fBvelosity\fP,
\fBvxworks\fP, \fBstandalone\fP\&.
.fi
.sp
.IP \(bu 2
\fBGHS_PRIMARY_TARGET\fP
.nf
Sets \fBprimaryTarget\fP entry in project file.
Defaults to \fB<arch>_<GHS_TARGET_PLATFORM>.tgt\fP\&.
.fi
.sp
.IP \(bu 2
\fBGHS_TOOLSET_ROOT\fP
.nf
Root path for \fBtoolset\fP searches.
Defaults to \fBC:/ghs\fP in Windows or \fB/usr/ghs\fP in Linux.
.fi
.sp
.IP \(bu 2
\fBGHS_OS_ROOT\fP
.nf
Root path for RTOS searches.
Defaults to \fBC:/ghs\fP in Windows or \fB/usr/ghs\fP in Linux.
.fi
.sp
.IP \(bu 2
\fBGHS_OS_DIR\fP and \fBGHS_OS_DIR_OPTION\fP
.nf
Sets \fB\-os_dir\fP entry in project file.
Defaults to latest platform OS installation at \fBGHS_OS_ROOT\fP\&. Set this value if
a specific RTOS is to be used.
\fBGHS_OS_DIR_OPTION\fP default value is \fB\-os_dir\fP\&.
.fi
.sp
.IP \(bu 2
\fBGHS_BSP_NAME\fP
.nf
Sets \fB\-bsp\fP entry in project file.
Defaults to \fBsim<arch>\fP for \fBintegrity\fP platforms.
.fi
.sp
.UNINDENT
.sp
Customizations are available through the following cache variables:
.INDENT 0.0
.IP \(bu 2
\fBGHS_CUSTOMIZATION\fP
.IP \(bu 2
\fBGHS_GPJ_MACROS\fP
.UNINDENT
.sp
The following properties are available:
.INDENT 0.0
.IP \(bu 2
\fBGHS_INTEGRITY_APP\fP
.IP \(bu 2
\fBGHS_NO_SOURCE_GROUP_FILE\fP
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This generator is deemed experimental as of CMake 3.17.1
and is still a work in progress. Future versions of CMake
may make breaking changes as the generator matures.
.UNINDENT
.UNINDENT
.SS Xcode
.sp
Generate Xcode project files.
.sp
This supports Xcode 5.0 and above.
.SS Toolset Selection
.sp
By default Xcode is allowed to select its own default toolchain.
The \fBCMAKE_GENERATOR_TOOLSET\fP option may be set, perhaps
via the \fBcmake(1)\fP \fB\-T\fP option, to specify another toolset.
.SH EXTRA GENERATORS
.sp
Some of the \fI\%CMake Generators\fP listed in the \fBcmake(1)\fP
command\-line tool \fB\-\-help\fP output may have variants that specify
an extra generator for an auxiliary IDE tool. Such generator
names have the form \fB<extra\-generator> \- <main\-generator>\fP\&.
The following extra generators are known to CMake.
.SS CodeBlocks
.sp
Generates CodeBlocks project files.
.sp
Project files for CodeBlocks will be created in the top directory and
in every subdirectory which features a \fBCMakeLists.txt\fP file containing
a \fBproject()\fP call. Additionally a hierarchy of makefiles is generated
into the build tree.
The \fBCMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES\fP variable may
be set to \fBON\fP to exclude any files which are located outside of
the project root directory.
The appropriate make program can build the
project through the default \fBall\fP target. An \fBinstall\fP target is
also provided.
.sp
This "extra" generator may be specified as:
.INDENT 0.0
.TP
.B \fBCodeBlocks \- MinGW Makefiles\fP
Generate with \fBMinGW Makefiles\fP\&.
.TP
.B \fBCodeBlocks \- NMake Makefiles\fP
Generate with \fBNMake Makefiles\fP\&.
.TP
.B \fBCodeBlocks \- NMake Makefiles JOM\fP
Generate with \fBNMake Makefiles JOM\fP\&.
.TP
.B \fBCodeBlocks \- Ninja\fP
Generate with \fBNinja\fP\&.
.TP
.B \fBCodeBlocks \- Unix Makefiles\fP
Generate with \fBUnix Makefiles\fP\&.
.UNINDENT
.SS CodeLite
.sp
Generates CodeLite project files.
.sp
Project files for CodeLite will be created in the top directory and
in every subdirectory which features a CMakeLists.txt file containing
a \fBproject()\fP call.
The \fBCMAKE_CODELITE_USE_TARGETS\fP variable may be set to \fBON\fP
to change the default behavior from projects to targets as the basis
for project files.
The appropriate make program can build the
project through the default \fBall\fP target. An \fBinstall\fP target
is also provided.
.sp
This "extra" generator may be specified as:
.INDENT 0.0
.TP
.B \fBCodeLite \- MinGW Makefiles\fP
Generate with \fBMinGW Makefiles\fP\&.
.TP
.B \fBCodeLite \- NMake Makefiles\fP
Generate with \fBNMake Makefiles\fP\&.
.TP
.B \fBCodeLite \- Ninja\fP
Generate with \fBNinja\fP\&.
.TP
.B \fBCodeLite \- Unix Makefiles\fP
Generate with \fBUnix Makefiles\fP\&.
.UNINDENT
.SS Eclipse CDT4
.sp
Generates Eclipse CDT 4.0 project files.
.sp
Project files for Eclipse will be created in the top directory. In
out of source builds, a linked resource to the top level source
directory will be created. Additionally a hierarchy of makefiles is
generated into the build tree. The appropriate make program can build
the project through the default \fBall\fP target. An \fBinstall\fP target
is also provided.
.sp
This "extra" generator may be specified as:
.INDENT 0.0
.TP
.B \fBEclipse CDT4 \- MinGW Makefiles\fP
Generate with \fBMinGW Makefiles\fP\&.
.TP
.B \fBEclipse CDT4 \- NMake Makefiles\fP
Generate with \fBNMake Makefiles\fP\&.
.TP
.B \fBEclipse CDT4 \- Ninja\fP
Generate with \fBNinja\fP\&.
.TP
.B \fBEclipse CDT4 \- Unix Makefiles\fP
Generate with \fBUnix Makefiles\fP\&.
.UNINDENT
.SS Kate
.sp
Generates Kate project files.
.sp
A project file for Kate will be created in the top directory in the top level
build directory.
To use it in Kate, the Project plugin must be enabled.
The project file is loaded in Kate by opening the
\fBProjectName.kateproject\fP file in the editor.
If the Kate Build\-plugin is enabled, all targets generated by CMake are
available for building.
.sp
This "extra" generator may be specified as:
.INDENT 0.0
.TP
.B \fBKate \- MinGW Makefiles\fP
Generate with \fBMinGW Makefiles\fP\&.
.TP
.B \fBKate \- NMake Makefiles\fP
Generate with \fBNMake Makefiles\fP\&.
.TP
.B \fBKate \- Ninja\fP
Generate with \fBNinja\fP\&.
.TP
.B \fBKate \- Unix Makefiles\fP
Generate with \fBUnix Makefiles\fP\&.
.UNINDENT
.SS Sublime Text 2
.sp
Generates Sublime Text 2 project files.
.sp
Project files for Sublime Text 2 will be created in the top directory
and in every subdirectory which features a \fBCMakeLists.txt\fP file
containing a \fBproject()\fP call. Additionally \fBMakefiles\fP
(or \fBbuild.ninja\fP files) are generated into the build tree.
The appropriate make program can build the project through the default \fBall\fP
target. An \fBinstall\fP target is also provided.
.sp
This "extra" generator may be specified as:
.INDENT 0.0
.TP
.B \fBSublime Text 2 \- MinGW Makefiles\fP
Generate with \fBMinGW Makefiles\fP\&.
.TP
.B \fBSublime Text 2 \- NMake Makefiles\fP
Generate with \fBNMake Makefiles\fP\&.
.TP
.B \fBSublime Text 2 \- Ninja\fP
Generate with \fBNinja\fP\&.
.TP
.B \fBSublime Text 2 \- Unix Makefiles\fP
Generate with \fBUnix Makefiles\fP\&.
.UNINDENT
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

621
cmake/cmake-language.7
View File

@ -1,621 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CMAKE-LANGUAGE" "7" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
cmake-language \- CMake Language Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH ORGANIZATION
.sp
CMake input files are written in the "CMake Language" in source files
named \fBCMakeLists.txt\fP or ending in a \fB\&.cmake\fP file name extension.
.sp
CMake Language source files in a project are organized into:
.INDENT 0.0
.IP \(bu 2
\fI\%Directories\fP (\fBCMakeLists.txt\fP),
.IP \(bu 2
\fI\%Scripts\fP (\fB<script>.cmake\fP), and
.IP \(bu 2
\fI\%Modules\fP (\fB<module>.cmake\fP).
.UNINDENT
.SS Directories
.sp
When CMake processes a project source tree, the entry point is
a source file called \fBCMakeLists.txt\fP in the top\-level source
directory. This file may contain the entire build specification
or use the \fBadd_subdirectory()\fP command to add subdirectories
to the build. Each subdirectory added by the command must also
contain a \fBCMakeLists.txt\fP file as the entry point to that
directory. For each source directory whose \fBCMakeLists.txt\fP file
is processed CMake generates a corresponding directory in the build
tree to act as the default working and output directory.
.SS Scripts
.sp
An individual \fB<script>.cmake\fP source file may be processed
in \fIscript mode\fP by using the \fBcmake(1)\fP command\-line tool
with the \fB\-P\fP option. Script mode simply runs the commands in
the given CMake Language source file and does not generate a
build system. It does not allow CMake commands that define build
targets or actions.
.SS Modules
.sp
CMake Language code in either \fI\%Directories\fP or \fI\%Scripts\fP may
use the \fBinclude()\fP command to load a \fB<module>.cmake\fP
source file in the scope of the including context.
See the \fBcmake\-modules(7)\fP manual page for documentation
of modules included with the CMake distribution.
Project source trees may also provide their own modules and
specify their location(s) in the \fBCMAKE_MODULE_PATH\fP
variable.
.SH SYNTAX
.SS Encoding
.sp
A CMake Language source file may be written in 7\-bit ASCII text for
maximum portability across all supported platforms. Newlines may be
encoded as either \fB\en\fP or \fB\er\en\fP but will be converted to \fB\en\fP
as input files are read.
.sp
Note that the implementation is 8\-bit clean so source files may
be encoded as UTF\-8 on platforms with system APIs supporting this
encoding. In addition, CMake 3.2 and above support source files
encoded in UTF\-8 on Windows (using UTF\-16 to call system APIs).
Furthermore, CMake 3.0 and above allow a leading UTF\-8
\fI\%Byte\-Order Mark\fP in source files.
.SS Source Files
.sp
A CMake Language source file consists of zero or more
\fI\%Command Invocations\fP separated by newlines and optionally
spaces and \fI\%Comments\fP:
.sp
.nf
\fBfile \fP ::= \fI\%file_element\fP*
\fBfile_element\fP ::= \fI\%command_invocation\fP \fI\%line_ending\fP |
(\fI\%bracket_comment\fP|\fI\%space\fP)* \fI\%line_ending\fP
\fBline_ending \fP ::= \fI\%line_comment\fP? \fI\%newline\fP
\fBspace \fP ::= <match \(aq[ \et]+\(aq>
\fBnewline \fP ::= <match \(aq\en\(aq>
.fi
.sp
Note that any source file line not inside \fI\%Command Arguments\fP or
a \fI\%Bracket Comment\fP can end in a \fI\%Line Comment\fP\&.
.SS Command Invocations
.sp
A \fIcommand invocation\fP is a name followed by paren\-enclosed arguments
separated by whitespace:
.sp
.nf
\fBcommand_invocation \fP ::= \fI\%space\fP* \fI\%identifier\fP \fI\%space\fP* \(aq(\(aq \fI\%arguments\fP \(aq)\(aq
\fBidentifier \fP ::= <match \(aq[A\-Za\-z_][A\-Za\-z0\-9_]*\(aq>
\fBarguments \fP ::= \fI\%argument\fP? \fI\%separated_arguments\fP*
\fBseparated_arguments\fP ::= \fI\%separation\fP+ \fI\%argument\fP? |
\fI\%separation\fP* \(aq(\(aq \fI\%arguments\fP \(aq)\(aq
\fBseparation \fP ::= \fI\%space\fP | \fI\%line_ending\fP
.fi
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
add_executable(hello world.c)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Command names are case\-insensitive.
Nested unquoted parentheses in the arguments must balance.
Each \fB(\fP or \fB)\fP is given to the command invocation as
a literal \fI\%Unquoted Argument\fP\&. This may be used in calls
to the \fBif()\fP command to enclose conditions.
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if(FALSE AND (FALSE OR TRUE)) # evaluates to FALSE
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
CMake versions prior to 3.0 require command name identifiers
to be at least 2 characters.
.sp
CMake versions prior to 2.8.12 silently accept an \fI\%Unquoted Argument\fP
or a \fI\%Quoted Argument\fP immediately following a \fI\%Quoted Argument\fP and
not separated by any whitespace. For compatibility, CMake 2.8.12 and
higher accept such code but produce a warning.
.UNINDENT
.UNINDENT
.SS Command Arguments
.sp
There are three types of arguments within \fI\%Command Invocations\fP:
.sp
.nf
\fBargument\fP ::= \fI\%bracket_argument\fP | \fI\%quoted_argument\fP | \fI\%unquoted_argument\fP
.fi
.SS Bracket Argument
.sp
A \fIbracket argument\fP, inspired by \fI\%Lua\fP long bracket syntax,
encloses content between opening and closing "brackets" of the
same length:
.sp
.nf
\fBbracket_argument\fP ::= \fI\%bracket_open\fP \fI\%bracket_content\fP \fI\%bracket_close\fP
\fBbracket_open \fP ::= \(aq[\(aq \(aq=\(aq* \(aq[\(aq
\fBbracket_content \fP ::= <any text not containing a \fI\%bracket_close\fP with
the same number of \(aq=\(aq as the \fI\%bracket_open\fP>
\fBbracket_close \fP ::= \(aq]\(aq \(aq=\(aq* \(aq]\(aq
.fi
.sp
An opening bracket is written \fB[\fP followed by zero or more \fB=\fP followed
by \fB[\fP\&. The corresponding closing bracket is written \fB]\fP followed
by the same number of \fB=\fP followed by \fB]\fP\&.
Brackets do not nest. A unique length may always be chosen
for the opening and closing brackets to contain closing brackets
of other lengths.
.sp
Bracket argument content consists of all text between the opening
and closing brackets, except that one newline immediately following
the opening bracket, if any, is ignored. No evaluation of the
enclosed content, such as \fI\%Escape Sequences\fP or \fI\%Variable References\fP,
is performed. A bracket argument is always given to the command
invocation as exactly one argument.
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
message([=[
This is the first line in a bracket argument with bracket length 1.
No \e\-escape sequences or ${variable} references are evaluated.
This is always one argument even though it contains a ; character.
The text does not end on a closing bracket of length 0 like ]].
It does end in a closing bracket of length 1.
]=])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
CMake versions prior to 3.0 do not support bracket arguments.
They interpret the opening bracket as the start of an
\fI\%Unquoted Argument\fP\&.
.UNINDENT
.UNINDENT
.SS Quoted Argument
.sp
A \fIquoted argument\fP encloses content between opening and closing
double\-quote characters:
.sp
.nf
\fBquoted_argument \fP ::= \(aq"\(aq \fI\%quoted_element\fP* \(aq"\(aq
\fBquoted_element \fP ::= <any character except \(aq\e\(aq or \(aq"\(aq> |
\fI\%escape_sequence\fP |
\fI\%quoted_continuation\fP
\fBquoted_continuation\fP ::= \(aq\e\(aq \fI\%newline\fP
.fi
.sp
Quoted argument content consists of all text between opening and
closing quotes. Both \fI\%Escape Sequences\fP and \fI\%Variable References\fP
are evaluated. A quoted argument is always given to the command
invocation as exactly one argument.
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
message("This is a quoted argument containing multiple lines.
This is always one argument even though it contains a ; character.
Both \e\e\-escape sequences and ${variable} references are evaluated.
The text does not end on an escaped double\-quote like \e".
It does end in an unescaped double quote.
")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The final \fB\e\fP on any line ending in an odd number of backslashes
is treated as a line continuation and ignored along with the
immediately following newline character. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
message("\e
This is the first line of a quoted argument. \e
In fact it is the only line but since it is long \e
the source code uses line continuation.\e
")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
CMake versions prior to 3.0 do not support continuation with \fB\e\fP\&.
They report errors in quoted arguments containing lines ending in
an odd number of \fB\e\fP characters.
.UNINDENT
.UNINDENT
.SS Unquoted Argument
.sp
An \fIunquoted argument\fP is not enclosed by any quoting syntax.
It may not contain any whitespace, \fB(\fP, \fB)\fP, \fB#\fP, \fB"\fP, or \fB\e\fP
except when escaped by a backslash:
.sp
.nf
\fBunquoted_argument\fP ::= \fI\%unquoted_element\fP+ | \fI\%unquoted_legacy\fP
\fBunquoted_element \fP ::= <any character except whitespace or one of \(aq()#"\e\(aq> |
\fI\%escape_sequence\fP
\fBunquoted_legacy \fP ::= <see note in text>
.fi
.sp
Unquoted argument content consists of all text in a contiguous block
of allowed or escaped characters. Both \fI\%Escape Sequences\fP and
\fI\%Variable References\fP are evaluated. The resulting value is divided
in the same way \fI\%Lists\fP divide into elements. Each non\-empty element
is given to the command invocation as an argument. Therefore an
unquoted argument may be given to a command invocation as zero or
more arguments.
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foreach(arg
NoSpace
Escaped\e Space
This;Divides;Into;Five;Arguments
Escaped\e;Semicolon
)
message("${arg}")
endforeach()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
To support legacy CMake code, unquoted arguments may also contain
double\-quoted strings (\fB"..."\fP, possibly enclosing horizontal
whitespace), and make\-style variable references (\fB$(MAKEVAR)\fP).
.sp
Unescaped double\-quotes must balance, may not appear at the
beginning of an unquoted argument, and are treated as part of the
content. For example, the unquoted arguments \fB\-Da="b c"\fP,
\fB\-Da=$(v)\fP, and \fBa" "b"c"d\fP are each interpreted literally.
They may instead be written as quoted arguments \fB"\-Da=\e"b c\e""\fP,
\fB"\-Da=$(v)"\fP, and \fB"a\e" \e"b\e"c\e"d"\fP, respectively.
.sp
Make\-style references are treated literally as part of the content
and do not undergo variable expansion. They are treated as part
of a single argument (rather than as separate \fB$\fP, \fB(\fP,
\fBMAKEVAR\fP, and \fB)\fP arguments).
.sp
The above "unquoted_legacy" production represents such arguments.
We do not recommend using legacy unquoted arguments in new code.
Instead use a \fI\%Quoted Argument\fP or a \fI\%Bracket Argument\fP to
represent the content.
.UNINDENT
.UNINDENT
.SS Escape Sequences
.sp
An \fIescape sequence\fP is a \fB\e\fP followed by one character:
.sp
.nf
\fBescape_sequence \fP ::= \fI\%escape_identity\fP | \fI\%escape_encoded\fP | \fI\%escape_semicolon\fP
\fBescape_identity \fP ::= \(aq\e\(aq <match \(aq[^A\-Za\-z0\-9;]\(aq>
\fBescape_encoded \fP ::= \(aq\et\(aq | \(aq\er\(aq | \(aq\en\(aq
\fBescape_semicolon\fP ::= \(aq\e;\(aq
.fi
.sp
A \fB\e\fP followed by a non\-alphanumeric character simply encodes the literal
character without interpreting it as syntax. A \fB\et\fP, \fB\er\fP, or \fB\en\fP
encodes a tab, carriage return, or newline character, respectively. A \fB\e;\fP
outside of any \fI\%Variable References\fP encodes itself but may be used in an
\fI\%Unquoted Argument\fP to encode the \fB;\fP without dividing the argument
value on it. A \fB\e;\fP inside \fI\%Variable References\fP encodes the literal
\fB;\fP character. (See also policy \fBCMP0053\fP documentation for
historical considerations.)
.SS Variable References
.sp
A \fIvariable reference\fP has the form \fB${<variable>}\fP and is
evaluated inside a \fI\%Quoted Argument\fP or an \fI\%Unquoted Argument\fP\&.
A variable reference is replaced by the value of the variable,
or by the empty string if the variable is not set.
Variable references can nest and are evaluated from the
inside out, e.g. \fB${outer_${inner_variable}_variable}\fP\&.
.sp
Literal variable references may consist of alphanumeric characters,
the characters \fB/_.+\-\fP, and \fI\%Escape Sequences\fP\&. Nested references
may be used to evaluate variables of any name. See also policy
\fBCMP0053\fP documentation for historical considerations and reasons why
the \fB$\fP is also technically permitted but is discouraged.
.sp
The \fI\%Variables\fP section documents the scope of variable names
and how their values are set.
.sp
An \fIenvironment variable reference\fP has the form \fB$ENV{<variable>}\fP\&.
See the \fI\%Environment Variables\fP section for more information.
.sp
A \fIcache variable reference\fP has the form \fB$CACHE{<variable>}\fP\&.
See \fBCACHE\fP for more information.
.sp
The \fBif()\fP command has a special condition syntax that
allows for variable references in the short form \fB<variable>\fP
instead of \fB${<variable>}\fP\&.
However, environment and cache variables always need to be
referenced as \fB$ENV{<variable>}\fP or \fB$CACHE{<variable>}\fP\&.
.SS Comments
.sp
A comment starts with a \fB#\fP character that is not inside a
\fI\%Bracket Argument\fP, \fI\%Quoted Argument\fP, or escaped with \fB\e\fP
as part of an \fI\%Unquoted Argument\fP\&. There are two types of
comments: a \fI\%Bracket Comment\fP and a \fI\%Line Comment\fP\&.
.SS Bracket Comment
.sp
A \fB#\fP immediately followed by a \fI\%bracket_open\fP forms a
\fIbracket comment\fP consisting of the entire bracket enclosure:
.sp
.nf
\fBbracket_comment\fP ::= \(aq#\(aq \fI\%bracket_argument\fP
.fi
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#[[This is a bracket comment.
It runs until the close bracket.]]
message("First Argument\en" #[[Bracket Comment]] "Second Argument")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
CMake versions prior to 3.0 do not support bracket comments.
They interpret the opening \fB#\fP as the start of a \fI\%Line Comment\fP\&.
.UNINDENT
.UNINDENT
.SS Line Comment
.sp
A \fB#\fP not immediately followed by a \fI\%bracket_open\fP forms a
\fIline comment\fP that runs until the end of the line:
.sp
.nf
\fBline_comment\fP ::= \(aq#\(aq <any text not starting in a \fI\%bracket_open\fP
and not containing a \fI\%newline\fP>
.fi
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# This is a line comment.
message("First Argument\en" # This is a line comment :)
"Second Argument") # This is a line comment.
.ft P
.fi
.UNINDENT
.UNINDENT
.SH CONTROL STRUCTURES
.SS Conditional Blocks
.sp
The \fBif()\fP/\fBelseif()\fP/\fBelse()\fP/\fBendif()\fP
commands delimit code blocks to be executed conditionally.
.SS Loops
.sp
The \fBforeach()\fP/\fBendforeach()\fP and
\fBwhile()\fP/\fBendwhile()\fP commands delimit code
blocks to be executed in a loop. Inside such blocks the
\fBbreak()\fP command may be used to terminate the loop
early whereas the \fBcontinue()\fP command may be used
to start with the next iteration immediately.
.SS Command Definitions
.sp
The \fBmacro()\fP/\fBendmacro()\fP, and
\fBfunction()\fP/\fBendfunction()\fP commands delimit
code blocks to be recorded for later invocation as commands.
.SH VARIABLES
.sp
Variables are the basic unit of storage in the CMake Language.
Their values are always of string type, though some commands may
interpret the strings as values of other types.
The \fBset()\fP and \fBunset()\fP commands explicitly
set or unset a variable, but other commands have semantics
that modify variables as well.
Variable names are case\-sensitive and may consist of almost
any text, but we recommend sticking to names consisting only
of alphanumeric characters plus \fB_\fP and \fB\-\fP\&.
.sp
Variables have dynamic scope. Each variable "set" or "unset"
creates a binding in the current scope:
.INDENT 0.0
.TP
.B Function Scope
\fI\%Command Definitions\fP created by the \fBfunction()\fP command
create commands that, when invoked, process the recorded commands
in a new variable binding scope. A variable "set" or "unset"
binds in this scope and is visible for the current function and
any nested calls within it, but not after the function returns.
.TP
.B Directory Scope
Each of the \fI\%Directories\fP in a source tree has its own variable
bindings. Before processing the \fBCMakeLists.txt\fP file for a
directory, CMake copies all variable bindings currently defined
in the parent directory, if any, to initialize the new directory
scope. CMake \fI\%Scripts\fP, when processed with \fBcmake \-P\fP, bind
variables in one "directory" scope.
.sp
A variable "set" or "unset" not inside a function call binds
to the current directory scope.
.TP
.B Persistent Cache
CMake stores a separate set of "cache" variables, or "cache entries",
whose values persist across multiple runs within a project build
tree. Cache entries have an isolated binding scope modified only
by explicit request, such as by the \fBCACHE\fP option of the
\fBset()\fP and \fBunset()\fP commands.
.UNINDENT
.sp
When evaluating \fI\%Variable References\fP, CMake first searches the
function call stack, if any, for a binding and then falls back
to the binding in the current directory scope, if any. If a
"set" binding is found, its value is used. If an "unset" binding
is found, or no binding is found, CMake then searches for a
cache entry. If a cache entry is found, its value is used.
Otherwise, the variable reference evaluates to an empty string.
The \fB$CACHE{VAR}\fP syntax can be used to do direct cache entry
lookups.
.sp
The \fBcmake\-variables(7)\fP manual documents the many variables
that are provided by CMake or have meaning to CMake when set
by project code.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
CMake reserves identifiers that:
.INDENT 0.0
.IP \(bu 2
begin with \fBCMAKE_\fP (upper\-, lower\-, or mixed\-case), or
.IP \(bu 2
begin with \fB_CMAKE_\fP (upper\-, lower\-, or mixed\-case), or
.IP \(bu 2
begin with \fB_\fP followed by the name of any \fBCMake Command\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SH ENVIRONMENT VARIABLES
.sp
Environment Variables are like ordinary \fI\%Variables\fP, with the
following differences:
.INDENT 0.0
.TP
.B Scope
Environment variables have global scope in a CMake process.
They are never cached.
.TP
.B References
\fI\%Variable References\fP have the form \fB$ENV{<variable>}\fP\&.
.TP
.B Initialization
Initial values of the CMake environment variables are those of
the calling process.
Values can be changed using the \fBset()\fP and \fBunset()\fP
commands.
These commands only affect the running CMake process,
not the system environment at large.
Changed values are not written back to the calling process,
and they are not seen by subsequent build or test processes.
.UNINDENT
.sp
The \fBcmake\-env\-variables(7)\fP manual documents environment
variables that have special meaning to CMake.
.SH LISTS
.sp
Although all values in CMake are stored as strings, a string
may be treated as a list in certain contexts, such as during
evaluation of an \fI\%Unquoted Argument\fP\&. In such contexts, a string
is divided into list elements by splitting on \fB;\fP characters not
following an unequal number of \fB[\fP and \fB]\fP characters and not
immediately preceded by a \fB\e\fP\&. The sequence \fB\e;\fP does not
divide a value but is replaced by \fB;\fP in the resulting element.
.sp
A list of elements is represented as a string by concatenating
the elements separated by \fB;\fP\&. For example, the \fBset()\fP
command stores multiple values into the destination variable
as a list:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(srcs a.c b.c c.c) # sets "srcs" to "a.c;b.c;c.c"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Lists are meant for simple use cases such as a list of source
files and should not be used for complex data processing tasks.
Most commands that construct lists do not escape \fB;\fP characters
in list elements, thus flattening nested lists:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(x a "b;c") # sets "x" to "a;b;c", not "a;b\e;c"
.ft P
.fi
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

22602
cmake/cmake-modules.7
View File

File diff suppressed because it is too large Load Diff

897
cmake/cmake-packages.7
View File

@ -1,897 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CMAKE-PACKAGES" "7" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
cmake-packages \- CMake Packages Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH INTRODUCTION
.sp
Packages provide dependency information to CMake based buildsystems. Packages
are found with the \fBfind_package()\fP command. The result of
using \fBfind_package()\fP is either a set of \fBIMPORTED\fP targets, or
a set of variables corresponding to build\-relevant information.
.SH USING PACKAGES
.sp
CMake provides direct support for two forms of packages,
\fI\%Config\-file Packages\fP and \fI\%Find\-module Packages\fP\&.
Indirect support for \fBpkg\-config\fP packages is also provided via
the \fBFindPkgConfig\fP module. In all cases, the basic form
of \fBfind_package()\fP calls is the same:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(Qt4 4.7.0 REQUIRED) # CMake provides a Qt4 find\-module
find_package(Qt5Core 5.1.0 REQUIRED) # Qt provides a Qt5 package config file.
find_package(LibXml2 REQUIRED) # Use pkg\-config via the LibXml2 find\-module
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In cases where it is known that a package configuration file is provided by
upstream, and only that should be used, the \fBCONFIG\fP keyword may be passed
to \fBfind_package()\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(Qt5Core 5.1.0 CONFIG REQUIRED)
find_package(Qt5Gui 5.1.0 CONFIG)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Similarly, the \fBMODULE\fP keyword says to use only a find\-module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(Qt4 4.7.0 MODULE REQUIRED)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Specifying the type of package explicitly improves the error message shown to
the user if it is not found.
.sp
Both types of packages also support specifying components of a package,
either after the \fBREQUIRED\fP keyword:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(Qt5 5.1.0 CONFIG REQUIRED Widgets Xml Sql)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or as a separate \fBCOMPONENTS\fP list:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(Qt5 5.1.0 COMPONENTS Widgets Xml Sql)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or as a separate \fBOPTIONAL_COMPONENTS\fP list:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(Qt5 5.1.0 COMPONENTS Widgets
OPTIONAL_COMPONENTS Xml Sql
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Handling of \fBCOMPONENTS\fP and \fBOPTIONAL_COMPONENTS\fP is defined by the
package.
.sp
By setting the \fBCMAKE_DISABLE_FIND_PACKAGE_<PackageName>\fP variable to
\fBTRUE\fP, the \fB<PackageName>\fP package will not be searched, and will always
be \fBNOTFOUND\fP\&.
.SS Config\-file Packages
.sp
A config\-file package is a set of files provided by upstreams for downstreams
to use. CMake searches in a number of locations for package configuration files, as
described in the \fBfind_package()\fP documentation. The most simple way for
a CMake user to tell \fBcmake(1)\fP to search in a non\-standard prefix for
a package is to set the \fBCMAKE_PREFIX_PATH\fP cache variable.
.sp
Config\-file packages are provided by upstream vendors as part of development
packages, that is, they belong with the header files and any other files
provided to assist downstreams in using the package.
.sp
A set of variables which provide package status information are also set
automatically when using a config\-file package. The \fB<PackageName>_FOUND\fP
variable is set to true or false, depending on whether the package was
found. The \fB<PackageName>_DIR\fP cache variable is set to the location of the
package configuration file.
.SS Find\-module Packages
.sp
A find module is a file with a set of rules for finding the required pieces of
a dependency, primarily header files and libraries. Typically, a find module
is needed when the upstream is not built with CMake, or is not CMake\-aware
enough to otherwise provide a package configuration file. Unlike a package configuration
file, it is not shipped with upstream, but is used by downstream to find the
files by guessing locations of files with platform\-specific hints.
.sp
Unlike the case of an upstream\-provided package configuration file, no single point
of reference identifies the package as being found, so the \fB<PackageName>_FOUND\fP
variable is not automatically set by the \fBfind_package()\fP command. It
can still be expected to be set by convention however and should be set by
the author of the Find\-module. Similarly there is no \fB<PackageName>_DIR\fP variable,
but each of the artifacts such as library locations and header file locations
provide a separate cache variable.
.sp
See the \fBcmake\-developer(7)\fP manual for more information about creating
Find\-module files.
.SH PACKAGE LAYOUT
.sp
A config\-file package consists of a \fI\%Package Configuration File\fP and
optionally a \fI\%Package Version File\fP provided with the project distribution.
.SS Package Configuration File
.sp
Consider a project \fBFoo\fP that installs the following files:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<prefix>/include/foo\-1.2/foo.h
<prefix>/lib/foo\-1.2/libfoo.a
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It may also provide a CMake package configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<prefix>/lib/cmake/foo\-1.2/FooConfig.cmake
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
with content defining \fBIMPORTED\fP targets, or defining variables, such
as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# ...
# (compute PREFIX relative to file location)
# ...
set(Foo_INCLUDE_DIRS ${PREFIX}/include/foo\-1.2)
set(Foo_LIBRARIES ${PREFIX}/lib/foo\-1.2/libfoo.a)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If another project wishes to use \fBFoo\fP it need only to locate the \fBFooConfig.cmake\fP
file and load it to get all the information it needs about package content
locations. Since the package configuration file is provided by the package
installation it already knows all the file locations.
.sp
The \fBfind_package()\fP command may be used to search for the package
configuration file. This command constructs a set of installation prefixes
and searches under each prefix in several locations. Given the name \fBFoo\fP,
it looks for a file called \fBFooConfig.cmake\fP or \fBfoo\-config.cmake\fP\&.
The full set of locations is specified in the \fBfind_package()\fP command
documentation. One place it looks is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<prefix>/lib/cmake/Foo*/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where \fBFoo*\fP is a case\-insensitive globbing expression. In our example the
globbing expression will match \fB<prefix>/lib/cmake/foo\-1.2\fP and the package
configuration file will be found.
.sp
Once found, a package configuration file is immediately loaded. It, together
with a package version file, contains all the information the project needs to
use the package.
.SS Package Version File
.sp
When the \fBfind_package()\fP command finds a candidate package configuration
file it looks next to it for a version file. The version file is loaded to test
whether the package version is an acceptable match for the version requested.
If the version file claims compatibility the configuration file is accepted.
Otherwise it is ignored.
.sp
The name of the package version file must match that of the package configuration
file but has either \fB\-version\fP or \fBVersion\fP appended to the name before
the \fB\&.cmake\fP extension. For example, the files:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<prefix>/lib/cmake/foo\-1.3/foo\-config.cmake
<prefix>/lib/cmake/foo\-1.3/foo\-config\-version.cmake
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<prefix>/lib/cmake/bar\-4.2/BarConfig.cmake
<prefix>/lib/cmake/bar\-4.2/BarConfigVersion.cmake
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
are each pairs of package configuration files and corresponding package version
files.
.sp
When the \fBfind_package()\fP command loads a version file it first sets the
following variables:
.INDENT 0.0
.TP
.B \fBPACKAGE_FIND_NAME\fP
The \fB<PackageName>\fP
.TP
.B \fBPACKAGE_FIND_VERSION\fP
Full requested version string
.TP
.B \fBPACKAGE_FIND_VERSION_MAJOR\fP
Major version if requested, else 0
.TP
.B \fBPACKAGE_FIND_VERSION_MINOR\fP
Minor version if requested, else 0
.TP
.B \fBPACKAGE_FIND_VERSION_PATCH\fP
Patch version if requested, else 0
.TP
.B \fBPACKAGE_FIND_VERSION_TWEAK\fP
Tweak version if requested, else 0
.TP
.B \fBPACKAGE_FIND_VERSION_COUNT\fP
Number of version components, 0 to 4
.UNINDENT
.sp
The version file must use these variables to check whether it is compatible or
an exact match for the requested version and set the following variables with
results:
.INDENT 0.0
.TP
.B \fBPACKAGE_VERSION\fP
Full provided version string
.TP
.B \fBPACKAGE_VERSION_EXACT\fP
True if version is exact match
.TP
.B \fBPACKAGE_VERSION_COMPATIBLE\fP
True if version is compatible
.TP
.B \fBPACKAGE_VERSION_UNSUITABLE\fP
True if unsuitable as any version
.UNINDENT
.sp
Version files are loaded in a nested scope so they are free to set any variables
they wish as part of their computation. The find_package command wipes out the
scope when the version file has completed and it has checked the output
variables. When the version file claims to be an acceptable match for the
requested version the find_package command sets the following variables for
use by the project:
.INDENT 0.0
.TP
.B \fB<PackageName>_VERSION\fP
Full provided version string
.TP
.B \fB<PackageName>_VERSION_MAJOR\fP
Major version if provided, else 0
.TP
.B \fB<PackageName>_VERSION_MINOR\fP
Minor version if provided, else 0
.TP
.B \fB<PackageName>_VERSION_PATCH\fP
Patch version if provided, else 0
.TP
.B \fB<PackageName>_VERSION_TWEAK\fP
Tweak version if provided, else 0
.TP
.B \fB<PackageName>_VERSION_COUNT\fP
Number of version components, 0 to 4
.UNINDENT
.sp
The variables report the version of the package that was actually found.
The \fB<PackageName>\fP part of their name matches the argument given to the
\fBfind_package()\fP command.
.SH CREATING PACKAGES
.sp
Usually, the upstream depends on CMake itself and can use some CMake facilities
for creating the package files. Consider an upstream which provides a single
shared library:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
project(UpstreamLib)
set(CMAKE_INCLUDE_CURRENT_DIR ON)
set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON)
set(Upstream_VERSION 3.4.1)
include(GenerateExportHeader)
add_library(ClimbingStats SHARED climbingstats.cpp)
generate_export_header(ClimbingStats)
set_property(TARGET ClimbingStats PROPERTY VERSION ${Upstream_VERSION})
set_property(TARGET ClimbingStats PROPERTY SOVERSION 3)
set_property(TARGET ClimbingStats PROPERTY
INTERFACE_ClimbingStats_MAJOR_VERSION 3)
set_property(TARGET ClimbingStats APPEND PROPERTY
COMPATIBLE_INTERFACE_STRING ClimbingStats_MAJOR_VERSION
)
install(TARGETS ClimbingStats EXPORT ClimbingStatsTargets
LIBRARY DESTINATION lib
ARCHIVE DESTINATION lib
RUNTIME DESTINATION bin
INCLUDES DESTINATION include
)
install(
FILES
climbingstats.h
"${CMAKE_CURRENT_BINARY_DIR}/climbingstats_export.h"
DESTINATION
include
COMPONENT
Devel
)
include(CMakePackageConfigHelpers)
write_basic_package_version_file(
"${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
VERSION ${Upstream_VERSION}
COMPATIBILITY AnyNewerVersion
)
export(EXPORT ClimbingStatsTargets
FILE "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsTargets.cmake"
NAMESPACE Upstream::
)
configure_file(cmake/ClimbingStatsConfig.cmake
"${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfig.cmake"
COPYONLY
)
set(ConfigPackageLocation lib/cmake/ClimbingStats)
install(EXPORT ClimbingStatsTargets
FILE
ClimbingStatsTargets.cmake
NAMESPACE
Upstream::
DESTINATION
${ConfigPackageLocation}
)
install(
FILES
cmake/ClimbingStatsConfig.cmake
"${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
DESTINATION
${ConfigPackageLocation}
COMPONENT
Devel
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBCMakePackageConfigHelpers\fP module provides a macro for creating
a simple \fBConfigVersion.cmake\fP file. This file sets the version of the
package. It is read by CMake when \fBfind_package()\fP is called to
determine the compatibility with the requested version, and to set some
version\-specific variables \fB<PackageName>_VERSION\fP, \fB<PackageName>_VERSION_MAJOR\fP,
\fB<PackageName>_VERSION_MINOR\fP etc. The \fBinstall(EXPORT)\fP command is
used to export the targets in the \fBClimbingStatsTargets\fP export\-set, defined
previously by the \fBinstall(TARGETS)\fP command. This command generates
the \fBClimbingStatsTargets.cmake\fP file to contain \fBIMPORTED\fP
targets, suitable for use by downstreams and arranges to install it to
\fBlib/cmake/ClimbingStats\fP\&. The generated \fBClimbingStatsConfigVersion.cmake\fP
and a \fBcmake/ClimbingStatsConfig.cmake\fP are installed to the same location,
completing the package.
.sp
The generated \fBIMPORTED\fP targets have appropriate properties set
to define their usage requirements, such as
\fBINTERFACE_INCLUDE_DIRECTORIES\fP,
\fBINTERFACE_COMPILE_DEFINITIONS\fP and other relevant built\-in
\fBINTERFACE_\fP properties. The \fBINTERFACE\fP variant of user\-defined
properties listed in \fBCOMPATIBLE_INTERFACE_STRING\fP and
other Compatible Interface Properties are also propagated to the
generated \fBIMPORTED\fP targets. In the above case,
\fBClimbingStats_MAJOR_VERSION\fP is defined as a string which must be
compatible among the dependencies of any depender. By setting this custom
defined user property in this version and in the next version of
\fBClimbingStats\fP, \fBcmake(1)\fP will issue a diagnostic if there is an
attempt to use version 3 together with version 4. Packages can choose to
employ such a pattern if different major versions of the package are designed
to be incompatible.
.sp
A \fBNAMESPACE\fP with double\-colons is specified when exporting the targets
for installation. This convention of double\-colons gives CMake a hint that
the name is an \fBIMPORTED\fP target when it is used by downstreams
with the \fBtarget_link_libraries()\fP command. This way, CMake can
issue a diagnostic if the package providing it has not yet been found.
.sp
In this case, when using \fBinstall(TARGETS)\fP the \fBINCLUDES DESTINATION\fP
was specified. This causes the \fBIMPORTED\fP targets to have their
\fBINTERFACE_INCLUDE_DIRECTORIES\fP populated with the \fBinclude\fP
directory in the \fBCMAKE_INSTALL_PREFIX\fP\&. When the \fBIMPORTED\fP
target is used by downstream, it automatically consumes the entries from
that property.
.SS Creating a Package Configuration File
.sp
In this case, the \fBClimbingStatsConfig.cmake\fP file could be as simple as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As this allows downstreams to use the \fBIMPORTED\fP targets. If any macros
should be provided by the \fBClimbingStats\fP package, they should
be in a separate file which is installed to the same location as the
\fBClimbingStatsConfig.cmake\fP file, and included from there.
.sp
This can also be extended to cover dependencies:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# ...
add_library(ClimbingStats SHARED climbingstats.cpp)
generate_export_header(ClimbingStats)
find_package(Stats 2.6.4 REQUIRED)
target_link_libraries(ClimbingStats PUBLIC Stats::Types)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As the \fBStats::Types\fP target is a \fBPUBLIC\fP dependency of \fBClimbingStats\fP,
downstreams must also find the \fBStats\fP package and link to the \fBStats::Types\fP
library. The \fBStats\fP package should be found in the \fBClimbingStatsConfig.cmake\fP
file to ensure this. The \fBfind_dependency\fP macro from the
\fBCMakeFindDependencyMacro\fP helps with this by propagating
whether the package is \fBREQUIRED\fP, or \fBQUIET\fP etc. All \fBREQUIRED\fP
dependencies of a package should be found in the \fBConfig.cmake\fP file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include(CMakeFindDependencyMacro)
find_dependency(Stats 2.6.4)
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBfind_dependency\fP macro also sets \fBClimbingStats_FOUND\fP to \fBFalse\fP if
the dependency is not found, along with a diagnostic that the \fBClimbingStats\fP
package can not be used without the \fBStats\fP package.
.sp
If \fBCOMPONENTS\fP are specified when the downstream uses \fBfind_package()\fP,
they are listed in the \fB<PackageName>_FIND_COMPONENTS\fP variable. If a particular
component is non\-optional, then the \fB<PackageName>_FIND_REQUIRED_<comp>\fP will
be true. This can be tested with logic in the package configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include(CMakeFindDependencyMacro)
find_dependency(Stats 2.6.4)
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")
set(_supported_components Plot Table)
foreach(_comp ${ClimbingStats_FIND_COMPONENTS})
if (NOT ";${_supported_components};" MATCHES _comp)
set(ClimbingStats_FOUND False)
set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
endif()
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStats${_comp}Targets.cmake")
endforeach()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Here, the \fBClimbingStats_NOT_FOUND_MESSAGE\fP is set to a diagnosis that the package
could not be found because an invalid component was specified. This message
variable can be set for any case where the \fB_FOUND\fP variable is set to \fBFalse\fP,
and will be displayed to the user.
.SS Creating a Package Configuration File for the Build Tree
.sp
The \fBexport(EXPORT)\fP command creates an \fBIMPORTED\fP targets
definition file which is specific to the build\-tree, and is not relocatable.
This can similarly be used with a suitable package configuration file and
package version file to define a package for the build tree which may be used
without installation. Consumers of the build tree can simply ensure that the
\fBCMAKE_PREFIX_PATH\fP contains the build directory, or set the
\fBClimbingStats_DIR\fP to \fB<build_dir>/ClimbingStats\fP in the cache.
.SS Creating Relocatable Packages
.sp
A relocatable package must not reference absolute paths of files on
the machine where the package is built that will not exist on the
machines where the package may be installed.
.sp
Packages created by \fBinstall(EXPORT)\fP are designed to be relocatable,
using paths relative to the location of the package itself. When defining
the interface of a target for \fBEXPORT\fP, keep in mind that the include
directories should be specified as relative paths which are relative to the
\fBCMAKE_INSTALL_PREFIX\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
target_include_directories(tgt INTERFACE
# Wrong, not relocatable:
$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
)
target_include_directories(tgt INTERFACE
# Ok, relocatable:
$<INSTALL_INTERFACE:include/TgtName>
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fB$<INSTALL_PREFIX>\fP
\fBgenerator expression\fP may be used as
a placeholder for the install prefix without resulting in a non\-relocatable
package. This is necessary if complex generator expressions are used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
target_include_directories(tgt INTERFACE
# Ok, relocatable:
$<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This also applies to paths referencing external dependencies.
It is not advisable to populate any properties which may contain
paths, such as \fBINTERFACE_INCLUDE_DIRECTORIES\fP and
\fBINTERFACE_LINK_LIBRARIES\fP, with paths relevant to dependencies.
For example, this code may not work well for a relocatable package:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
target_link_libraries(ClimbingStats INTERFACE
${Foo_LIBRARIES} ${Bar_LIBRARIES}
)
target_include_directories(ClimbingStats INTERFACE
"$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>"
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The referenced variables may contain the absolute paths to libraries
and include directories \fBas found on the machine the package was made on\fP\&.
This would create a package with hard\-coded paths to dependencies and not
suitable for relocation.
.sp
Ideally such dependencies should be used through their own
IMPORTED targets that have their own
\fBIMPORTED_LOCATION\fP and usage requirement properties
such as \fBINTERFACE_INCLUDE_DIRECTORIES\fP populated
appropriately. Those imported targets may then be used with
the \fBtarget_link_libraries()\fP command for \fBClimbingStats\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With this approach the package references its external dependencies
only through the names of IMPORTED targets\&.
When a consumer uses the installed package, the consumer will run the
appropriate \fBfind_package()\fP commands (via the \fBfind_dependency\fP
macro described above) to find the dependencies and populate the
imported targets with appropriate paths on their own machine.
.sp
Unfortunately many \fBmodules\fP shipped with
CMake do not yet provide IMPORTED targets
because their development pre\-dated this approach. This may improve
incrementally over time. Workarounds to create relocatable packages
using such modules include:
.INDENT 0.0
.IP \(bu 2
When building the package, specify each \fBFoo_LIBRARY\fP cache
entry as just a library name, e.g. \fB\-DFoo_LIBRARY=foo\fP\&. This
tells the corresponding find module to populate the \fBFoo_LIBRARIES\fP
with just \fBfoo\fP to ask the linker to search for the library
instead of hard\-coding a path.
.IP \(bu 2
Or, after installing the package content but before creating the
package installation binary for redistribution, manually replace
the absolute paths with placeholders for substitution by the
installation tool when the package is installed.
.UNINDENT
.SH PACKAGE REGISTRY
.sp
CMake provides two central locations to register packages that have
been built or installed anywhere on a system:
.INDENT 0.0
.IP \(bu 2
\fI\%User Package Registry\fP
.IP \(bu 2
\fI\%System Package Registry\fP
.UNINDENT
.sp
The registries are especially useful to help projects find packages in
non\-standard install locations or directly in their own build trees.
A project may populate either the user or system registry (using its own
means, see below) to refer to its location.
In either case the package should store at the registered location a
\fI\%Package Configuration File\fP (\fB<PackageName>Config.cmake\fP) and optionally a
\fI\%Package Version File\fP (\fB<PackageName>ConfigVersion.cmake\fP).
.sp
The \fBfind_package()\fP command searches the two package registries
as two of the search steps specified in its documentation. If it has
sufficient permissions it also removes stale package registry entries
that refer to directories that do not exist or do not contain a matching
package configuration file.
.SS User Package Registry
.sp
The User Package Registry is stored in a per\-user location.
The \fBexport(PACKAGE)\fP command may be used to register a project
build tree in the user package registry. CMake currently provides no
interface to add install trees to the user package registry. Installers
must be manually taught to register their packages if desired.
.sp
On Windows the user package registry is stored in the Windows registry
under a key in \fBHKEY_CURRENT_USER\fP\&.
.sp
A \fB<PackageName>\fP may appear under registry key:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
HKEY_CURRENT_USER\eSoftware\eKitware\eCMake\ePackages\e<PackageName>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
as a \fBREG_SZ\fP value, with arbitrary name, that specifies the directory
containing the package configuration file.
.sp
On UNIX platforms the user package registry is stored in the user home
directory under \fB~/.cmake/packages\fP\&. A \fB<PackageName>\fP may appear under
the directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
~/.cmake/packages/<PackageName>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
as a file, with arbitrary name, whose content specifies the directory
containing the package configuration file.
.SS System Package Registry
.sp
The System Package Registry is stored in a system\-wide location.
CMake currently provides no interface to add to the system package registry.
Installers must be manually taught to register their packages if desired.
.sp
On Windows the system package registry is stored in the Windows registry
under a key in \fBHKEY_LOCAL_MACHINE\fP\&. A \fB<PackageName>\fP may appear under
registry key:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
HKEY_LOCAL_MACHINE\eSoftware\eKitware\eCMake\ePackages\e<PackageName>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
as a \fBREG_SZ\fP value, with arbitrary name, that specifies the directory
containing the package configuration file.
.sp
There is no system package registry on non\-Windows platforms.
.SS Disabling the Package Registry
.sp
In some cases using the Package Registries is not desirable. CMake
allows one to disable them using the following variables:
.INDENT 0.0
.IP \(bu 2
The \fBexport(PACKAGE)\fP command does not populate the user
package registry when \fBCMP0090\fP is set to \fBNEW\fP unless the
\fBCMAKE_EXPORT_PACKAGE_REGISTRY\fP variable explicitly enables it.
When \fBCMP0090\fP is \fInot\fP set to \fBNEW\fP then
\fBexport(PACKAGE)\fP populates the user package registry unless
the \fBCMAKE_EXPORT_NO_PACKAGE_REGISTRY\fP variable explicitly
disables it.
.IP \(bu 2
\fBCMAKE_FIND_USE_PACKAGE_REGISTRY\fP disables the
User Package Registry in all the \fBfind_package()\fP calls when
set to \fBFALSE\fP\&.
.IP \(bu 2
Deprecated \fBCMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY\fP disables the
User Package Registry in all the \fBfind_package()\fP calls when set
to \fBTRUE\fP\&. This variable is ignored when
\fBCMAKE_FIND_USE_PACKAGE_REGISTRY\fP has been set.
.IP \(bu 2
\fBCMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY\fP disables
the System Package Registry in all the \fBfind_package()\fP calls.
.UNINDENT
.SS Package Registry Example
.sp
A simple convention for naming package registry entries is to use content
hashes. They are deterministic and unlikely to collide
(\fBexport(PACKAGE)\fP uses this approach).
The name of an entry referencing a specific directory is simply the content
hash of the directory path itself.
.sp
If a project arranges for package registry entries to exist, such as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
> reg query HKCU\eSoftware\eKitware\eCMake\ePackages\eMyPackage
HKEY_CURRENT_USER\eSoftware\eKitware\eCMake\ePackages\eMyPackage
45e7d55f13b87179bb12f907c8de6fc4 REG_SZ c:/Users/Me/Work/lib/cmake/MyPackage
7b4a9844f681c80ce93190d4e3185db9 REG_SZ c:/Users/Me/Work/MyPackage\-build
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd
/home/me/work/lib/cmake/MyPackage
$ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07
/home/me/work/MyPackage\-build
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
then the \fBCMakeLists.txt\fP code:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(MyPackage)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will search the registered locations for package configuration files
(\fBMyPackageConfig.cmake\fP). The search order among package registry
entries for a single package is unspecified and the entry names
(hashes in this example) have no meaning. Registered locations may
contain package version files (\fBMyPackageConfigVersion.cmake\fP) to
tell \fBfind_package()\fP whether a specific location is suitable
for the version requested.
.SS Package Registry Ownership
.sp
Package registry entries are individually owned by the project installations
that they reference. A package installer is responsible for adding its own
entry and the corresponding uninstaller is responsible for removing it.
.sp
The \fBexport(PACKAGE)\fP command populates the user package registry
with the location of a project build tree. Build trees tend to be deleted by
developers and have no "uninstall" event that could trigger removal of their
entries. In order to keep the registries clean the \fBfind_package()\fP
command automatically removes stale entries it encounters if it has sufficient
permissions. CMake provides no interface to remove an entry referencing an
existing build tree once \fBexport(PACKAGE)\fP has been invoked.
However, if the project removes its package configuration file from the build
tree then the entry referencing the location will be considered stale.
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

3996
cmake/cmake-policies.7
View File

File diff suppressed because it is too large Load Diff

7936
cmake/cmake-properties.7
View File

File diff suppressed because it is too large Load Diff

312
cmake/cmake-qt.7
View File

@ -1,312 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CMAKE-QT" "7" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
cmake-qt \- CMake Qt Features Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH INTRODUCTION
.sp
CMake can find and use Qt 4 and Qt 5 libraries. The Qt 4 libraries are found
by the \fBFindQt4\fP find\-module shipped with CMake, whereas the
Qt 5 libraries are found using "Config\-file Packages" shipped with Qt 5. See
\fBcmake\-packages(7)\fP for more information about CMake packages, and
see \fI\%the Qt cmake manual\fP
for your Qt version.
.sp
Qt 4 and Qt 5 may be used together in the same
\fBCMake buildsystem\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmake_minimum_required(VERSION 3.8.0 FATAL_ERROR)
project(Qt4And5)
set(CMAKE_AUTOMOC ON)
find_package(Qt5 COMPONENTS Widgets DBus REQUIRED)
add_executable(publisher publisher.cpp)
target_link_libraries(publisher Qt5::Widgets Qt5::DBus)
find_package(Qt4 REQUIRED)
add_executable(subscriber subscriber.cpp)
target_link_libraries(subscriber Qt4::QtGui Qt4::QtDBus)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A CMake target may not link to both Qt 4 and Qt 5. A diagnostic is issued if
this is attempted or results from transitive target dependency evaluation.
.SH QT BUILD TOOLS
.sp
Qt relies on some bundled tools for code generation, such as \fBmoc\fP for
meta\-object code generation, \fBuic\fP for widget layout and population,
and \fBrcc\fP for virtual file system content generation. These tools may be
automatically invoked by \fBcmake(1)\fP if the appropriate conditions
are met. The automatic tool invocation may be used with both Qt 4 and Qt 5.
.SS AUTOMOC
.sp
The \fBAUTOMOC\fP target property controls whether \fBcmake(1)\fP
inspects the C++ files in the target to determine if they require \fBmoc\fP to
be run, and to create rules to execute \fBmoc\fP at the appropriate time.
.sp
If a macro from \fBAUTOMOC_MACRO_NAMES\fP is found in a header file,
\fBmoc\fP will be run on the file. The result will be put into a file named
according to \fBmoc_<basename>.cpp\fP\&.
If the macro is found in a C++ implementation
file, the moc output will be put into a file named according to
\fB<basename>.moc\fP, following the Qt conventions. The \fB<basename>.moc\fP must
be included by the user in the C++ implementation file with a preprocessor
\fB#include\fP\&.
.sp
Included \fBmoc_*.cpp\fP and \fB*.moc\fP files will be generated in the
\fB<AUTOGEN_BUILD_DIR>/include\fP directory which is
automatically added to the target\(aqs \fBINCLUDE_DIRECTORIES\fP\&.
.INDENT 0.0
.IP \(bu 2
This differs from CMake 3.7 and below; see their documentation for details.
.IP \(bu 2
For \fBmulti configuration generators\fP,
the include directory is \fB<AUTOGEN_BUILD_DIR>/include_<CONFIG>\fP\&.
.IP \(bu 2
See \fBAUTOGEN_BUILD_DIR\fP\&.
.UNINDENT
.sp
Not included \fBmoc_<basename>.cpp\fP files will be generated in custom
folders to avoid name collisions and included in a separate
\fB<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp\fP file which is compiled
into the target.
.INDENT 0.0
.IP \(bu 2
See \fBAUTOGEN_BUILD_DIR\fP\&.
.UNINDENT
.sp
The \fBmoc\fP command line will consume the \fBCOMPILE_DEFINITIONS\fP and
\fBINCLUDE_DIRECTORIES\fP target properties from the target it is being
invoked for, and for the appropriate build configuration.
.sp
The \fBAUTOMOC\fP target property may be pre\-set for all
following targets by setting the \fBCMAKE_AUTOMOC\fP variable. The
\fBAUTOMOC_MOC_OPTIONS\fP target property may be populated to set
options to pass to \fBmoc\fP\&. The \fBCMAKE_AUTOMOC_MOC_OPTIONS\fP
variable may be populated to pre\-set the options for all following targets.
.sp
Additional macro names to search for can be added to
\fBAUTOMOC_MACRO_NAMES\fP\&.
.sp
Additional \fBmoc\fP dependency file names can be extracted from source code
by using \fBAUTOMOC_DEPEND_FILTERS\fP\&.
.sp
Source C++ files can be excluded from \fBAUTOMOC\fP processing by
enabling \fBSKIP_AUTOMOC\fP or the broader \fBSKIP_AUTOGEN\fP\&.
.SS AUTOUIC
.sp
The \fBAUTOUIC\fP target property controls whether \fBcmake(1)\fP
inspects the C++ files in the target to determine if they require \fBuic\fP to
be run, and to create rules to execute \fBuic\fP at the appropriate time.
.sp
If a preprocessor \fB#include\fP directive is found which matches
\fB<path>ui_<basename>.h\fP, and a \fB<basename>.ui\fP file exists,
then \fBuic\fP will be executed to generate the appropriate file.
The \fB<basename>.ui\fP file is searched for in the following places
.INDENT 0.0
.IP 1. 3
\fB<source_dir>/<basename>.ui\fP
.IP 2. 3
\fB<source_dir>/<path><basename>.ui\fP
.IP 3. 3
\fB<AUTOUIC_SEARCH_PATHS>/<basename>.ui\fP
.IP 4. 3
\fB<AUTOUIC_SEARCH_PATHS>/<path><basename>.ui\fP
.UNINDENT
.sp
where \fB<source_dir>\fP is the directory of the C++ file and
\fBAUTOUIC_SEARCH_PATHS\fP is a list of additional search paths.
.sp
The generated generated \fBui_*.h\fP files are placed in the
\fB<AUTOGEN_BUILD_DIR>/include\fP directory which is
automatically added to the target\(aqs \fBINCLUDE_DIRECTORIES\fP\&.
.INDENT 0.0
.IP \(bu 2
This differs from CMake 3.7 and below; see their documentation for details.
.IP \(bu 2
For \fBmulti configuration generators\fP,
the include directory is \fB<AUTOGEN_BUILD_DIR>/include_<CONFIG>\fP\&.
.IP \(bu 2
See \fBAUTOGEN_BUILD_DIR\fP\&.
.UNINDENT
.sp
The \fBAUTOUIC\fP target property may be pre\-set for all following
targets by setting the \fBCMAKE_AUTOUIC\fP variable. The
\fBAUTOUIC_OPTIONS\fP target property may be populated to set options
to pass to \fBuic\fP\&. The \fBCMAKE_AUTOUIC_OPTIONS\fP variable may be
populated to pre\-set the options for all following targets. The
\fBAUTOUIC_OPTIONS\fP source file property may be set on the
\fB<basename>.ui\fP file to set particular options for the file. This
overrides options from the \fBAUTOUIC_OPTIONS\fP target property.
.sp
A target may populate the \fBINTERFACE_AUTOUIC_OPTIONS\fP target
property with options that should be used when invoking \fBuic\fP\&. This must be
consistent with the \fBAUTOUIC_OPTIONS\fP target property content of the
depender target. The \fBCMAKE_DEBUG_TARGET_PROPERTIES\fP variable may
be used to track the origin target of such
\fBINTERFACE_AUTOUIC_OPTIONS\fP\&. This means that a library which
provides an alternative translation system for Qt may specify options which
should be used when running \fBuic\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
add_library(KI18n klocalizedstring.cpp)
target_link_libraries(KI18n Qt5::Core)
# KI18n uses the tr2i18n() function instead of tr(). That function is
# declared in the klocalizedstring.h header.
set(autouic_options
\-tr tr2i18n
\-include klocalizedstring.h
)
set_property(TARGET KI18n APPEND PROPERTY
INTERFACE_AUTOUIC_OPTIONS ${autouic_options}
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A consuming project linking to the target exported from upstream automatically
uses appropriate options when \fBuic\fP is run by \fBAUTOUIC\fP, as a
result of linking with the \fBIMPORTED\fP target:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(CMAKE_AUTOUIC ON)
# Uses a libwidget.ui file:
add_library(LibWidget libwidget.cpp)
target_link_libraries(LibWidget
KF5::KI18n
Qt5::Widgets
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Source files can be excluded from \fBAUTOUIC\fP processing by
enabling \fBSKIP_AUTOUIC\fP or the broader \fBSKIP_AUTOGEN\fP\&.
.SS AUTORCC
.sp
The \fBAUTORCC\fP target property controls whether \fBcmake(1)\fP
creates rules to execute \fBrcc\fP at the appropriate time on source files
which have the suffix \fB\&.qrc\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
add_executable(myexe main.cpp resource_file.qrc)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBAUTORCC\fP target property may be pre\-set for all following targets
by setting the \fBCMAKE_AUTORCC\fP variable. The
\fBAUTORCC_OPTIONS\fP target property may be populated to set options
to pass to \fBrcc\fP\&. The \fBCMAKE_AUTORCC_OPTIONS\fP variable may be
populated to pre\-set the options for all following targets. The
\fBAUTORCC_OPTIONS\fP source file property may be set on the
\fB<name>.qrc\fP file to set particular options for the file. This
overrides options from the \fBAUTORCC_OPTIONS\fP target property.
.sp
Source files can be excluded from \fBAUTORCC\fP processing by
enabling \fBSKIP_AUTORCC\fP or the broader \fBSKIP_AUTOGEN\fP\&.
.SH THE <ORIGIN>_AUTOGEN TARGET
.sp
The \fBmoc\fP and \fBuic\fP tools are executed as part of a synthesized
\fB<ORIGIN>_autogen\fP \fBcustom target\fP generated by
CMake. By default that \fB<ORIGIN>_autogen\fP target inherits the dependencies
of the \fB<ORIGIN>\fP target (see \fBAUTOGEN_ORIGIN_DEPENDS\fP).
Target dependencies may be added to the \fB<ORIGIN>_autogen\fP target by adding
them to the \fBAUTOGEN_TARGET_DEPENDS\fP target property.
.SH VISUAL STUDIO GENERATORS
.sp
When using the \fBVisual Studio generators\fP, CMake
generates a \fBPRE_BUILD\fP \fBcustom command\fP
instead of the \fB<ORIGIN>_autogen\fP \fBcustom target\fP
(for \fBAUTOMOC\fP and \fBAUTOUIC\fP).
This isn\(aqt always possible though and
an \fB<ORIGIN>_autogen\fP \fBcustom target\fP is used,
when either
.INDENT 0.0
.IP \(bu 2
the \fB<ORIGIN>\fP target depends on \fBGENERATED\fP files which aren\(aqt
excluded from \fBAUTOMOC\fP and \fBAUTOUIC\fP by
\fBSKIP_AUTOMOC\fP, \fBSKIP_AUTOUIC\fP, \fBSKIP_AUTOGEN\fP
or \fBCMP0071\fP
.IP \(bu 2
\fBAUTOGEN_TARGET_DEPENDS\fP lists a source file
.IP \(bu 2
\fBCMAKE_GLOBAL_AUTOGEN_TARGET\fP is enabled
.UNINDENT
.SH QTMAIN.LIB ON WINDOWS
.sp
The Qt 4 and 5 \fBIMPORTED\fP targets for the QtGui libraries specify
that the qtmain.lib static library shipped with Qt will be linked by all
dependent executables which have the \fBWIN32_EXECUTABLE\fP enabled.
.sp
To disable this behavior, enable the \fBQt5_NO_LINK_QTMAIN\fP target property for
Qt 5 based targets or \fBQT4_NO_LINK_QTMAIN\fP target property for Qt 4 based
targets.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
add_executable(myexe WIN32 main.cpp)
target_link_libraries(myexe Qt4::QtGui)
add_executable(myexe_no_qtmain WIN32 main_no_qtmain.cpp)
set_property(TARGET main_no_qtmain PROPERTY QT4_NO_LINK_QTMAIN ON)
target_link_libraries(main_no_qtmain Qt4::QtGui)
.ft P
.fi
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

992
cmake/cmake-server.7
View File

@ -1,992 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CMAKE-SERVER" "7" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
cmake-server \- CMake Server
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Deprecated since version 3.15: This will be removed from a future version of CMake.
Clients should use the \fBcmake\-file\-api(7)\fP instead.
.SH INTRODUCTION
.sp
\fBcmake(1)\fP is capable of providing semantic information about
CMake code it executes to generate a buildsystem. If executed with
the \fB\-E server\fP command line options, it starts in a long running mode
and allows a client to request the available information via a JSON protocol.
.sp
The protocol is designed to be useful to IDEs, refactoring tools, and
other tools which have a need to understand the buildsystem in entirety.
.sp
A single \fBcmake\-buildsystem(7)\fP may describe buildsystem contents
and build properties which differ based on
\fBgeneration\-time context\fP
including:
.INDENT 0.0
.IP \(bu 2
The Platform (eg, Windows, APPLE, Linux).
.IP \(bu 2
The build configuration (eg, Debug, Release, Coverage).
.IP \(bu 2
The Compiler (eg, MSVC, GCC, Clang) and compiler version.
.IP \(bu 2
The language of the source files compiled.
.IP \(bu 2
Available compile features (eg CXX variadic templates).
.IP \(bu 2
CMake policies.
.UNINDENT
.sp
The protocol aims to provide information to tooling to satisfy several
needs:
.INDENT 0.0
.IP 1. 3
Provide a complete and easily parsed source of all information relevant
to the tooling as it relates to the source code. There should be no need
for tooling to parse generated buildsystems to access include directories
or compile definitions for example.
.IP 2. 3
Semantic information about the CMake buildsystem itself.
.IP 3. 3
Provide a stable interface for reading the information in the CMake cache.
.IP 4. 3
Information for determining when cmake needs to be re\-run as a result of
file changes.
.UNINDENT
.SH OPERATION
.sp
Start \fBcmake(1)\fP in the server command mode, supplying the path to
the build directory to process:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmake \-E server (\-\-debug|\-\-pipe=<NAMED_PIPE>)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The server will communicate using stdin/stdout (with the \fB\-\-debug\fP parameter)
or using a named pipe (with the \fB\-\-pipe=<NAMED_PIPE>\fP parameter). Note
that "named pipe" refers to a local domain socket on Unix and to a named pipe
on Windows.
.sp
When connecting to the server (via named pipe or by starting it in \fB\-\-debug\fP
mode), the server will reply with a hello message:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Messages sent to and from the process are wrapped in magic strings:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{
... some JSON message ...
}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The server is now ready to accept further requests via the named pipe
or stdin.
.SH DEBUGGING
.sp
CMake server mode can be asked to provide statistics on execution times, etc.
or to dump a copy of the response into a file. This is done passing a "debug"
JSON object as a child of the request.
.sp
The debug object supports the "showStats" key, which takes a boolean and makes
the server mode return a "zzzDebug" object with stats as part of its response.
"dumpToFile" takes a string value and will cause the cmake server to copy
the response into the given filename.
.sp
This is a response from the cmake server with "showStats" set to true:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{
"cookie":"",
"errorMessage":"Waiting for type \e"handshake\e".",
"inReplyTo":"unknown",
"type":"error",
"zzzDebug": {
"dumpFile":"/tmp/error.txt",
"jsonSerialization":0.011016,
"size":111,
"totalTime":0.025995
}
}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The server has made a copy of this response into the file /tmp/error.txt and
took 0.011 seconds to turn the JSON response into a string, and it took 0.025
seconds to process the request in total. The reply has a size of 111 bytes.
.SH PROTOCOL API
.SS General Message Layout
.sp
All messages need to have a "type" value, which identifies the type of
message that is passed back or forth. E.g. the initial message sent by the
server is of type "hello". Messages without a type will generate an response
of type "error".
.sp
All requests sent to the server may contain a "cookie" value. This value
will he handed back unchanged in all responses triggered by the request.
.sp
All responses will contain a value "inReplyTo", which may be empty in
case of parse errors, but will contain the type of the request message
in all other cases.
.SS Type "reply"
.sp
This type is used by the server to reply to requests.
.sp
The message may \-\- depending on the type of the original request \-\-
contain values.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Type "error"
.sp
This type is used to return an error condition to the client. It will
contain an "errorMessage".
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Type "progress"
.sp
When the server is busy for a long time, it is polite to send back replies of
type "progress" to the client. These will contain a "progressMessage" with a
string describing the action currently taking place as well as
"progressMinimum", "progressMaximum" and "progressCurrent" with integer values
describing the range of progress.
.sp
Messages of type "progress" will be followed by more "progress" messages or with
a message of type "reply" or "error" that complete the request.
.sp
"progress" messages may not be emitted after the "reply" or "error" message for
the request that triggered the responses was delivered.
.SS Type "message"
.sp
A message is triggered when the server processes a request and produces some
form of output that should be displayed to the user. A Message has a "message"
with the actual text to display as well as a "title" with a suggested dialog
box title.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Type "signal"
.sp
The server can send signals when it detects changes in the system state. Signals
are of type "signal", have an empty "cookie" and "inReplyTo" field and always
have a "name" set to show which signal was sent.
.SS Specific Signals
.sp
The cmake server may sent signals with the following names:
.SS "dirty" Signal
.sp
The "dirty" signal is sent whenever the server determines that the configuration
of the project is no longer up\-to\-date. This happens when any of the files that have
an influence on the build system is changed.
.sp
The "dirty" signal may look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{
"cookie":"",
"inReplyTo":"",
"name":"dirty",
"type":"signal"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS "fileChange" Signal
.sp
The "fileChange" signal is sent whenever a watched file is changed. It contains
the "path" that has changed and a list of "properties" with the kind of change
that was detected. Possible changes are "change" and "rename".
.sp
The "fileChange" signal looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{
"cookie":"",
"inReplyTo":"",
"name":"fileChange",
"path":"/absolute/CMakeLists.txt",
"properties":["change"],
"type":"signal"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Specific Message Types
.SS Type "hello"
.sp
The initial message send by the cmake server on startup is of type "hello".
This is the only message ever sent by the server that is not of type "reply",
"progress" or "error".
.sp
It will contain "supportedProtocolVersions" with an array of server protocol
versions supported by the cmake server. These are JSON objects with "major" and
"minor" keys containing non\-negative integer values. Some versions may be marked
as experimental. These will contain the "isExperimental" key set to true. Enabling
these requires a special command line argument when starting the cmake server mode.
.sp
Within a "major" version all "minor" versions are fully backwards compatible.
New "minor" versions may introduce functionality in such a way that existing
clients of the same "major" version will continue to work, provided they
ignore keys in the output that they do not know about.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Type "handshake"
.sp
The first request that the client may send to the server is of type "handshake".
.sp
This request needs to pass one of the "supportedProtocolVersions" of the "hello"
type response received earlier back to the server in the "protocolVersion" field.
Giving the "major" version of the requested protocol version will make the server
use the latest minor version of that protocol. Use this if you do not explicitly
need to depend on a specific minor version.
.sp
Protocol version 1.0 requires the following attributes to be set:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
"sourceDirectory" with a path to the sources
.IP \(bu 2
"buildDirectory" with a path to the build directory
.IP \(bu 2
"generator" with the generator name
.IP \(bu 2
"extraGenerator" (optional!) with the extra generator to be used
.IP \(bu 2
"platform" with the generator platform (if supported by the generator)
.IP \(bu 2
"toolset" with the generator toolset (if supported by the generator)
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Protocol version 1.2 makes all but the build directory optional, provided
there is a valid cache in the build directory that contains all the other
information already.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0},
"sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild",
"generator":"Ninja"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
which will result in a response type "reply":
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
indicating that the server is ready for action.
.SS Type "globalSettings"
.sp
This request can be sent after the initial handshake. It will return a
JSON structure with information on cmake state.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"type":"globalSettings"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
which will result in a response type "reply":
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{
"buildDirectory": "/tmp/test\-build",
"capabilities": {
"generators": [
{
"extraGenerators": [],
"name": "Watcom WMake",
"platformSupport": false,
"toolsetSupport": false
},
<...>
],
"serverMode": false,
"version": {
"isDirty": false,
"major": 3,
"minor": 6,
"patch": 20160830,
"string": "3.6.20160830\-gd6abad",
"suffix": "gd6abad"
}
},
"checkSystemVars": false,
"cookie": "",
"extraGenerator": "",
"generator": "Ninja",
"debugOutput": false,
"inReplyTo": "globalSettings",
"sourceDirectory": "/home/code/cmake",
"trace": false,
"traceExpand": false,
"type": "reply",
"warnUninitialized": false,
"warnUnused": false,
"warnUnusedCli": true
}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Type "setGlobalSettings"
.sp
This request can be sent to change the global settings attributes. Unknown
attributes are going to be ignored. Read\-only attributes reported by
"globalSettings" are all capabilities, buildDirectory, generator,
extraGenerator and sourceDirectory. Any attempt to set these will be ignored,
too.
.sp
All other settings will be changed.
.sp
The server will respond with an empty reply message or an error.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"type":"setGlobalSettings","debugOutput":true}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CMake will reply to this with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"inReplyTo":"setGlobalSettings","type":"reply"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Type "configure"
.sp
This request will configure a project for build.
.sp
To configure a build directory already containing cmake files, it is enough to
set "buildDirectory" via "setGlobalSettings". To create a fresh build directory
you also need to set "currentGenerator" and "sourceDirectory" via "setGlobalSettings"
in addition to "buildDirectory".
.sp
You may a list of strings to "configure" via the "cacheArguments" key. These
strings will be interpreted similar to command line arguments related to
cache handling that are passed to the cmake command line client.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"type":"configure", "cacheArguments":["\-Dsomething=else"]}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CMake will reply like this (after reporting progress for some time):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"cookie":"","inReplyTo":"configure","type":"reply"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Type "compute"
.sp
This request will generate build system files in the build directory and
is only available after a project was successfully "configure"d.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"type":"compute"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CMake will reply (after reporting progress information):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"cookie":"","inReplyTo":"compute","type":"reply"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Type "codemodel"
.sp
The "codemodel" request can be used after a project was "compute"d successfully.
.sp
It will list the complete project structure as it is known to cmake.
.sp
The reply will contain a key "configurations", which will contain a list of
configuration objects. Configuration objects are used to destinquish between
different configurations the build directory might have enabled. While most
generators only support one configuration, others might support several.
.sp
Each configuration object can have the following keys:
.INDENT 0.0
.TP
.B "name"
contains the name of the configuration. The name may be empty.
.TP
.B "projects"
contains a list of project objects, one for each build project.
.UNINDENT
.sp
Project objects define one (sub\-)project defined in the cmake build system.
.sp
Each project object can have the following keys:
.INDENT 0.0
.TP
.B "name"
contains the (sub\-)projects name.
.TP
.B "minimumCMakeVersion"
contains the minimum cmake version allowed for this project, null if the
project doesn\(aqt specify one.
.TP
.B "hasInstallRule"
true if the project contains any install rules, false otherwise.
.TP
.B "sourceDirectory"
contains the current source directory
.TP
.B "buildDirectory"
contains the current build directory.
.TP
.B "targets"
contains a list of build system target objects.
.UNINDENT
.sp
Target objects define individual build targets for a certain configuration.
.sp
Each target object can have the following keys:
.INDENT 0.0
.TP
.B "name"
contains the name of the target.
.TP
.B "type"
defines the type of build of the target. Possible values are
"STATIC_LIBRARY", "MODULE_LIBRARY", "SHARED_LIBRARY", "OBJECT_LIBRARY",
"EXECUTABLE", "UTILITY" and "INTERFACE_LIBRARY".
.TP
.B "fullName"
contains the full name of the build result (incl. extensions, etc.).
.TP
.B "sourceDirectory"
contains the current source directory.
.TP
.B "buildDirectory"
contains the current build directory.
.TP
.B "isGeneratorProvided"
true if the target is auto\-created by a generator, false otherwise
.TP
.B "hasInstallRule"
true if the target contains any install rules, false otherwise.
.TP
.B "installPaths"
full path to the destination directories defined by target install rules.
.TP
.B "artifacts"
with a list of build artifacts. The list is sorted with the most
important artifacts first (e.g. a .DLL file is listed before a
\&.PDB file on windows).
.TP
.B "linkerLanguage"
contains the language of the linker used to produce the artifact.
.TP
.B "linkLibraries"
with a list of libraries to link to. This value is encoded in the
system\(aqs native shell format.
.TP
.B "linkFlags"
with a list of flags to pass to the linker. This value is encoded in
the system\(aqs native shell format.
.TP
.B "linkLanguageFlags"
with the flags for a compiler using the linkerLanguage. This value is
encoded in the system\(aqs native shell format.
.TP
.B "frameworkPath"
with the framework path (on Apple computers). This value is encoded
in the system\(aqs native shell format.
.TP
.B "linkPath"
with the link path. This value is encoded in the system\(aqs native shell
format.
.TP
.B "sysroot"
with the sysroot path.
.TP
.B "fileGroups"
contains the source files making up the target.
.UNINDENT
.sp
FileGroups are used to group sources using similar settings together.
.sp
Each fileGroup object may contain the following keys:
.INDENT 0.0
.TP
.B "language"
contains the programming language used by all files in the group.
.TP
.B "compileFlags"
with a string containing all the flags passed to the compiler
when building any of the files in this group. This value is encoded in
the system\(aqs native shell format.
.TP
.B "includePath"
with a list of include paths. Each include path is an object
containing a "path" with the actual include path and "isSystem" with a bool
value informing whether this is a normal include or a system include. This
value is encoded in the system\(aqs native shell format.
.TP
.B "defines"
with a list of defines in the form "SOMEVALUE" or "SOMEVALUE=42". This
value is encoded in the system\(aqs native shell format.
.TP
.B "sources"
with a list of source files.
.UNINDENT
.sp
All file paths in the fileGroup are either absolute or relative to the
sourceDirectory of the target.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"type":"codemodel"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CMake will reply:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{
"configurations": [
{
"name": "",
"projects": [
{
"buildDirectory": "/tmp/build/Source/CursesDialog/form",
"name": "CMAKE_FORM",
"sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
"targets": [
{
"artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ],
"buildDirectory": "/tmp/build/Source/CursesDialog/form",
"fileGroups": [
{
"compileFlags": " \-std=gnu11",
"defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ],
"includePath": [ { "path": "/tmp/build/Utilities" }, <...> ],
"isGenerated": false,
"language": "C",
"sources": [ "fld_arg.c", <...> ]
}
],
"fullName": "libcmForm.a",
"linkerLanguage": "C",
"name": "cmForm",
"sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
"type": "STATIC_LIBRARY"
}
]
},
<...>
]
}
],
"cookie": "",
"inReplyTo": "codemodel",
"type": "reply"
}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Type "ctestInfo"
.sp
The "ctestInfo" request can be used after a project was "compute"d successfully.
.sp
It will list the complete project test structure as it is known to cmake.
.sp
The reply will contain a key "configurations", which will contain a list of
configuration objects. Configuration objects are used to destinquish between
different configurations the build directory might have enabled. While most
generators only support one configuration, others might support several.
.sp
Each configuration object can have the following keys:
.INDENT 0.0
.TP
.B "name"
contains the name of the configuration. The name may be empty.
.TP
.B "projects"
contains a list of project objects, one for each build project.
.UNINDENT
.sp
Project objects define one (sub\-)project defined in the cmake build system.
.sp
Each project object can have the following keys:
.INDENT 0.0
.TP
.B "name"
contains the (sub\-)projects name.
.TP
.B "ctestInfo"
contains a list of test objects.
.UNINDENT
.sp
Each test object can have the following keys:
.INDENT 0.0
.TP
.B "ctestName"
contains the name of the test.
.TP
.B "ctestCommand"
contains the test command.
.TP
.B "properties"
contains a list of test property objects.
.UNINDENT
.sp
Each test property object can have the following keys:
.INDENT 0.0
.TP
.B "key"
contains the test property key.
.TP
.B "value"
contains the test property value.
.UNINDENT
.SS Type "cmakeInputs"
.sp
The "cmakeInputs" requests will report files used by CMake as part
of the build system itself.
.sp
This request is only available after a project was successfully
"configure"d.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"type":"cmakeInputs"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CMake will reply with the following information:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"buildFiles":
[
{"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]},
{"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]},
{"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]}
],
"cmakeRootDirectory":"/usr/lib/cmake",
"sourceDirectory":"/home/code/src/cmake",
"cookie":"",
"inReplyTo":"cmakeInputs",
"type":"reply"
}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All file names are either relative to the top level source directory or
absolute.
.sp
The list of files which "isCMake" set to true are part of the cmake installation.
.sp
The list of files witch "isTemporary" set to true are part of the build directory
and will not survive the build directory getting cleaned out.
.SS Type "cache"
.sp
The "cache" request will list the cached configuration values.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"type":"cache"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CMake will respond with the following output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{
"cookie":"","inReplyTo":"cache","type":"reply",
"cache":
[
{
"key":"SOMEVALUE",
"properties":
{
"ADVANCED":"1",
"HELPSTRING":"This is not helpful"
}
"type":"STRING",
"value":"TEST"}
]
}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The output can be limited to a list of keys by passing an array of key names
to the "keys" optional field of the "cache" request.
.SS Type "fileSystemWatchers"
.sp
The server can watch the filesystem for changes. The "fileSystemWatchers"
command will report on the files and directories watched.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{"type":"fileSystemWatchers"}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CMake will respond with the following output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[== "CMake Server" ==[
{
"cookie":"","inReplyTo":"fileSystemWatchers","type":"reply",
"watchedFiles": [ "/absolute/path" ],
"watchedDirectories": [ "/absolute" ]
}
]== "CMake Server" ==]
.ft P
.fi
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

841
cmake/cmake-toolchains.7
View File

@ -1,841 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CMAKE-TOOLCHAINS" "7" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
cmake-toolchains \- CMake Toolchains Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH INTRODUCTION
.sp
CMake uses a toolchain of utilities to compile, link libraries and create
archives, and other tasks to drive the build. The toolchain utilities available
are determined by the languages enabled. In normal builds, CMake automatically
determines the toolchain for host builds based on system introspection and
defaults. In cross\-compiling scenarios, a toolchain file may be specified
with information about compiler and utility paths.
.SH LANGUAGES
.sp
Languages are enabled by the \fBproject()\fP command. Language\-specific
built\-in variables, such as
\fBCMAKE_CXX_COMPILER\fP,
\fBCMAKE_CXX_COMPILER_ID\fP etc are set by
invoking the \fBproject()\fP command. If no project command
is in the top\-level CMakeLists file, one will be implicitly generated. By default
the enabled languages are \fBC\fP and \fBCXX\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
project(C_Only C)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A special value of \fBNONE\fP can also be used with the \fBproject()\fP command
to enable no languages:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
project(MyProject NONE)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBenable_language()\fP command can be used to enable languages after the
\fBproject()\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
enable_language(CXX)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When a language is enabled, CMake finds a compiler for that language, and
determines some information, such as the vendor and version of the compiler,
the target architecture and bitwidth, the location of corresponding utilities
etc.
.sp
The \fBENABLED_LANGUAGES\fP global property contains the languages which
are currently enabled.
.SH VARIABLES AND PROPERTIES
.sp
Several variables relate to the language components of a toolchain which are
enabled. \fBCMAKE_<LANG>_COMPILER\fP is the full path to the compiler used
for \fB<LANG>\fP\&. \fBCMAKE_<LANG>_COMPILER_ID\fP is the identifier used
by CMake for the compiler and \fBCMAKE_<LANG>_COMPILER_VERSION\fP is the
version of the compiler.
.sp
The \fBCMAKE_<LANG>_FLAGS\fP variables and the configuration\-specific
equivalents contain flags that will be added to the compile command when
compiling a file of a particular language.
.sp
As the linker is invoked by the compiler driver, CMake needs a way to determine
which compiler to use to invoke the linker. This is calculated by the
\fBLANGUAGE\fP of source files in the target, and in the case of static
libraries, the language of the dependent libraries. The choice CMake makes may
be overridden with the \fBLINKER_LANGUAGE\fP target property.
.SH TOOLCHAIN FEATURES
.sp
CMake provides the \fBtry_compile()\fP command and wrapper macros such as
\fBCheckCXXSourceCompiles\fP, \fBCheckCXXSymbolExists\fP and
\fBCheckIncludeFile\fP to test capability and availability of various
toolchain features. These APIs test the toolchain in some way and cache the
result so that the test does not have to be performed again the next time
CMake runs.
.sp
Some toolchain features have built\-in handling in CMake, and do not require
compile\-tests. For example, \fBPOSITION_INDEPENDENT_CODE\fP allows
specifying that a target should be built as position\-independent code, if
the compiler supports that feature. The \fB<LANG>_VISIBILITY_PRESET\fP
and \fBVISIBILITY_INLINES_HIDDEN\fP target properties add flags for
hidden visibility, if supported by the compiler.
.SH CROSS COMPILING
.sp
If \fBcmake(1)\fP is invoked with the command line parameter
\fB\-DCMAKE_TOOLCHAIN_FILE=path/to/file\fP, the file will be loaded early to set
values for the compilers.
The \fBCMAKE_CROSSCOMPILING\fP variable is set to true when CMake is
cross\-compiling.
.sp
Note that using the \fBCMAKE_SOURCE_DIR\fP or \fBCMAKE_BINARY_DIR\fP
variables inside a toolchain file is typically undesirable. The toolchain
file is used in contexts where these variables have different values when used
in different places (e.g. as part of a call to \fBtry_compile()\fP). In most
cases, where there is a need to evaluate paths inside a toolchain file, the more
appropriate variable to use would be \fBCMAKE_CURRENT_LIST_DIR\fP, since
it always has an unambiguous, predictable value.
.SS Cross Compiling for Linux
.sp
A typical cross\-compiling toolchain for Linux has content such
as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)
set(CMAKE_SYSROOT /home/devel/rasp\-pi\-rootfs)
set(CMAKE_STAGING_PREFIX /home/devel/stage)
set(tools /home/devel/gcc\-4.7\-linaro\-rpi\-gnueabihf)
set(CMAKE_C_COMPILER ${tools}/bin/arm\-linux\-gnueabihf\-gcc)
set(CMAKE_CXX_COMPILER ${tools}/bin/arm\-linux\-gnueabihf\-g++)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBCMAKE_SYSTEM_NAME\fP is the CMake\-identifier of the target platform
to build for.
.sp
The \fBCMAKE_SYSTEM_PROCESSOR\fP is the CMake\-identifier of the target architecture
to build for.
.sp
The \fBCMAKE_SYSROOT\fP is optional, and may be specified if a sysroot
is available.
.sp
The \fBCMAKE_STAGING_PREFIX\fP is also optional. It may be used to specify
a path on the host to install to. The \fBCMAKE_INSTALL_PREFIX\fP is always
the runtime installation location, even when cross\-compiling.
.sp
The \fBCMAKE_<LANG>_COMPILER\fP variables may be set to full paths, or to
names of compilers to search for in standard locations. For toolchains that
do not support linking binaries without custom flags or scripts one may set
the \fBCMAKE_TRY_COMPILE_TARGET_TYPE\fP variable to \fBSTATIC_LIBRARY\fP
to tell CMake not to try to link executables during its checks.
.sp
CMake \fBfind_*\fP commands will look in the sysroot, and the \fBCMAKE_FIND_ROOT_PATH\fP
entries by default in all cases, as well as looking in the host system root prefix.
Although this can be controlled on a case\-by\-case basis, when cross\-compiling, it
can be useful to exclude looking in either the host or the target for particular
artifacts. Generally, includes, libraries and packages should be found in the
target system prefixes, whereas executables which must be run as part of the build
should be found only on the host and not on the target. This is the purpose of
the \fBCMAKE_FIND_ROOT_PATH_MODE_*\fP variables.
.SS Cross Compiling for the Cray Linux Environment
.sp
Cross compiling for compute nodes in the Cray Linux Environment can be done
without needing a separate toolchain file. Specifying
\fB\-DCMAKE_SYSTEM_NAME=CrayLinuxEnvironment\fP on the CMake command line will
ensure that the appropriate build settings and search paths are configured.
The platform will pull its configuration from the current environment
variables and will configure a project to use the compiler wrappers from the
Cray Programming Environment\(aqs \fBPrgEnv\-*\fP modules if present and loaded.
.sp
The default configuration of the Cray Programming Environment is to only
support static libraries. This can be overridden and shared libraries
enabled by setting the \fBCRAYPE_LINK_TYPE\fP environment variable to
\fBdynamic\fP\&.
.sp
Running CMake without specifying \fBCMAKE_SYSTEM_NAME\fP will
run the configure step in host mode assuming a standard Linux environment.
If not overridden, the \fBPrgEnv\-*\fP compiler wrappers will end up getting used,
which if targeting the either the login node or compute node, is likely not the
desired behavior. The exception to this would be if you are building directly
on a NID instead of cross\-compiling from a login node. If trying to build
software for a login node, you will need to either first unload the
currently loaded \fBPrgEnv\-*\fP module or explicitly tell CMake to use the
system compilers in \fB/usr/bin\fP instead of the Cray wrappers. If instead
targeting a compute node is desired, just specify the
\fBCMAKE_SYSTEM_NAME\fP as mentioned above.
.SS Cross Compiling using Clang
.sp
Some compilers such as Clang are inherently cross compilers.
The \fBCMAKE_<LANG>_COMPILER_TARGET\fP can be set to pass a
value to those supported compilers when compiling:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)
set(triple arm\-linux\-gnueabihf)
set(CMAKE_C_COMPILER clang)
set(CMAKE_C_COMPILER_TARGET ${triple})
set(CMAKE_CXX_COMPILER clang++)
set(CMAKE_CXX_COMPILER_TARGET ${triple})
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Similarly, some compilers do not ship their own supplementary utilities
such as linkers, but provide a way to specify the location of the external
toolchain which will be used by the compiler driver. The
\fBCMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN\fP variable can be set in a
toolchain file to pass the path to the compiler driver.
.SS Cross Compiling for QNX
.sp
As the Clang compiler the QNX QCC compile is inherently a cross compiler.
And the \fBCMAKE_<LANG>_COMPILER_TARGET\fP can be set to pass a
value to those supported compilers when compiling:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(CMAKE_SYSTEM_NAME QNX)
set(arch gcc_ntoarmv7le)
set(CMAKE_C_COMPILER qcc)
set(CMAKE_C_COMPILER_TARGET ${arch})
set(CMAKE_CXX_COMPILER QCC)
set(CMAKE_CXX_COMPILER_TARGET ${arch})
set(CMAKE_SYSROOT $ENV{QNX_TARGET})
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Cross Compiling for Windows CE
.sp
Cross compiling for Windows CE requires the corresponding SDK being
installed on your system. These SDKs are usually installed under
\fBC:/Program Files (x86)/Windows CE Tools/SDKs\fP\&.
.sp
A toolchain file to configure a Visual Studio generator for
Windows CE may look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(CMAKE_SYSTEM_NAME WindowsCE)
set(CMAKE_SYSTEM_VERSION 8.0)
set(CMAKE_SYSTEM_PROCESSOR arm)
set(CMAKE_GENERATOR_TOOLSET CE800) # Can be omitted for 8.0
set(CMAKE_GENERATOR_PLATFORM SDK_AM335X_SK_WEC2013_V310)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBCMAKE_GENERATOR_PLATFORM\fP tells the generator which SDK to use.
Further \fBCMAKE_SYSTEM_VERSION\fP tells the generator what version of
Windows CE to use. Currently version 8.0 (Windows Embedded Compact 2013) is
supported out of the box. Other versions may require one to set
\fBCMAKE_GENERATOR_TOOLSET\fP to the correct value.
.SS Cross Compiling for Windows 10 Universal Applications
.sp
A toolchain file to configure a Visual Studio generator for a
Windows 10 Universal Application may look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(CMAKE_SYSTEM_NAME WindowsStore)
set(CMAKE_SYSTEM_VERSION 10.0)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A Windows 10 Universal Application targets both Windows Store and
Windows Phone. Specify the \fBCMAKE_SYSTEM_VERSION\fP variable
to be \fB10.0\fP to build with the latest available Windows 10 SDK.
Specify a more specific version (e.g. \fB10.0.10240.0\fP for RTM)
to build with the corresponding SDK.
.SS Cross Compiling for Windows Phone
.sp
A toolchain file to configure a Visual Studio generator for
Windows Phone may look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(CMAKE_SYSTEM_NAME WindowsPhone)
set(CMAKE_SYSTEM_VERSION 8.1)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Cross Compiling for Windows Store
.sp
A toolchain file to configure a Visual Studio generator for
Windows Store may look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(CMAKE_SYSTEM_NAME WindowsStore)
set(CMAKE_SYSTEM_VERSION 8.1)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Cross Compiling for Android
.sp
A toolchain file may configure cross\-compiling for Android by setting the
\fBCMAKE_SYSTEM_NAME\fP variable to \fBAndroid\fP\&. Further configuration
is specific to the Android development environment to be used.
.sp
For Visual Studio Generators, CMake expects \fI\%NVIDIA Nsight Tegra
Visual Studio Edition\fP to be installed. See that section for further
configuration details.
.sp
For Makefile Generators and the \fBNinja\fP generator,
CMake expects one of these environments:
.INDENT 0.0
.IP \(bu 2
\fI\%NDK\fP
.IP \(bu 2
\fI\%Standalone Toolchain\fP
.UNINDENT
.sp
CMake uses the following steps to select one of the environments:
.INDENT 0.0
.IP \(bu 2
If the \fBCMAKE_ANDROID_NDK\fP variable is set, the NDK at the
specified location will be used.
.IP \(bu 2
Else, if the \fBCMAKE_ANDROID_STANDALONE_TOOLCHAIN\fP variable
is set, the Standalone Toolchain at the specified location will be used.
.IP \(bu 2
Else, if the \fBCMAKE_SYSROOT\fP variable is set to a directory
of the form \fB<ndk>/platforms/android\-<api>/arch\-<arch>\fP, the \fB<ndk>\fP
part will be used as the value of \fBCMAKE_ANDROID_NDK\fP and the
NDK will be used.
.IP \(bu 2
Else, if the \fBCMAKE_SYSROOT\fP variable is set to a directory of the
form \fB<standalone\-toolchain>/sysroot\fP, the \fB<standalone\-toolchain>\fP part
will be used as the value of \fBCMAKE_ANDROID_STANDALONE_TOOLCHAIN\fP
and the Standalone Toolchain will be used.
.IP \(bu 2
Else, if a cmake variable \fBANDROID_NDK\fP is set it will be used
as the value of \fBCMAKE_ANDROID_NDK\fP, and the NDK will be used.
.IP \(bu 2
Else, if a cmake variable \fBANDROID_STANDALONE_TOOLCHAIN\fP is set, it will be
used as the value of \fBCMAKE_ANDROID_STANDALONE_TOOLCHAIN\fP, and the
Standalone Toolchain will be used.
.IP \(bu 2
Else, if an environment variable \fBANDROID_NDK_ROOT\fP or
\fBANDROID_NDK\fP is set, it will be used as the value of
\fBCMAKE_ANDROID_NDK\fP, and the NDK will be used.
.IP \(bu 2
Else, if an environment variable \fBANDROID_STANDALONE_TOOLCHAIN\fP is
set then it will be used as the value of
\fBCMAKE_ANDROID_STANDALONE_TOOLCHAIN\fP, and the Standalone
Toolchain will be used.
.IP \(bu 2
Else, an error diagnostic will be issued that neither the NDK or
Standalone Toolchain can be found.
.UNINDENT
.SS Cross Compiling for Android with the NDK
.sp
A toolchain file may configure Makefile Generators or the
\fBNinja\fP generator to target Android for cross\-compiling.
.sp
Configure use of an Android NDK with the following variables:
.INDENT 0.0
.TP
.B \fBCMAKE_SYSTEM_NAME\fP
Set to \fBAndroid\fP\&. Must be specified to enable cross compiling
for Android.
.TP
.B \fBCMAKE_SYSTEM_VERSION\fP
Set to the Android API level. If not specified, the value is
determined as follows:
.INDENT 7.0
.IP \(bu 2
If the \fBCMAKE_ANDROID_API\fP variable is set, its value
is used as the API level.
.IP \(bu 2
If the \fBCMAKE_SYSROOT\fP variable is set, the API level is
detected from the NDK directory structure containing the sysroot.
.IP \(bu 2
Otherwise, the latest API level available in the NDK is used.
.UNINDENT
.TP
.B \fBCMAKE_ANDROID_ARCH_ABI\fP
Set to the Android ABI (architecture). If not specified, this
variable will default to \fBarmeabi\fP\&.
The \fBCMAKE_ANDROID_ARCH\fP variable will be computed
from \fBCMAKE_ANDROID_ARCH_ABI\fP automatically.
Also see the \fBCMAKE_ANDROID_ARM_MODE\fP and
\fBCMAKE_ANDROID_ARM_NEON\fP variables.
.TP
.B \fBCMAKE_ANDROID_NDK\fP
Set to the absolute path to the Android NDK root directory.
A \fB${CMAKE_ANDROID_NDK}/platforms\fP directory must exist.
If not specified, a default for this variable will be chosen
as specified \fI\%above\fP\&.
.TP
.B \fBCMAKE_ANDROID_NDK_DEPRECATED_HEADERS\fP
Set to a true value to use the deprecated per\-api\-level headers
instead of the unified headers. If not specified, the default will
be false unless using a NDK that does not provide unified headers.
.TP
.B \fBCMAKE_ANDROID_NDK_TOOLCHAIN_VERSION\fP
On NDK r19 or above, this variable must be unset or set to \fBclang\fP\&.
On NDK r18 or below, set this to the version of the NDK toolchain to
be selected as the compiler. If not specified, the default will be
the latest available GCC toolchain.
.TP
.B \fBCMAKE_ANDROID_STL_TYPE\fP
Set to specify which C++ standard library to use. If not specified,
a default will be selected as described in the variable documentation.
.UNINDENT
.sp
The following variables will be computed and provided automatically:
.INDENT 0.0
.TP
.B \fBCMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX\fP
The absolute path prefix to the binutils in the NDK toolchain.
.TP
.B \fBCMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX\fP
The host platform suffix of the binutils in the NDK toolchain.
.UNINDENT
.sp
For example, a toolchain file might contain:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(CMAKE_SYSTEM_NAME Android)
set(CMAKE_SYSTEM_VERSION 21) # API level
set(CMAKE_ANDROID_ARCH_ABI arm64\-v8a)
set(CMAKE_ANDROID_NDK /path/to/android\-ndk)
set(CMAKE_ANDROID_STL_TYPE gnustl_static)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively one may specify the values without a toolchain file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cmake ../src \e
\-DCMAKE_SYSTEM_NAME=Android \e
\-DCMAKE_SYSTEM_VERSION=21 \e
\-DCMAKE_ANDROID_ARCH_ABI=arm64\-v8a \e
\-DCMAKE_ANDROID_NDK=/path/to/android\-ndk \e
\-DCMAKE_ANDROID_STL_TYPE=gnustl_static
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Cross Compiling for Android with a Standalone Toolchain
.sp
A toolchain file may configure Makefile Generators or the
\fBNinja\fP generator to target Android for cross\-compiling
using a standalone toolchain.
.sp
Configure use of an Android standalone toolchain with the following variables:
.INDENT 0.0
.TP
.B \fBCMAKE_SYSTEM_NAME\fP
Set to \fBAndroid\fP\&. Must be specified to enable cross compiling
for Android.
.TP
.B \fBCMAKE_ANDROID_STANDALONE_TOOLCHAIN\fP
Set to the absolute path to the standalone toolchain root directory.
A \fB${CMAKE_ANDROID_STANDALONE_TOOLCHAIN}/sysroot\fP directory
must exist.
If not specified, a default for this variable will be chosen
as specified \fI\%above\fP\&.
.TP
.B \fBCMAKE_ANDROID_ARM_MODE\fP
When the standalone toolchain targets ARM, optionally set this to \fBON\fP
to target 32\-bit ARM instead of 16\-bit Thumb.
See variable documentation for details.
.TP
.B \fBCMAKE_ANDROID_ARM_NEON\fP
When the standalone toolchain targets ARM v7, optionally set thisto \fBON\fP
to target ARM NEON devices. See variable documentation for details.
.UNINDENT
.sp
The following variables will be computed and provided automatically:
.INDENT 0.0
.TP
.B \fBCMAKE_SYSTEM_VERSION\fP
The Android API level detected from the standalone toolchain.
.TP
.B \fBCMAKE_ANDROID_ARCH_ABI\fP
The Android ABI detected from the standalone toolchain.
.TP
.B \fBCMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX\fP
The absolute path prefix to the \fBbinutils\fP in the standalone toolchain.
.TP
.B \fBCMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX\fP
The host platform suffix of the \fBbinutils\fP in the standalone toolchain.
.UNINDENT
.sp
For example, a toolchain file might contain:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(CMAKE_SYSTEM_NAME Android)
set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android\-toolchain)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively one may specify the values without a toolchain file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cmake ../src \e
\-DCMAKE_SYSTEM_NAME=Android \e
\-DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android\-toolchain
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition
.sp
A toolchain file to configure one of the Visual Studio Generators
to build using NVIDIA Nsight Tegra targeting Android may look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(CMAKE_SYSTEM_NAME Android)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBCMAKE_GENERATOR_TOOLSET\fP may be set to select
the Nsight Tegra "Toolchain Version" value.
.sp
See also target properties:
.INDENT 0.0
.IP \(bu 2
\fBANDROID_ANT_ADDITIONAL_OPTIONS\fP
.IP \(bu 2
\fBANDROID_API_MIN\fP
.IP \(bu 2
\fBANDROID_API\fP
.IP \(bu 2
\fBANDROID_ARCH\fP
.IP \(bu 2
\fBANDROID_ASSETS_DIRECTORIES\fP
.IP \(bu 2
\fBANDROID_GUI\fP
.IP \(bu 2
\fBANDROID_JAR_DEPENDENCIES\fP
.IP \(bu 2
\fBANDROID_JAR_DIRECTORIES\fP
.IP \(bu 2
\fBANDROID_JAVA_SOURCE_DIR\fP
.IP \(bu 2
\fBANDROID_NATIVE_LIB_DEPENDENCIES\fP
.IP \(bu 2
\fBANDROID_NATIVE_LIB_DIRECTORIES\fP
.IP \(bu 2
\fBANDROID_PROCESS_MAX\fP
.IP \(bu 2
\fBANDROID_PROGUARD_CONFIG_PATH\fP
.IP \(bu 2
\fBANDROID_PROGUARD\fP
.IP \(bu 2
\fBANDROID_SECURE_PROPS_PATH\fP
.IP \(bu 2
\fBANDROID_SKIP_ANT_STEP\fP
.IP \(bu 2
\fBANDROID_STL_TYPE\fP
.UNINDENT
.SS Cross Compiling for iOS, tvOS, or watchOS
.sp
For cross\-compiling to iOS, tvOS, or watchOS, the \fBXcode\fP
generator is recommended. The \fBUnix Makefiles\fP or
\fBNinja\fP generators can also be used, but they require the
project to handle more areas like target CPU selection and code signing.
.sp
Any of the three systems can be targeted by setting the
\fBCMAKE_SYSTEM_NAME\fP variable to a value from the table below.
By default, the latest Device SDK is chosen. As for all Apple platforms,
a different SDK (e.g. a simulator) can be selected by setting the
\fBCMAKE_OSX_SYSROOT\fP variable, although this should rarely be
necessary (see \fI\%Switching Between Device and Simulator\fP below).
A list of available SDKs can be obtained by running \fBxcodebuild \-showsdks\fP\&.
.TS
center;
|l|l|l|l|.
_
T{
OS
T} T{
CMAKE_SYSTEM_NAME
T} T{
Device SDK (default)
T} T{
Simulator SDK
T}
_
T{
iOS
T} T{
iOS
T} T{
iphoneos
T} T{
iphonesimulator
T}
_
T{
tvOS
T} T{
tvOS
T} T{
appletvos
T} T{
appletvsimulator
T}
_
T{
watchOS
T} T{
watchOS
T} T{
watchos
T} T{
watchsimulator
T}
_
.TE
.sp
For example, to create a CMake configuration for iOS, the following
command is sufficient:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmake .. \-GXcode \-DCMAKE_SYSTEM_NAME=iOS
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Variable \fBCMAKE_OSX_ARCHITECTURES\fP can be used to set architectures
for both device and simulator. Variable \fBCMAKE_OSX_DEPLOYMENT_TARGET\fP
can be used to set an iOS/tvOS/watchOS deployment target.
.sp
Next configuration will install fat 5 architectures iOS library
and add the \fB\-miphoneos\-version\-min=9.3\fP/\fB\-mios\-simulator\-version\-min=9.3\fP
flags to the compiler:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cmake \-S. \-B_builds \-GXcode \e
\-DCMAKE_SYSTEM_NAME=iOS \e
"\-DCMAKE_OSX_ARCHITECTURES=armv7;armv7s;arm64;i386;x86_64" \e
\-DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \e
\-DCMAKE_INSTALL_PREFIX=\(gapwd\(ga/_install \e
\-DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO \e
\-DCMAKE_IOS_INSTALL_COMBINED=YES
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# CMakeLists.txt
cmake_minimum_required(VERSION 3.14)
project(foo)
add_library(foo foo.cpp)
install(TARGETS foo DESTINATION lib)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Install:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cmake \-\-build _builds \-\-config Release \-\-target install
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Check library:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lipo \-info _install/lib/libfoo.a
Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ otool \-l _install/lib/libfoo.a | grep \-A2 LC_VERSION_MIN_IPHONEOS
cmd LC_VERSION_MIN_IPHONEOS
cmdsize 16
version 9.3
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Code Signing
.sp
Some build artifacts for the embedded Apple platforms require mandatory
code signing. If the \fBXcode\fP generator is being used and
code signing is required or desired, the development team ID can be
specified via the \fBCMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM\fP CMake variable.
This team ID will then be included in the generated Xcode project.
By default, CMake avoids the need for code signing during the internal
configuration phase (i.e compiler ID and feature detection).
.SS Switching Between Device and Simulator
.sp
When configuring for any of the embedded platforms, one can target either
real devices or the simulator. Both have their own separate SDK, but CMake
only supports specifying a single SDK for the configuration phase. This
means the developer must select one or the other at configuration time.
When using the \fBXcode\fP generator, this is less of a limitation
because Xcode still allows you to build for either a device or a simulator,
even though configuration was only performed for one of the two. From
within the Xcode IDE, builds are performed for the selected "destination"
platform. When building from the command line, the desired sdk can be
specified directly by passing a \fB\-sdk\fP option to the underlying build
tool (\fBxcodebuild\fP). For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cmake \-\-build ... \-\- \-sdk iphonesimulator
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Please note that checks made during configuration were performed against
the configure\-time SDK and might not hold true for other SDKs. Commands
like \fBfind_package()\fP, \fBfind_library()\fP, etc. store and use
details only for the configured SDK/platform, so they can be problematic
if wanting to switch between device and simulator builds. You can follow
the next rules to make device + simulator configuration work:
.INDENT 0.0
.IP \(bu 2
Use explicit \fB\-l\fP linker flag,
e.g. \fBtarget_link_libraries(foo PUBLIC "\-lz")\fP
.IP \(bu 2
Use explicit \fB\-framework\fP linker flag,
e.g. \fBtarget_link_libraries(foo PUBLIC "\-framework CoreFoundation")\fP
.IP \(bu 2
Use \fBfind_package()\fP only for libraries installed with
\fBCMAKE_IOS_INSTALL_COMBINED\fP feature
.UNINDENT
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

6513
cmake/cmake-variables.7
View File

File diff suppressed because it is too large Load Diff

1251
cmake/cmake.1
View File

File diff suppressed because it is too large Load Diff

4500
cmake/cpack-generators.7
View File

File diff suppressed because it is too large Load Diff

297
cmake/cpack.1
View File

@ -1,297 +0,0 @@
.\" Man page generated from reStructuredText.
.
.TH "CPACK" "1" "Apr 27, 2020" "3.17.1" "CMake"
.SH NAME
cpack \- CPack Command-Line Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cpack [<options>]
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
The \fBcpack\fP executable is the CMake packaging program. It generates
installers and source packages in a variety of formats.
.sp
For each installer or package format, \fBcpack\fP has a specific backend,
called "generator". A generator is responsible for generating the required
inputs and invoking the specific package creation tools. These installer
or package generators are not to be confused with the makefile generators
of the \fBcmake\fP command.
.sp
All supported generators are specified in the \fBcpack\-generators\fP manual. The command \fBcpack \-\-help\fP prints a
list of generators supported for the target platform. Which of them are
to be used can be selected through the \fBCPACK_GENERATOR\fP variable
or through the command\-line option \fB\-G\fP\&.
.sp
The \fBcpack\fP program is steered by a configuration file written in the
\fBCMake language\fP\&. Unless chosen differently
through the command\-line option \fB\-\-config\fP, the file \fBCPackConfig.cmake\fP
in the current directory is used.
.sp
In the standard CMake workflow, the file \fBCPackConfig.cmake\fP is generated
by the \fBcmake\fP executable, provided the \fBCPack\fP
module is included by the project\(aqs \fBCMakeLists.txt\fP file.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-G <generators>\fP
\fB<generators>\fP is a semicolon\-separated list
of generator names. \fBcpack\fP will iterate through this list and produce
package(s) in that generator\(aqs format according to the details provided in
the \fBCPackConfig.cmake\fP configuration file. If this option is not given,
the \fBCPACK_GENERATOR\fP variable determines the default set of
generators that will be used.
.TP
.B \fB\-C <configs>\fP
Specify the project configuration(s) to be packaged (e.g. \fBDebug\fP,
\fBRelease\fP, etc.), where \fB<configs>\fP is a
semicolon\-separated list\&.
When the CMake project uses a multi\-configuration
generator such as Xcode or Visual Studio, this option is needed to tell
\fBcpack\fP which built executables to include in the package.
The user is responsible for ensuring that the configuration(s) listed
have already been built before invoking \fBcpack\fP\&.
.TP
.B \fB\-D <var>=<value>\fP
Set a CPack variable. This will override any value set for \fB<var>\fP in the
input file read by \fBcpack\fP\&.
.TP
.B \fB\-\-config <configFile>\fP
Specify the configuration file read by \fBcpack\fP to provide the packaging
details. By default, \fBCPackConfig.cmake\fP in the current directory will
be used.
.TP
.B \fB\-\-verbose, \-V\fP
Run \fBcpack\fP with verbose output. This can be used to show more details
from the package generation tools and is suitable for project developers.
.TP
.B \fB\-\-debug\fP
Run \fBcpack\fP with debug output. This option is intended mainly for the
developers of \fBcpack\fP itself and is not normally needed by project
developers.
.TP
.B \fB\-\-trace\fP
Put the underlying cmake scripts in trace mode.
.TP
.B \fB\-\-trace\-expand\fP
Put the underlying cmake scripts in expanded trace mode.
.TP
.B \fB\-P <packageName>\fP
Override/define the value of the \fBCPACK_PACKAGE_NAME\fP variable used
for packaging. Any value set for this variable in the \fBCPackConfig.cmake\fP
file will then be ignored.
.TP
.B \fB\-R <packageVersion>\fP
Override/define the value of the \fBCPACK_PACKAGE_VERSION\fP
variable used for packaging. It will override a value set in the
\fBCPackConfig.cmake\fP file or one automatically computed from
\fBCPACK_PACKAGE_VERSION_MAJOR\fP,
\fBCPACK_PACKAGE_VERSION_MINOR\fP and
\fBCPACK_PACKAGE_VERSION_PATCH\fP\&.
.TP
.B \fB\-B <packageDirectory>\fP
Override/define \fBCPACK_PACKAGE_DIRECTORY\fP, which controls the
directory where CPack will perform its packaging work. The resultant
package(s) will be created at this location by default and a
\fB_CPack_Packages\fP subdirectory will also be created below this directory to
use as a working area during package creation.
.TP
.B \fB\-\-vendor <vendorName>\fP
Override/define \fBCPACK_PACKAGE_VENDOR\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-\-help,\-help,\-usage,\-h,\-H,/?\fP
Print usage information and exit.
.sp
Usage describes the basic command line interface and its options.
.TP
.B \fB\-\-version,\-version,/V [<f>]\fP
Show program name/version banner and exit.
.sp
If a file is specified, the version is written into it.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-full [<f>]\fP
Print all help manuals and exit.
.sp
All manuals are printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-manual <man> [<f>]\fP
Print one help manual and exit.
.sp
The specified manual is printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-manual\-list [<f>]\fP
List help manuals available and exit.
.sp
The list contains all manuals for which help may be obtained by
using the \fB\-\-help\-manual\fP option followed by a manual name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-command <cmd> [<f>]\fP
Print help for one command and exit.
.sp
The \fBcmake\-commands(7)\fP manual entry for \fB<cmd>\fP is
printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-command\-list [<f>]\fP
List commands with help available and exit.
.sp
The list contains all commands for which help may be obtained by
using the \fB\-\-help\-command\fP option followed by a command name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-commands [<f>]\fP
Print cmake\-commands manual and exit.
.sp
The \fBcmake\-commands(7)\fP manual is printed in a
human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-module <mod> [<f>]\fP
Print help for one module and exit.
.sp
The \fBcmake\-modules(7)\fP manual entry for \fB<mod>\fP is printed
in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-module\-list [<f>]\fP
List modules with help available and exit.
.sp
The list contains all modules for which help may be obtained by
using the \fB\-\-help\-module\fP option followed by a module name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-modules [<f>]\fP
Print cmake\-modules manual and exit.
.sp
The \fBcmake\-modules(7)\fP manual is printed in a human\-readable
text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-policy <cmp> [<f>]\fP
Print help for one policy and exit.
.sp
The \fBcmake\-policies(7)\fP manual entry for \fB<cmp>\fP is
printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-policy\-list [<f>]\fP
List policies with help available and exit.
.sp
The list contains all policies for which help may be obtained by
using the \fB\-\-help\-policy\fP option followed by a policy name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-policies [<f>]\fP
Print cmake\-policies manual and exit.
.sp
The \fBcmake\-policies(7)\fP manual is printed in a
human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-property <prop> [<f>]\fP
Print help for one property and exit.
.sp
The \fBcmake\-properties(7)\fP manual entries for \fB<prop>\fP are
printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-property\-list [<f>]\fP
List properties with help available and exit.
.sp
The list contains all properties for which help may be obtained by
using the \fB\-\-help\-property\fP option followed by a property name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-properties [<f>]\fP
Print cmake\-properties manual and exit.
.sp
The \fBcmake\-properties(7)\fP manual is printed in a
human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-variable <var> [<f>]\fP
Print help for one variable and exit.
.sp
The \fBcmake\-variables(7)\fP manual entry for \fB<var>\fP is
printed in a human\-readable text format.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-variable\-list [<f>]\fP
List variables with help available and exit.
.sp
The list contains all variables for which help may be obtained by
using the \fB\-\-help\-variable\fP option followed by a variable name.
The help is printed to a named <f>ile if given.
.TP
.B \fB\-\-help\-variables [<f>]\fP
Print cmake\-variables manual and exit.
.sp
The \fBcmake\-variables(7)\fP manual is printed in a
human\-readable text format.
The help is printed to a named <f>ile if given.
.UNINDENT
.SH SEE ALSO
.sp
The following resources are available to get help using CMake:
.INDENT 0.0
.TP
.B Home Page
\fI\%https://cmake.org\fP
.sp
The primary starting point for learning about CMake.
.TP
.B Online Documentation and Community Resources
\fI\%https://cmake.org/documentation\fP
.sp
Links to available documentation and community resources may be
found on this web page.
.TP
.B Discourse Forum
\fI\%https://discourse.cmake.org\fP
.sp
The Discourse Forum hosts discussion and questions about CMake.
.UNINDENT
.SH COPYRIGHT
2000-2020 Kitware, Inc. and Contributors
.\" Generated by docutils manpage writer.
.

2074
cmake/ctest.1
View File

File diff suppressed because it is too large Load Diff