Lubuntu/cmake
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated version 3.9.0 from 'upstream/3.9.0'

Browse Source 
with Debian dir 58a76f23b0e8bb8bae4fdd4ee03e46facf573cc7
This commit is contained in:
Felix Geyer 2017-07-20 19:36:12 +02:00
commit b8719a1807
2058 changed files with 47958 additions and 24619 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
.clang-tidy Normal file
View File

@ -0,0 +1,30 @@
---
Checks: "-*,\
misc-*,\
-misc-incorrect-roundings,\
-misc-macro-parentheses,\
-misc-misplaced-widening-cast,\
-misc-static-assert,\
modernize-make-shared,\
modernize-make-unique,\
modernize-redundant-void-arg,\
modernize-use-bool-literals,\
modernize-use-nullptr,\
modernize-use-override,\
performance-*,\
-performance-inefficient-string-concatenation,\
readability-*,\
-readability-function-size,\
-readability-identifier-naming,\
-readability-implicit-bool-cast,\
-readability-inconsistent-declaration-parameter-name,\
-readability-named-parameter,\
-readability-redundant-declaration,\
-readability-redundant-member-init,\
-readability-simplify-boolean-expr,\
"
HeaderFilterRegex: 'Source/cm[^/]*\.(h|hxx|cxx)$'
CheckOptions:
- key: modernize-use-nullptr.NullMacros
value: 'CM_NULLPTR'
...

4
Auxiliary/cmake.m4
View File

@ -24,10 +24,10 @@ AC_ARG_VAR([$1][_LIBS], [linker flags for $1. This overrides the cmake output])d
failed=false
AC_MSG_CHECKING([for $1])
if test -n "$1[]_$2[]FLAGS"; then
if test -z "${$1[]_$2[]FLAGS}"; then
$1[]_$2[]FLAGS=`$CMAKE_BINARY --find-package "-DNAME=$1" "-DCOMPILER_ID=m4_default([$3], [GNU])" "-DLANGUAGE=$2" -DMODE=COMPILE $4` || failed=true
fi
if test -n "$1[]_LIBS"; then
if test -z "${$1[]_LIBS}"; then
$1[]_LIBS=`$CMAKE_BINARY --find-package "-DNAME=$1" "-DCOMPILER_ID=m4_default([$3], [GNU])" "-DLANGUAGE=$2" -DMODE=LINK $4` || failed=true
fi

48
Auxiliary/vim/cmake.vim.in
View File

File diff suppressed because one or more lines are too long

27
Auxiliary/vim/extract-upper-case.pl
View File

@ -3,6 +3,9 @@
use strict;
use warnings;
#my $cmake = "/home/pboettch/devel/upstream/cmake/build/bin/cmake";
my $cmake = "cmake";
my @variables;
my @commands;
my @properties;
@ -10,7 +13,7 @@ my @modules;
my %keywords; # command => keyword-list
# unwanted upper-cases
my %unwanted = map { $_ => 1 } qw(VS CXX IDE NOTFOUND NO_ DFOO DBAR);
my %unwanted = map { $_ => 1 } qw(VS CXX IDE NOTFOUND NO_ DFOO DBAR NEW);
# cannot remove ALL - exists for add_custom_command
# control-statements
@ -24,9 +27,10 @@ my %deprecated = map { $_ => 1 } qw(build_name exec_program export_library_depen
push @modules, "ExternalProject";
# variables
open(CMAKE, "cmake --help-variable-list|") or die "could not run cmake";
open(CMAKE, "$cmake --help-variable-list|") or die "could not run cmake";
while (<CMAKE>) {
chomp;
next if /\</; # skip VARIABLES which contained <>-"templates"
push @variables, $_;
}
close(CMAKE);
@ -35,17 +39,16 @@ close(CMAKE);
my %variables = map { $_ => 1 } @variables;
# commands
open(CMAKE, "cmake --help-command-list|");
open(CMAKE, "$cmake --help-command-list|");
while (my $cmd = <CMAKE>) {
chomp $cmd;
push @commands, $cmd;
}
close(CMAKE);
# now generate a keyword-list per command
foreach my $cmd (@commands) {
my @word = extract_upper("cmake --help-command $cmd|");
my @word = extract_upper("$cmake --help-command $cmd|");
next if scalar @word == 0;
@ -54,7 +57,7 @@ foreach my $cmd (@commands) {
# and now for modules
foreach my $mod (@modules) {
my @word = extract_upper("cmake --help-module $mod|");
my @word = extract_upper("$cmake --help-module $mod|");
next if scalar @word == 0;
@ -62,10 +65,10 @@ foreach my $mod (@modules) {
}
# and now for generator-expressions
my @generator_expr = extract_upper("cmake --help-manual cmake-generator-expressions |");
my @generator_expr = extract_upper("$cmake --help-manual cmake-generator-expressions |");
# properties
open(CMAKE, "cmake --help-property-list|");
open(CMAKE, "$cmake --help-property-list|");
while (<CMAKE>) {
chomp;
push @properties, $_;
@ -88,7 +91,7 @@ while(<IN>)
! exists $deprecated{$_} } @commands;
print OUT " " x 12 , "\\ ", join(" ", @tmp), "\n";
} elsif ($1 eq "VARIABLE_LIST") {
print OUT " " x 12 , "\\ ", join(" ", @variables), "\n";
print OUT " " x 12 , "\\ ", join(" ", sort keys %variables), "\n";
} elsif ($1 eq "MODULES") {
print OUT " " x 12 , "\\ ", join("\n", @modules), "\n";
} elsif ($1 eq "GENERATOR_EXPRESSIONS") {
@ -101,9 +104,8 @@ while(<IN>)
print OUT " " x 12 , "\\ ", join(" ", sort keys %deprecated), "\n";
} elsif ($1 eq "KEYWORDS") {
foreach my $k (sort keys %keywords) {
print OUT "syn keyword cmakeKW$k\n";
print OUT "syn keyword cmakeKW$k contained\n";
print OUT " " x 12, "\\ ", join(" ", @{$keywords{$k}}), "\n";
print OUT " " x 12, "\\ contained\n";
print OUT "\n";
push @keyword_hi, "hi def link cmakeKW$k ModeMsg";
}
@ -130,7 +132,8 @@ sub extract_upper
foreach my $w (m/\b([A-Z_]{2,})\b/g) {
next
if exists $variables{$w} or # skip if it is a variable
exists $unwanted{$w}; # skip if not wanted
exists $unwanted{$w} or # skip if not wanted
grep(/$w/, @word); # skip if already in array
push @word, $w;
}

1
Auxiliary/vim/indent/cmake.vim
View File

@ -14,6 +14,7 @@ if exists("b:did_indent")
endif
let b:did_indent = 1
setlocal et
setlocal indentexpr=CMakeGetIndent(v:lnum)
setlocal indentkeys+==ENDIF(,ENDFOREACH(,ENDMACRO(,ELSE(,ELSEIF(,ENDWHILE(

411
Auxiliary/vim/syntax/cmake.vim
View File

File diff suppressed because one or more lines are too long

78
CMakeLists.txt
View File

@ -55,14 +55,22 @@ if(NOT DEFINED CMAKE_C_STANDARD AND NOT CMake_NO_C_STANDARD)
endif()
endif()
if(NOT DEFINED CMAKE_CXX_STANDARD AND NOT CMake_NO_CXX_STANDARD)
include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx14_cstdio.cmake)
if(NOT CMake_CXX14_CSTDIO_BROKEN)
set(CMAKE_CXX_STANDARD 14)
if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.14)
set(CMAKE_CXX_STANDARD 98)
else()
set(CMAKE_CXX_STANDARD 11)
include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx14_cstdio.cmake)
if(NOT CMake_CXX14_CSTDIO_BROKEN)
set(CMAKE_CXX_STANDARD 14)
else()
set(CMAKE_CXX_STANDARD 11)
endif()
endif()
endif()
if(NOT CMake_TEST_EXTERNAL_CMAKE)
# include special compile flags for some compilers
include(CompileFlags.cmake)
# check for available C++ features
include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx_features.cmake)
endif()
@ -226,6 +234,31 @@ option(CMAKE_USE_FOLDERS "Enable folder grouping of projects in IDEs." ON)
mark_as_advanced(CMAKE_USE_FOLDERS)
option(CMake_RUN_CLANG_TIDY "Run clang-tidy with the compiler." OFF)
if(CMake_RUN_CLANG_TIDY)
if(CMake_SOURCE_DIR STREQUAL CMake_BINARY_DIR)
message(FATAL_ERROR "CMake_RUN_CLANG_TIDY requires an out-of-source build!")
endif()
find_program(CLANG_TIDY_COMMAND NAMES clang-tidy)
if(NOT CLANG_TIDY_COMMAND)
message(FATAL_ERROR "CMake_RUN_CLANG_TIDY is ON but clang-tidy is not found!")
endif()
set(CMAKE_CXX_CLANG_TIDY "${CLANG_TIDY_COMMAND}")
endif()
configure_file(.clang-tidy .clang-tidy COPYONLY)
option(CMake_RUN_IWYU "Run include-what-you-use with the compiler." OFF)
if(CMake_RUN_IWYU)
find_program(IWYU_COMMAND NAMES include-what-you-use iwyu)
if(NOT IWYU_COMMAND)
message(FATAL_ERROR "CMake_RUN_IWYU is ON but include-what-you-use is not found!")
endif()
set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE
"${IWYU_COMMAND};-Xiwyu;--mapping_file=${CMake_SOURCE_DIR}/Utilities/IWYU/mapping.imp")
endif()
#-----------------------------------------------------------------------
# a macro that only sets the FOLDER target property if it's
# "appropriate"
@ -421,14 +454,15 @@ macro (CMAKE_BUILD_UTILITIES)
if(NOT LIBLZMA_FOUND)
message(FATAL_ERROR "CMAKE_USE_SYSTEM_LIBLZMA is ON but LibLZMA is not found!")
endif()
set(LZMA_INCLUDE_DIR ${LIBLZMA_INCLUDE_DIRS})
set(LZMA_LIBRARY ${LIBLZMA_LIBRARIES})
else()
add_subdirectory(Utilities/cmliblzma)
CMAKE_SET_TARGET_FOLDER(cmliblzma "Utilities/3rdParty")
set(LZMA_INCLUDE_DIR
set(LIBLZMA_HAS_AUTO_DECODER 1)
set(LIBLZMA_HAS_EASY_ENCODER 1)
set(LIBLZMA_HAS_LZMA_PRESET 1)
set(LIBLZMA_INCLUDE_DIR
"${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmliblzma/liblzma/api")
set(LZMA_LIBRARY cmliblzma)
set(LIBLZMA_LIBRARY cmliblzma)
endif()
endif()
@ -449,13 +483,14 @@ macro (CMAKE_BUILD_UTILITIES)
add_definitions(-DLIBARCHIVE_STATIC)
set(ENABLE_NETTLE OFF CACHE INTERNAL "Enable use of Nettle")
set(ENABLE_OPENSSL ${CMAKE_USE_OPENSSL} CACHE INTERNAL "Enable use of OpenSSL")
set(ENABLE_LZMA ON CACHE INTERNAL "Enable the use of the system found LZMA library if found")
set(ENABLE_ZLIB ON CACHE INTERNAL "Enable the use of the system found ZLIB library if found")
set(ENABLE_BZip2 ON CACHE INTERNAL "Enable the use of the system found BZip2 library if found")
set(ENABLE_LIBXML2 OFF CACHE INTERNAL "Enable the use of the system found libxml2 library if found")
set(ENABLE_EXPAT ON CACHE INTERNAL "Enable the use of the system found EXPAT library if found")
set(ENABLE_PCREPOSIX OFF CACHE INTERNAL "Enable the use of the system found PCREPOSIX library if found")
set(ENABLE_LibGCC OFF CACHE INTERNAL "Enable the use of the system found LibGCC library if found")
set(ENABLE_LZMA ON CACHE INTERNAL "Enable the use of the system LZMA library if found")
set(ENABLE_LZO OFF CACHE INTERNAL "Enable the use of the system LZO library if found")
set(ENABLE_ZLIB ON CACHE INTERNAL "Enable the use of the system ZLIB library if found")
set(ENABLE_BZip2 ON CACHE INTERNAL "Enable the use of the system BZip2 library if found")
set(ENABLE_LIBXML2 OFF CACHE INTERNAL "Enable the use of the system libxml2 library if found")
set(ENABLE_EXPAT ON CACHE INTERNAL "Enable the use of the system EXPAT library if found")
set(ENABLE_PCREPOSIX OFF CACHE INTERNAL "Enable the use of the system PCREPOSIX library if found")
set(ENABLE_LibGCC OFF CACHE INTERNAL "Enable the use of the system LibGCC library if found")
set(ENABLE_XATTR OFF CACHE INTERNAL "Enable extended attribute support")
set(ENABLE_ACL OFF CACHE INTERNAL "Enable ACL support")
set(ENABLE_ICONV OFF CACHE INTERNAL "Enable iconv support")
@ -501,18 +536,9 @@ int main(void) { return 0; }
if(NOT HAVE_CoreServices_OS_X_10_5)
set(CMAKE_USE_LIBUV 0)
endif()
elseif(CYGWIN)
# libuv does not support Cygwin
set(CMAKE_USE_LIBUV 0)
elseif(CMAKE_SYSTEM_NAME STREQUAL "HP-UX")
# Disable until it can be ported.
set(CMAKE_USE_LIBUV 0)
elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "sparc")
# Disable until it can be ported.
set(CMAKE_USE_LIBUV 0)
elseif(CMAKE_SYSTEM STREQUAL "SunOS-5.10")
# Disable until it can be ported.
set(CMAKE_USE_LIBUV 0)
endif()
endif()
if(CMAKE_USE_LIBUV)
@ -627,9 +653,6 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
include(${CMake_SOURCE_DIR}/Tests/CMakeInstall.cmake)
endif()
# include special compile flags for some compilers
include(CompileFlags.cmake)
# no clue why we are testing for this here
include(CheckSymbolExists)
CHECK_SYMBOL_EXISTS(unsetenv "stdlib.h" HAVE_UNSETENV)
@ -810,6 +833,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
PATTERN "*.sh*" PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE
GROUP_READ GROUP_EXECUTE
WORLD_READ WORLD_EXECUTE
REGEX "Help/dev($|/)" EXCLUDE
)
# Install auxiliary files integrating with other tools.

24
CONTRIBUTING.rst
View File

@ -1,6 +1,11 @@
Contributing to CMake
*********************
The following summarizes the process for contributing changes.
See documentation on `CMake Development`_ for more information.
.. _`CMake Development`: Help/dev/README.rst
Community
=========
@ -19,25 +24,20 @@ CMake uses `Kitware's GitLab Instance`_ to manage development and code review.
To contribute patches:
#. Fork the upstream `CMake Repository`_ into a personal account.
#. Run `Utilities/SetupForDevelopment.sh`_ for local configuration.
#. See the `CMake Source Code Guide`_ for coding guidelines.
#. Base all new work on the upstream ``master`` branch.
#. Create commits making incremental, distinct, logically complete changes.
#. Push a topic branch to a personal repository fork on GitLab.
#. Create a GitLab Merge Request targeting the upstream ``master`` branch.
The merge request will enter the `CMake Review Process`_ for consideration.
.. _`Kitware's GitLab Instance`: https://gitlab.kitware.com
.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
Code Style
==========
We use `clang-format`_ to define our style for C++ code in the CMake source
tree. See the `.clang-format`_ configuration file for our style settings.
Use ``clang-format`` version 3.8 or higher to format source files.
See also the `Utilities/Scripts/clang-format.bash`_ script.
.. _`clang-format`: http://clang.llvm.org/docs/ClangFormat.html
.. _`.clang-format`: .clang-format
.. _`Utilities/Scripts/clang-format.bash`: Utilities/Scripts/clang-format.bash
.. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh
.. _`CMake Source Code Guide`: Help/dev/source.rst
.. _`CMake Review Process`: Help/dev/review.rst
License
=======

16
CompileFlags.cmake
View File

@ -4,10 +4,6 @@
#-----------------------------------------------------------------------------
# set some special flags for different compilers
#
if(CMAKE_GENERATOR MATCHES "Visual Studio 7")
set(CMAKE_SKIP_COMPATIBILITY_TESTS 1)
endif()
if(WIN32 AND CMAKE_C_COMPILER_ID STREQUAL "Intel")
set(_INTEL_WINDOWS 1)
endif()
@ -63,9 +59,17 @@ if(CMAKE_SYSTEM_PROCESSOR MATCHES "^parisc")
endif()
endif()
if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro)
if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND
NOT DEFINED CMAKE_CXX${CMAKE_CXX_STANDARD}_STANDARD_COMPILE_OPTION)
if (NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.13)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++03")
if (NOT CMAKE_CXX_STANDARD OR CMAKE_CXX_STANDARD EQUAL 98)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++03")
elseif(CMAKE_VERSION VERSION_LESS 3.8.20170502)
# CMake knows how to add this flag for compilation as C++11,
# but has not been taught that SunPro needs it for linking too.
# Add it in a place that will be used for both.
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
endif()
else()
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -library=stlport4")
endif()

35
Help/command/FIND_XXX.txt
View File

@ -16,8 +16,9 @@ The general signature is:
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_DEFAULT_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
@ -60,6 +61,10 @@ If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
added to the search.
If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace::
|prefix_XXX_SUBDIR| for each ``<prefix>`` in ``PackageName_ROOT`` if called
from within a find module
.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
|prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
@ -71,33 +76,47 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
|prefix_XXX_SUBDIR| for each ``<prefix>`` in
:variable:`CMAKE_SYSTEM_PREFIX_PATH`
1. Search paths specified in cmake-specific cache variables.
1. If called from within a find module, search prefix paths unique to the
current package being found. Specifically look in the ``PackageName_ROOT``
CMake and environment variables. The package root variables are maintained
as a stack so if called from nested find modules, root paths from the
parent's find module will be searchd after paths from the current module,
i.e. ``CurrentPackage_ROOT``, ``ENV{CurrentPackage_ROOT}``,
``ParentPackage_ROOT``, ``ENV{ParentPacakge_ROOT}``, etc.
This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
* |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|
2. Search paths specified in cmake-specific cache variables.
These are intended to be used on the command line with a ``-DVAR=value``.
The values are interpreted as :ref:`;-lists <CMake Language Lists>`.
This can be skipped if ``NO_CMAKE_PATH`` is passed.
* |CMAKE_PREFIX_PATH_XXX|
* |CMAKE_XXX_PATH|
* |CMAKE_XXX_MAC_PATH|
2. Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration.
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration,
and therefore use the host's native path separator
(``;`` on Windows and ``:`` on UNIX).
This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed.
* |CMAKE_PREFIX_PATH_XXX|
* |CMAKE_XXX_PATH|
* |CMAKE_XXX_MAC_PATH|
3. Search the paths specified by the ``HINTS`` option.
4. Search the paths specified by the ``HINTS`` option.
These should be paths computed by system introspection, such as a
hint provided by the location of another item already found.
Hard-coded guesses should be specified with the ``PATHS`` option.
4. Search the standard system environment variables.
5. Search the standard system environment variables.
This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument.
* |SYSTEM_ENVIRONMENT_PATH_XXX|
5. Search cmake variables defined in the Platform files
6. Search cmake variables defined in the Platform files
for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
is passed.
@ -105,7 +124,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
* |CMAKE_SYSTEM_XXX_PATH|
* |CMAKE_SYSTEM_XXX_MAC_PATH|
6. Search the paths specified by the PATHS option
7. Search the paths specified by the PATHS option
or in the short-hand version of the command.
These are typically hard-coded guesses.

2
Help/command/add_custom_command.rst
View File

@ -215,7 +215,7 @@ of the following is specified:
``PRE_BUILD``
Run before any other rules are executed within the target.
This is supported only on Visual Studio 7 or later.
This is supported only on Visual Studio 8 or later.
For all other generators ``PRE_BUILD`` will be treated as
``PRE_LINK``.
``PRE_LINK``

3
Help/command/add_executable.rst
View File

@ -40,6 +40,9 @@ the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.
--------------------------------------------------------------------------

15
Help/command/add_library.rst
View File

@ -59,12 +59,16 @@ the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.
Imported Libraries
^^^^^^^^^^^^^^^^^^
::
add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
[GLOBAL])
An :ref:`IMPORTED library target <Imported Targets>` references a library
@ -106,10 +110,9 @@ may contain only sources that compile, header files, and other files
that would not affect linking of a normal library (e.g. ``.txt``).
They may contain custom commands generating such sources, but not
``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Object libraries
cannot be imported, exported, installed, or linked. Some native build
systems may not like targets that have only object files, so consider
adding at least one real source file to any target that references
``$<TARGET_OBJECTS:objlib>``.
cannot be linked. Some native build systems may not like targets that
have only object files, so consider adding at least one real source file
to any target that references ``$<TARGET_OBJECTS:objlib>``.
Alias Libraries
^^^^^^^^^^^^^^^
@ -120,7 +123,7 @@ Alias Libraries
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
not appear in the generatedbuildsystem as a make target. The ``<target>``
not appear in the generated buildsystem as a make target. The ``<target>``
may not be an :ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
``ALIAS`` targets can be used as linkable targets and as targets to
read properties from. They can also be tested for existence with the

3
Help/command/ctest_memcheck.rst
View File

@ -13,6 +13,9 @@ Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.
[INCLUDE <include-regex>]
[EXCLUDE_LABEL <label-exclude-regex>]
[INCLUDE_LABEL <label-include-regex>]
[EXCLUDE_FIXTURE <regex>]
[EXCLUDE_FIXTURE_SETUP <regex>]
[EXCLUDE_FIXTURE_CLEANUP <regex>]
[PARALLEL_LEVEL <level>]
[TEST_LOAD <threshold>]
[SCHEDULE_RANDOM <ON|OFF>]

10
Help/command/ctest_submit.rst
View File

@ -6,6 +6,7 @@ Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
::
ctest_submit([PARTS <part>...] [FILES <file>...]
[HTTPHEADER <header>]
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
[RETURN_VALUE <result-var>]
@ -36,6 +37,10 @@ The options are:
Specify an explicit list of specific files to be submitted.
Each individual file must exist at the time of the call.
``HTTPHEADER <HTTP-header>``
Specify HTTP header to be included in the request to CDash during submission.
This suboption can be repeated several times.
``RETRY_COUNT <count>``
Specify how many times to retry a timed-out submission.
@ -57,6 +62,7 @@ Submit to CDash Upload API
::
ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
[HTTPHEADER <header>]
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
[QUIET])
@ -67,5 +73,5 @@ with a content hash of the file. If CDash does not already have the file,
then it is uploaded. Along with the file, a CDash type string is specified
to tell CDash which handler to use to process the data.
This signature accepts the ``RETRY_COUNT``, ``RETRY_DELAY``, and ``QUIET``
options as described above.
This signature accepts the ``HTTPHEADER``, ``RETRY_COUNT``, ``RETRY_DELAY``, and
``QUIET`` options as described above.

17
Help/command/ctest_test.rst
View File

@ -13,6 +13,9 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
[INCLUDE <include-regex>]
[EXCLUDE_LABEL <label-exclude-regex>]
[INCLUDE_LABEL <label-include-regex>]
[EXCLUDE_FIXTURE <regex>]
[EXCLUDE_FIXTURE_SETUP <regex>]
[EXCLUDE_FIXTURE_CLEANUP <regex>]
[PARALLEL_LEVEL <level>]
[TEST_LOAD <threshold>]
[SCHEDULE_RANDOM <ON|OFF>]
@ -61,6 +64,20 @@ The options are:
Specify a regular expression matching test labels to include.
Tests not matching this expression are excluded.
``EXCLUDE_FIXTURE <regex>``
If a test in the set of tests to be executed requires a particular fixture,
that fixture's setup and cleanup tests would normally be added to the test
set automatically. This option prevents adding setup or cleanup tests for
fixtures matching the ``<regex>``. Note that all other fixture behavior is
retained, including test dependencies and skipping tests that have fixture
setup tests that fail.
``EXCLUDE_FIXTURE_SETUP <regex>``
Same as ``EXCLUDE_FIXTURE`` except only matching setup tests are excluded.
``EXCLUDE_FIXTURE_CLEANUP <regex>``
Same as ``EXCLUDE_FIXTURE`` except only matching cleanup tests are excluded.
``PARALLEL_LEVEL <level>``
Specify a positive number representing the number of tests to
be run in parallel.

3
Help/command/find_file.rst
View File

@ -8,6 +8,9 @@ find_file
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|

18
Help/command/find_library.rst
View File

@ -8,6 +8,9 @@ find_library
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/lib``
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
@ -49,6 +52,14 @@ path to the framework ``<fullPath>/A.framework``. When a full path to a
framework is used as a library, CMake will use a ``-framework A``, and a
``-F<fullPath>`` to link the framework to the target.
If the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable is set all
search paths will be tested as normal, with the suffix appended, and with
all matches of ``lib/`` replaced with
``lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/``. This variable overrides
the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS`,
:prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS`,
and :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global properties.
If the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global property is set
all search paths will be tested as normal, with ``32/`` appended, and
with all matches of ``lib/`` replaced with ``lib32/``. This property is
@ -56,6 +67,13 @@ automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.
If the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property is set
all search paths will be tested as normal, with ``x32/`` appended, and
with all matches of ``lib/`` replaced with ``libx32/``. This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.
If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set
all search paths will be tested as normal, with ``64/`` appended, and
with all matches of ``lib/`` replaced with ``lib64/``. This property is

30
Help/command/find_package.rst
View File

@ -64,8 +64,9 @@ The complete Config mode command signature is::
[PATHS path1 [path2 ... ]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[NO_DEFAULT_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_PACAKGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_PACKAGE_REGISTRY]
[NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
@ -249,16 +250,25 @@ The set of installation prefixes is constructed using the following
steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are
enabled.
1. Search paths specified in cmake-specific cache variables. These
1. Search paths specified in the ``PackageName_ROOT`` CMake and environment
variables. The package root variables are maintained as a stack so if
called from within a find module, root paths from the parent's find
module will also be searched after paths for the current package. This can
be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
2. Search paths specified in cmake-specific cache variables. These
are intended to be used on the command line with a ``-DVAR=value``.
The values are interpreted as :ref:`;-lists <CMake Language Lists>`.
This can be skipped if ``NO_CMAKE_PATH`` is passed::
CMAKE_PREFIX_PATH
CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH
2. Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration.
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration,
and therefore use the host's native path separator
(``;`` on Windows and ``:`` on UNIX).
This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed::
<package>_DIR
@ -266,26 +276,26 @@ enabled.
CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH
3. Search paths specified by the ``HINTS`` option. These should be paths
4. Search paths specified by the ``HINTS`` option. These should be paths
computed by system introspection, such as a hint provided by the
location of another item already found. Hard-coded guesses should
be specified with the ``PATHS`` option.
4. Search the standard system environment variables. This can be
5. Search the standard system environment variables. This can be
skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed. Path entries
ending in ``/bin`` or ``/sbin`` are automatically converted to their
parent directories::
PATH
5. Search paths stored in the CMake :ref:`User Package Registry`.
6. Search paths stored in the CMake :ref:`User Package Registry`.
This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by
setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`
to ``TRUE``.
See the :manual:`cmake-packages(7)` manual for details on the user
package registry.
6. Search cmake variables defined in the Platform files for the
7. Search cmake variables defined in the Platform files for the
current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
passed::
@ -293,14 +303,14 @@ enabled.
CMAKE_SYSTEM_FRAMEWORK_PATH
CMAKE_SYSTEM_APPBUNDLE_PATH
7. Search paths stored in the CMake :ref:`System Package Registry`.
8. Search paths stored in the CMake :ref:`System Package Registry`.
This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed
or by setting the
:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``.
See the :manual:`cmake-packages(7)` manual for details on the system
package registry.
8. Search paths specified by the ``PATHS`` option. These are typically
9. Search paths specified by the ``PATHS`` option. These are typically
hard-coded guesses.
.. |FIND_XXX| replace:: find_package

3
Help/command/find_path.rst
View File

@ -8,6 +8,9 @@ find_path
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|

2
Help/command/find_program.rst
View File

@ -8,6 +8,8 @@ find_program
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin``
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
|FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
|CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH`

3
Help/command/if.rst
View File

@ -103,7 +103,8 @@ Possible expressions are:
``if(<variable|string> MATCHES regex)``
True if the given string or variable's value matches the given regular
expression.
expression. See :ref:`Regex Specification` for regex format.
``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables.
``if(<variable|string> LESS <variable|string>)``
True if the given string or variable's value is a valid number and less

4
Help/command/include_external_msproject.rst
View File

@ -20,3 +20,7 @@ command to make things depend on the external project.
specify the type of project, id (GUID) of the project and the name of
the target platform. This is useful for projects requiring values
other than the default (e.g. WIX projects).
If the imported project has different configuration names than the
current project, set the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>`
target property to specify the mapping.

23
Help/command/install.rst
View File

@ -73,7 +73,7 @@ Installing Targets
::
install(TARGETS targets... [EXPORT <export-name>]
[[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
[[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
[DESTINATION <dir>]
[PERMISSIONS permissions...]
@ -86,10 +86,10 @@ Installing Targets
)
The ``TARGETS`` form specifies rules for installing targets from a
project. There are five kinds of target files that may be installed:
``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE``.
Executables are treated as ``RUNTIME`` targets, except that those
marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE``
project. There are six kinds of target files that may be installed:
``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, ``FRAMEWORK``, and
``BUNDLE``. Executables are treated as ``RUNTIME`` targets, except that
those marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE``
targets on OS X. Static libraries are treated as ``ARCHIVE`` targets,
except that those marked with the ``FRAMEWORK`` property are treated
as ``FRAMEWORK`` targets on OS X.
@ -99,10 +99,11 @@ targets, except that those marked with the ``FRAMEWORK`` property are
treated as ``FRAMEWORK`` targets on OS X. For DLL platforms the DLL
part of a shared library is treated as a ``RUNTIME`` target and the
corresponding import library is treated as an ``ARCHIVE`` target.
All Windows-based systems including Cygwin are DLL platforms.
The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, and ``FRAMEWORK`` arguments
change the type of target to which the subsequent properties apply.
If none is given the installation properties apply to all target
All Windows-based systems including Cygwin are DLL platforms. Object
libraries are always treated as ``OBJECTS`` targets.
The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, and ``FRAMEWORK``
arguments change the type of target to which the subsequent properties
apply. If none is given the installation properties apply to all target
types. If only one is given then only targets of that type will be
installed (which can be used to install just a DLL or just an import
library).
@ -165,8 +166,8 @@ the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and
The ``EXPORT`` option associates the installed target files with an
export called ``<export-name>``. It must appear before any ``RUNTIME``,
``LIBRARY``, or ``ARCHIVE`` options. To actually install the export
file itself, call ``install(EXPORT)``, documented below.
``LIBRARY``, ``ARCHIVE``, or ``OBJECTS`` options. To actually install the
export file itself, call ``install(EXPORT)``, documented below.
Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
set to ``TRUE`` has undefined behavior.

5
Help/command/project.rst
View File

@ -8,6 +8,7 @@ Set a name, version, and enable languages for the entire project.
project(<PROJECT-NAME> [LANGUAGES] [<language-name>...])
project(<PROJECT-NAME>
[VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
[DESCRIPTION <project-description-string>]
[LANGUAGES <language-name>...])
Sets the name of the project and stores the name in the
@ -40,6 +41,10 @@ in variables
Variables corresponding to unspecified versions are set to the empty string
(if policy :policy:`CMP0048` is set to ``NEW``).
If optional ``DESCRIPTION`` is given, then additional :variable:`PROJECT_DESCRIPTION`
variable will be set to its argument. The argument must be a string with short
description of the project (only a few words).
Optionally you can specify which languages your project supports.
Example languages are ``C``, ``CXX`` (i.e. C++), ``Fortran``, etc.
By default ``C`` and ``CXX`` are enabled if no language options are

9
Help/command/separate_arguments.rst
View File

@ -5,9 +5,9 @@ Parse space-separated arguments into a semicolon-separated list.
::
separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")
separate_arguments(<var> <NATIVE|UNIX|WINDOWS>_COMMAND "<args>")
Parses a unix- or windows-style command-line string "<args>" and
Parses a UNIX- or Windows-style command-line string "<args>" and
stores a semicolon-separated list of the arguments in ``<var>``. The
entire command line must be given in one "<args>" argument.
@ -16,12 +16,15 @@ recognizes both single-quote and double-quote pairs. A backslash
escapes the next literal character (``\"`` is ``"``); there are no special
escapes (``\n`` is just ``n``).
The ``WINDOWS_COMMAND`` mode parses a windows command-line using the same
The ``WINDOWS_COMMAND`` mode parses a Windows command-line using the same
syntax the runtime library uses to construct argv at startup. It
separates arguments by whitespace that is not double-quoted.
Backslashes are literal unless they precede double-quotes. See the
MSDN article `Parsing C Command-Line Arguments`_ for details.
The ``NATIVE_COMMAND`` mode parses a Windows command-line if the host
system is Windows, and a UNIX command-line otherwise.
.. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx
::

52
Help/command/string.rst
View File

@ -77,31 +77,43 @@ The replace expression may refer to paren-delimited subexpressions of the
match using ``\1``, ``\2``, ..., ``\9``. Note that two backslashes (``\\1``)
are required in CMake code to get a backslash through argument parsing.
.. _`Regex Specification`:
Regex Specification
"""""""""""""""""""
The following characters have special meaning in regular expressions:
::
^ Matches at beginning of input
$ Matches at end of input
. Matches any single character
[ ] Matches any character(s) inside the brackets
[^ ] Matches any character(s) not inside the brackets
- Inside brackets, specifies an inclusive range between
characters on either side e.g. [a-f] is [abcdef]
To match a literal - using brackets, make it the first
or the last character e.g. [+*/-] matches basic
mathematical operators.
* Matches preceding pattern zero or more times
+ Matches preceding pattern one or more times
? Matches preceding pattern zero or once only
| Matches a pattern on either side of the |
() Saves a matched subexpression, which can be referenced
in the REGEX REPLACE operation. Additionally it is saved
by all regular expression-related commands, including
e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).
``^``
Matches at beginning of input
``$``
Matches at end of input
``.``
Matches any single character
``[ ]``
Matches any character(s) inside the brackets
``[^ ]``
Matches any character(s) not inside the brackets
``-``
Inside brackets, specifies an inclusive range between
characters on either side e.g. ``[a-f]`` is ``[abcdef]``
To match a literal ``-`` using brackets, make it the first
or the last character e.g. ``[+*/-]`` matches basic
mathematical operators.
``*``
Matches preceding pattern zero or more times
``+``
Matches preceding pattern one or more times
``?``
Matches preceding pattern zero or once only
``|``
Matches a pattern on either side of the ``|``
``()``
Saves a matched subexpression, which can be referenced
in the ``REGEX REPLACE`` operation. Additionally it is saved
by all regular expression-related commands, including
e.g. :command:`if(MATCHES)`, in the variables
:variable:`CMAKE_MATCH_<n>` for ``<n>`` 0..9.
``*``, ``+`` and ``?`` have higher precedence than concatenation. ``|``
has lower precedence than concatenation. This means that the regular

49
Help/dev/README.rst Normal file
View File

@ -0,0 +1,49 @@
CMake Development
*****************
This directory contains documentation about development of CMake itself.
It is not part of the user documentation distributed with CMake.
Contributor Instructions
========================
See `CONTRIBUTING.rst`_ for instructions to contribute changes.
The process for contributing changes is the same whether or not one
has been invited to participate directly in upstream development.
.. _`CONTRIBUTING.rst`: ../../CONTRIBUTING.rst
Upstream Development
====================
CMake uses `Kitware's GitLab Instance`_ to manage development, review, and
integration of changes. The `CMake Repository`_ holds the integration
branches and tags. Upstream development processes are covered by the
following documents:
* The `CMake Review Process`_ manages integration of changes.
* The `CMake Testing Process`_ drives integration testing.
.. _`Kitware's GitLab Instance`: https://gitlab.kitware.com
.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
.. _`CMake Review Process`: review.rst
.. _`CMake Testing Process`: testing.rst
Developer Documentation
=======================
CMake developer documentation is provided by the following documents:
* The `CMake Source Code Guide`_.
.. _`CMake Source Code Guide`: source.rst
Maintainer Documentation
========================
CMake maintainer documentation is provided by the following documents:
* The `CMake Maintainer Guide`_.
.. _`CMake Maintainer Guide`: maint.rst

171
Help/dev/maint.rst Normal file
View File

@ -0,0 +1,171 @@
CMake Maintainer Guide
**********************
The following is a guide to CMake maintenance processes.
See documentation on `CMake Development`_ for more information.
.. _`CMake Development`: README.rst
.. contents:: Maintainer Processes:
Branch a New Release
====================
This section covers how to start a new ``release`` branch for a major or
minor version bump (patch releases remain on their existing branch).
In the following we use the placeholder ``$ver`` to represent the
version number of the new release with the form ``$major.$minor``,
and ``$prev`` to represent the version number of the prior release.
Review Prior Release
--------------------
Review the history around the prior release branch:
.. code-block:: shell
git log --graph --boundary \
^$(git rev-list --grep="Merge topic 'doc-.*-relnotes'" -n 1 master)~1 \
$(git rev-list --grep="Begin post-.* development" -n 1 master) \
$(git tag --list *-rc1| tail -1)
Consolidate Release Notes
-------------------------
Starting from a clean work tree on ``master``, create a topic branch to
use for consolidating the release notes:
.. code-block:: shell
git checkout -b doc-$ver-relnotes
Run the `consolidate-relnotes.bash`_ script:
.. code-block:: shell
Utilities/Release/consolidate-relnotes.bash $ver $prev
.. _`consolidate-relnotes.bash`: ../../Utilities/Release/consolidate-relnotes.bash
This moves notes from the ``Help/release/dev/*.rst`` files into a versioned
``Help/release/$ver.rst`` file and updates ``Help/release/index.rst`` to
link to the new document. Commit the changes with a message such as::
Help: Consolidate $ver release notes
Run the `Utilities/Release/consolidate-relnotes.bash` script to move
notes from `Help/release/dev/*` into `Help/release/$ver.rst`.
Manually edit ``Help/release/$ver.rst`` to add section headers, organize
the notes, and revise wording. Then commit with a message such as::
Help: Organize and revise $ver release notes
Add section headers similar to the $prev release notes and move each
individual bullet into an appropriate section. Revise a few bullets.
Open a merge request with the ``doc-$ver-relnotes`` branch for review
and integration. Further steps may proceed after this has been merged
to ``master``.
Update 'release' Branch
-----------------------
Starting from a clean work tree on ``master``, create a new ``release-$ver``
branch locally:
.. code-block:: shell
git checkout -b release-$ver origin/master
Remove the development branch release note infrastructure:
.. code-block:: shell
git rm Help/release/dev/0-sample-topic.rst
sed -i '/^\.\. include:: dev.txt/ {N;d}' Help/release/index.rst
Commit with a message such as::
Help: Drop development topic notes to prepare release
Release versions do not have the development topic section of
the CMake Release Notes index page.
Update ``Source/CMakeVersion.cmake`` to set the version to
``$major.$minor.0-rc1``:
.. code-block:: cmake
# CMake version number components.
set(CMake_VERSION_MAJOR $major)
set(CMake_VERSION_MINOR $minor)
set(CMake_VERSION_PATCH 0)
set(CMake_VERSION_RC 1)
Update ``Utilities/Release/upload_release.cmake``:
.. code-block:: cmake
set(VERSION $ver)
Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the
actual version number:
.. code-block:: shell
$EDITOR $(git grep -l DEVEL_CMAKE_VERSION)
Commit with a message such as::
CMake $major.$minor.0-rc1 version update
Merge the ``release-$ver`` branch to ``master``:
.. code-block:: shell
git checkout master
git pull
git merge --no-ff release-$ver
Begin post-release development by restoring the development branch release
note infrastructure and the version date from ``origin/master``:
.. code-block:: shell
git checkout origin/master -- \
Source/CMakeVersion.cmake Help/release/dev/0-sample-topic.rst
sed -i $'/^Releases/ i\\\n.. include:: dev.txt\\\n' Help/release/index.rst
Update ``Source/CMakeVersion.cmake`` to set the version to
``$major.$minor.$date``:
.. code-block:: cmake
# CMake version number components.
set(CMake_VERSION_MAJOR $major)
set(CMake_VERSION_MINOR $minor)
set(CMake_VERSION_PATCH $date)
#set(CMake_VERSION_RC 1)
Commit with a message such as::
Begin post-$ver development
Push the update to the ``master`` and ``release`` branches:
.. code-block:: shell
git push --atomic origin master release-$ver:release
Announce 'release' Branch
-------------------------
Send email to the ``cmake-developers@cmake.org`` mailing list (perhaps
in reply to a release preparation thread) announcing that post-release
development is open::
I've branched 'release' for $ver. The repository is now open for
post-$ver development. Please rebase open merge requests on 'master'
before staging or merging.

350
Help/dev/review.rst Normal file
View File

@ -0,0 +1,350 @@
CMake Review Process
********************
The following documents the process for reviewing and integrating changes.
See `CONTRIBUTING.rst`_ for instructions to contribute changes.
See documentation on `CMake Development`_ for more information.
.. _`CONTRIBUTING.rst`: ../../CONTRIBUTING.rst
.. _`CMake Development`: README.rst
.. contents:: The review process consists of the following steps:
Merge Request
=============
A user initiates the review process for a change by pushing a *topic
branch* to his or her own fork of the `CMake Repository`_ on GitLab and
creating a *merge request* ("MR"). The new MR will appear on the
`CMake Merge Requests Page`_. The rest of the review and integration
process is managed by the merge request page for the change.
During the review process, the MR submitter should address review comments
or test failures by updating the MR with a (force-)push of the topic
branch. The update initiates a new round of review.
We recommend that users enable the "Remove source branch when merge
request is accepted" option when creating the MR or by editing it.
This will cause the MR topic branch to be automatically removed from
the user's fork during the `Merge`_ step.
.. _`CMake Merge Requests Page`: https://gitlab.kitware.com/cmake/cmake/merge_requests
.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
Workflow Status
---------------
`CMake GitLab Project Developers`_ may set one of the following labels
in GitLab to track the state of a MR:
* ``workflow:wip`` indicates that the MR needs additional updates from
the MR submitter before further review. Use this label after making
comments that require such updates.
* ``workflow:in-review`` indicates that the MR awaits feedback from a
human reviewer or from `Topic Testing`_. Use this label after making
comments requesting such feedback.
* ``workflow:nightly-testing`` indicates that the MR awaits results
of `Integration Testing`_. Use this label after making comments
requesting such staging.
* ``workflow:expired`` indicates that the MR has been closed due
to a period of inactivity. See the `Expire`_ step. Use this label
after closing a MR for this reason.
The workflow status labels are intended to be mutually exclusive,
so please remove any existing workflow label when adding one.
.. _`CMake GitLab Project Developers`: https://gitlab.kitware.com/cmake/cmake/settings/members
Robot Review
============
The "Kitware Robot" (``@kwrobot``) automatically performs basic checks on
the commits proposed in a MR. If all is well the robot silently reports
a successful "build" status to GitLab. Otherwise the robot posts a comment
with its diagnostics. **A topic may not be merged until the automatic
review succeeds.**
Note that the MR submitter is expected to address the robot's comments by
*rewriting* the commits named by the robot's diagnostics (e.g., via
``git rebase -i``). This is because the robot checks each commit individually,
not the topic as a whole. This is done in order to ensure that commits in the
middle of a topic do not, for example, add a giant file which is then later
removed in the topic.
Automatic Check
---------------
The automatic check is repeated whenever the topic branch is updated.
One may explicitly request a re-check by adding a comment with the
following command among the `comment trailing lines`_::
Do: check
``@kwrobot`` will add an award emoji to the comment to indicate that it
was processed and also run its checks again.
Automatic Format
----------------
The automatic check will reject commits introducing source code not
formatted according to ``clang-format``. One may ask the robot to
automatically rewrite the MR topic branch with expected formatting
by adding a comment with the following command among the
`comment trailing lines`_::
Do: reformat
``@kwrobot`` will add an award emoji to the comment to indicate that it
was processed and also rewrite the MR topic branch and force-push an
updated version with every commit formatted as expected by the check.
Human Review
============
Anyone is welcome to review merge requests and make comments!
Please make comments directly on the MR page Discussion and Changes tabs
and not on individual commits. Comments on a commit may disappear
from the MR page if the commit is rewritten in response.
Reviewers may add comments providing feedback or to acknowledge their
approval. Lines of specific forms will be extracted during the `merge`_
step and included as trailing lines of the generated merge commit message.
Each review comment consists of up to two parts which must be specified
in the following order: `comment body`_, then `comment trailing lines`_.
Each part is optional, but they must be specified in this order.
Comment Body
------------
The body of a comment may be free-form `GitLab Flavored Markdown`_.
See GitLab documentation on `Special GitLab References`_ to add links to
things like issues, commits, or other merge requests (even across projects).
Additionally, a line in the comment body may start with one of the
following votes:
* ``-1`` or ``:-1:`` indicates "the change is not ready for integration".
* ``+1`` or ``:+1:`` indicates "I like the change".
This adds an ``Acked-by:`` trailer to the `merge`_ commit message.
* ``+2`` indicates "the change is ready for integration".
This adds a ``Reviewed-by:`` trailer to the `merge`_ commit message.
* ``+3`` indicates "I have tested the change and verified it works".
This adds a ``Tested-by:`` trailer to the `merge`_ commit message.
.. _`GitLab Flavored Markdown`: https://gitlab.kitware.com/help/user/markdown.md
.. _`Special GitLab References`: https://gitlab.kitware.com/help/user/markdown.md#special-gitlab-references
Comment Trailing Lines
----------------------
Zero or more *trailing* lines in the last section of a comment may appear
with the form ``Key: Value``. The first such line should be separated
from a preceding `comment body`_ by a blank line. Any key-value pair(s)
may be specified for human reference. A few specific keys have meaning to
``@kwrobot`` as follows.
Comment Trailer Votes
^^^^^^^^^^^^^^^^^^^^^
Among the `comment trailing lines`_ one may cast a vote using one of the
following pairs followed by nothing but whitespace before the end of the line:
* ``Rejected-by: me`` indicates "the change is not ready for integration".
* ``Acked-by: me`` indicates "I like the change".
This adds an ``Acked-by:`` trailer to the `merge`_ commit message.
* ``Reviewed-by: me`` indicates "the change is ready for integration".
This adds a ``Reviewed-by:`` trailer to the `merge`_ commit message.
* ``Tested-by: me`` indicates "I have tested the change and verified it works".
This adds a ``Tested-by:`` trailer to the `merge`_ commit message.
Each ``me`` reference may instead be an ``@username`` reference or a full
``Real Name <user@domain>`` reference to credit someone else for performing
the review. References to ``me`` and ``@username`` will automatically be
transformed into a real name and email address according to the user's
GitLab account profile.
Comment Trailer Commands
^^^^^^^^^^^^^^^^^^^^^^^^
Among the `comment trailing lines`_ authorized users may issue special
commands to ``@kwrobot`` using the form ``Do: ...``:
* ``Do: check`` explicitly re-runs the robot `Automatic Check`_.
* ``Do: reformat`` rewrites the MR topic for `Automatic Format`_.
* ``Do: test`` submits the MR for `Topic Testing`_.
* ``Do: stage`` submits the MR for `Integration Testing`_.
* ``Do: merge`` submits the MR for `Merge`_.
See the corresponding sections for details on permissions and options
for each command.
Topic Testing
=============
CMake has a `buildbot`_ instance watching for merge requests to test.
`CMake GitLab Project Developers`_ may activate buildbot on a MR by
adding a comment with a command among the `comment trailing lines`_::
Do: test
``@kwrobot`` will add an award emoji to the comment to indicate that it
was processed and also inform buildbot about the request. The buildbot
user (``@buildbot``) will schedule builds and respond with a comment
linking to the `CMake CDash Page`_ with a filter for results associated
with the topic test request. If the MR topic branch is updated by a
push a new ``Do: test`` command is needed to activate testing again.
The ``Do: test`` command accepts the following arguments:
* ``--stop``: clear the list of commands for the merge request
* ``--clear``: clear previous commands before adding this command
* ``--regex-include <arg>`` or ``-i <arg>``: only build on builders
matching ``<arg>`` (a Python regular expression)
* ``--regex-exclude <arg>`` or ``-e <arg>``: exclude builds on builders
matching ``<arg>`` (a Python regular expression)
Builder names follow the pattern ``project-host-os-buildtype-generator``:
* ``project``: always ``cmake`` for CMake builds
* ``host``: the buildbot host
* ``os``: one of ``windows``, ``osx``, or ``linux``
* ``buildtype``: ``release`` or ``debug``
* ``generator``: ``ninja``, ``makefiles``, ``vs<year>``,
or ``lint-iwyu-tidy``
The special ``lint-<tools>`` generator name is a builder that builds
CMake using lint tools but does not run the test suite (so the actual
generator does not matter).
.. _`buildbot`: http://buildbot.net
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
Integration Testing
===================
The above `topic testing`_ tests the MR topic independent of other
merge requests and on only a few key platforms and configurations.
The `CMake Testing Process`_ also has a large number of machines
provided by Kitware and generous volunteers that cover nearly all
supported platforms, generators, and configurations. In order to
avoid overwhelming these resources, they do not test every MR
individually. Instead, these machines follow an *integration branch*,
run tests on a nightly basis (or continuously during the day), and
post to the `CMake CDash Page`_. Some follow ``master``. Most follow
a special integration branch, the *topic stage*.
The topic stage is a special branch maintained by the "Kitware Robot"
(``@kwrobot``). It consists of the head of the MR target integration
branch (e.g. ``master``) branch followed by a sequence of merges each
integrating changes from an open MR that has been staged for integration
testing. Each time the target integration branch is updated the stage
is rebuilt automatically by merging the staged MR topics again.
`CMake GitLab Project Developers`_ may stage a MR for integration testing
by adding a comment with a command among the `comment trailing lines`_::
Do: stage
``@kwrobot`` will add an award emoji to the comment to indicate that it
was processed and also attempt to add the MR topic branch to the topic
stage. If the MR cannot be added (e.g. due to conflicts) the robot will
post a comment explaining what went wrong.
Once a MR has been added to the topic stage it will remain on the stage
until one of the following occurs:
* The MR topic branch is updated by a push.
* The MR target integration branch (e.g. ``master``) branch is updated
and the MR cannot be merged into the topic stage again due to conflicts.
* A developer or the submitter posts an explicit ``Do: unstage`` command.
This is useful to remove a MR from the topic stage when one is not ready
to push an update to the MR topic branch. It is unnecessary to explicitly
unstage just before or after pushing an update because the push will cause
the MR to be unstaged automatically.
* The MR is closed.
* The MR is merged.
Once a MR has been removed from the topic stage a new ``Do: stage``
command is needed to stage it again.
.. _`CMake Testing Process`: testing.rst
Resolve
=======
A MR may be resolved in one of the following ways.
Merge
-----
Once review has concluded that the MR topic is ready for integration,
`CMake GitLab Project Masters`_ may merge the topic by adding a comment
with a command among the `comment trailing lines`_::
Do: merge
``@kwrobot`` will add an award emoji to the comment to indicate that it
was processed and also attempt to merge the MR topic branch to the MR
target integration branch (e.g. ``master``). If the MR cannot be merged
(e.g. due to conflicts) the robot will post a comment explaining what
went wrong. If the MR is merged the robot will also remove the source
branch from the user's fork if the corresponding MR option was checked.
The robot automatically constructs a merge commit message of the following
form::
Merge topic 'mr-topic-branch-name'
00000000 commit message subject line (one line per commit)
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !0000
Mention of the commit short sha1s and MR number helps GitLab link the
commits back to the merge request and indicates when they were merged.
The ``Acked-by:`` trailer shown indicates that `Robot Review`_ passed.
Additional ``Acked-by:``, ``Reviewed-by:``, and similar trailers may be
collected from `Human Review`_ comments that have been made since the
last time the MR topic branch was updated with a push.
The ``Do: merge`` command accepts the following arguments:
* ``-t <topic>``: substitute ``<topic>`` for the name of the MR topic
branch in the constructed merge commit message.
Additionally, ``Do: merge`` extracts configuration from trailing lines
in the MR description:
* ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of
the MR topic branch in the constructed merge commit message.
The ``-t`` option overrides this.
.. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members
Close
-----
If review has concluded that the MR should not be integrated then it
may be closed through GitLab.
Expire
------
If progress on a MR has stalled for a while, it may be closed with a
``workflow:expired`` label and a comment indicating that the MR has
been closed due to inactivity.
Contributors are welcome to re-open an expired MR when they are ready
to continue work. Please re-open *before* pushing an update to the
MR topic branch to ensure GitLab will still act on the association.

60
Help/dev/source.rst Normal file
View File

@ -0,0 +1,60 @@
CMake Source Code Guide
***********************
The following is a guide to the CMake source code for developers.
See documentation on `CMake Development`_ for more information.
.. _`CMake Development`: README.rst
C++ Code Style
==============
We use `clang-format`_ version **3.8** to define our style for C++ code in
the CMake source tree. See the `.clang-format`_ configuration file for our
style settings. Use the `Utilities/Scripts/clang-format.bash`_ script to
format source code. It automatically runs ``clang-format`` on the set of
source files for which we enforce style. The script also has options to
format only a subset of files, such as those that are locally modified.
.. _`clang-format`: http://clang.llvm.org/docs/ClangFormat.html
.. _`.clang-format`: ../../.clang-format
.. _`Utilities/Scripts/clang-format.bash`: ../../Utilities/Scripts/clang-format.bash
C++ Subset Permitted
====================
CMake supports compiling as C++98 in addition to C++11 and C++14.
In order to support building on older toolchains some constructs
need to be handled with care:
* Use ``CM_AUTO_PTR`` instead of ``std::auto_ptr``.
The ``std::auto_ptr`` template is deprecated in C++11. We want to use it
so we can build on C++98 compilers but we do not want to turn off compiler
warnings about deprecated interfaces in general. Use the ``CM_AUTO_PTR``
macro instead.
* Use ``CM_EQ_DELETE;`` instead of ``= delete;``.
Defining functions as *deleted* is not supported in C++98. Using
``CM_EQ_DELETE`` will delete the functions if the compiler supports it and
give them no implementation otherwise. Calling such a function will lead
to compiler errors if the compiler supports *deleted* functions and linker
errors otherwise.
* Use ``CM_DISABLE_COPY(Class)`` to mark classes as non-copyable.
The ``CM_DISABLE_COPY`` macro should be used in the private section of a
class to make sure that attempts to copy or assign an instance of the class
lead to compiler errors even if the compiler does not support *deleted*
functions. As a guideline, all polymorphic classes should be made
non-copyable in order to avoid slicing. Classes that are composed of or
derived from non-copyable classes must also be made non-copyable explicitly
with ``CM_DISABLE_COPY``.
* Use ``size_t`` instead of ``std::size_t``.
Various implementations have differing implementation of ``size_t``.
When assigning the result of ``.size()`` on a container for example,
the result should be assigned to ``size_t`` not to ``std::size_t``,
``unsigned int`` or similar types.

42
Help/dev/testing.rst Normal file
View File

@ -0,0 +1,42 @@
CMake Testing Process
*********************
The following documents the process for running integration testing builds.
See documentation on `CMake Development`_ for more information.
.. _`CMake Development`: README.rst
CMake Dashboard Scripts
=======================
The *integration testing* step of the `CMake Review Process`_ uses a set of
testing machines that follow an integration branch on their own schedule to
drive testing and submit results to the `CMake CDash Page`_. Anyone is
welcome to provide testing machines in order to help keep support for their
platforms working.
The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive
nightly, continous, and experimental testing of CMake. Use the following
commands to set up a new integration testing client:
.. code-block:: console
$ mkdir -p ~/Dashboards
$ cd ~/Dashboards
$ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts
$ cd CMakeScripts
The ``cmake_common.cmake`` script contains comments at the top with
instructions to set up a testing client. As it instructs, create a
CTest script with local settings and include ``cmake_common.cmake``.
.. _`CMake Review Process`: review.rst
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
.. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts
Nightly Start Time
------------------
The ``cmake_common.cmake`` script expects its includer to be run from a
nightly scheduled task (cron job). Schedule such tasks for sometime after
``1:00am UTC``, the time at which our nightly testing branches fast-forward.

8
Help/generator/VS_TOOLSET_HOST_ARCH.txt
View File

@ -2,9 +2,5 @@ For each toolset that comes with this version of Visual Studio, there are
variants that are themselves compiled for 32-bit (x86) and 64-bit (x64) hosts
(independent of the architecture they target). By default Visual Studio
chooses the 32-bit variant even on a 64-bit host. One may request use of the
64-bit host tools by adding ``host=x64`` to the toolset specification:
``host=x64``
Select the 64-bit variant of the default toolset.
``<toolset>,host=x64``
Select the 64-bit variant of the ``<toolset>`` toolset.
64-bit host tools by adding a ``host=x64`` option to the toolset specification.
See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details.

12
Help/generator/Visual Studio 15 2017.rst
View File

@ -15,6 +15,18 @@ a target platform name optionally at the end of this generator name:
``Visual Studio 15 2017 ARM``
Specify target platform ``ARM``.
Instance Selection
^^^^^^^^^^^^^^^^^^
VS 2017 supports multiple installations on the same machine.
CMake queries the Visual Studio Installer to locate VS instances.
If more than one instance is installed we do not define which one
is chosen by default. If the ``VS150COMNTOOLS`` environment variable
is set and points to the ``Common7/Tools`` directory within one of
the instances, that instance will be used. The environment variable
must remain consistently set whenever CMake is re-run within a given
build tree.
Toolset Selection
^^^^^^^^^^^^^^^^^

10
Help/generator/Visual Studio 7 .NET 2003.rst
View File

@ -1,10 +1,6 @@
Visual Studio 7 .NET 2003
-------------------------
Deprecated. Generates Visual Studio .NET 2003 project files.
.. note::
This generator is deprecated and will be removed
in a future version of CMake. It will still be
possible to build with VS 7.1 tools using the
:generator:`NMake Makefiles` generator.
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 :generator:`NMake Makefiles` generator.

9
Help/generator/Visual Studio 8 2005.rst
View File

@ -1,7 +1,14 @@
Visual Studio 8 2005
--------------------
Generates Visual Studio 8 2005 project files.
Deprecated. Generates Visual Studio 8 2005 project files.
.. note::
This generator is deprecated and will be removed in a future version
of CMake. It will still be possible to build with VS 8 2005 tools
using the :generator:`Visual Studio 10 2010` (or above) generator
with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v80``, or by
using the :generator:`NMake Makefiles` generator.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
to specify a target platform name.

2
Help/generator/Xcode.rst
View File

@ -3,6 +3,8 @@ Xcode
Generate Xcode project files.
This supports Xcode 3.0 and above.
Toolset Selection
^^^^^^^^^^^^^^^^^

24
Help/manual/OPTIONS_BUILD.txt
View File

@ -48,31 +48,19 @@
build system. Possible generator names are specified in the
:manual:`cmake-generators(7)` manual.
``-T <toolset-name>``
Specify toolset name if supported by generator.
``-T <toolset-spec>``
Toolset specification for the generator, if supported.
Some CMake generators support a toolset name to be given to the
native build system to choose a compiler.
See the :variable:`CMAKE_GENERATOR_TOOLSET` variable.
This is supported only on specific generators:
* :ref:`Visual Studio Generators` for VS 2010 and above
* The :generator:`Xcode` generator for Xcode 3.0 and above
See native build system documentation for allowed toolset names.
Some CMake generators support a toolset specification to tell
the native build system how to choose a compiler. See the
:variable:`CMAKE_GENERATOR_TOOLSET` variable for details.
``-A <platform-name>``
Specify platform name if supported by generator.
Some CMake generators support a platform name to be given to the
native build system to choose a compiler or SDK. See the
:variable:`CMAKE_GENERATOR_PLATFORM` variable.
This is supported only on specific generators:
* For :ref:`Visual Studio Generators` with VS 2005 and above this
specifies the target architecture.
See native build system documentation for allowed platform names.
:variable:`CMAKE_GENERATOR_PLATFORM` variable for details.
``-Wno-dev``
Suppress developer warnings.

12
Help/manual/cmake-buildsystem.7.rst
View File

@ -125,10 +125,10 @@ The object files collection can be used as source inputs to other targets:
add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
``OBJECT`` libraries may only be used locally as sources in a buildsystem --
they may not be installed, exported, or used in the right hand side of
``OBJECT`` libraries may not be used in the right hand side of
:command:`target_link_libraries`. They also may not be used as the ``TARGET``
in a use of the :command:`add_custom_command(TARGET)` command signature.
in a use of the :command:`add_custom_command(TARGET)` command signature. They
may be installed, and will be exported as an INTERFACE library.
Although object libraries may not be named directly in calls to
the :command:`target_link_libraries` command, they can be "linked"
@ -136,6 +136,12 @@ indirectly by using an :ref:`Interface Library <Interface Libraries>`
whose :prop_tgt:`INTERFACE_SOURCES` target property is set to name
``$<TARGET_OBJECTS:objlib>``.
Although object libraries may not be used as the ``TARGET``
in a use of the :command:`add_custom_command(TARGET)` command signature,
the list of objects can be used by :command:`add_custom_command(OUTPUT)` or
:command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``.
Build Specification and Usage Requirements
==========================================

153
Help/manual/cmake-commands.7.rst
View File

@ -7,10 +7,64 @@ cmake-commands(7)
.. contents::
Normal Commands
===============
Scripting Commands
==================
These commands may be used freely in CMake projects.
These commands are always available.
.. toctree::
:maxdepth: 1
/command/break
/command/cmake_host_system_information
/command/cmake_minimum_required
/command/cmake_parse_arguments
/command/cmake_policy
/command/configure_file
/command/continue
/command/elseif
/command/else
/command/endforeach
/command/endfunction
/command/endif
/command/endmacro
/command/endwhile
/command/execute_process
/command/file
/command/find_file
/command/find_library
/command/find_package
/command/find_path
/command/find_program
/command/foreach
/command/function
/command/get_cmake_property
/command/get_directory_property
/command/get_filename_component
/command/get_property
/command/if
/command/include
/command/list
/command/macro
/command/mark_as_advanced
/command/math
/command/message
/command/option
/command/return
/command/separate_arguments
/command/set_directory_properties
/command/set_property
/command/set
/command/site_name
/command/string
/command/unset
/command/variable_watch
/command/while
Project Commands
================
These commands are available only in CMake projects.
.. toctree::
:maxdepth: 1
@ -25,73 +79,31 @@ These commands may be used freely in CMake projects.
/command/add_subdirectory
/command/add_test
/command/aux_source_directory
/command/break
/command/build_command
/command/cmake_host_system_information
/command/cmake_minimum_required
/command/cmake_parse_arguments
/command/cmake_policy
/command/configure_file
/command/continue
/command/create_test_sourcelist
/command/define_property
/command/elseif
/command/else
/command/enable_language
/command/enable_testing
/command/endforeach
/command/endfunction
/command/endif
/command/endmacro
/command/endwhile
/command/execute_process
/command/export
/command/file
/command/find_file
/command/find_library
/command/find_package
/command/find_path
/command/find_program
/command/fltk_wrap_ui
/command/foreach
/command/function
/command/get_cmake_property
/command/get_directory_property
/command/get_filename_component
/command/get_property
/command/get_source_file_property
/command/get_target_property
/command/get_test_property
/command/if
/command/include_directories
/command/include_external_msproject
/command/include_regular_expression
/command/include
/command/install
/command/link_directories
/command/link_libraries
/command/list
/command/load_cache
/command/macro
/command/mark_as_advanced
/command/math
/command/message
/command/option
/command/project
/command/qt_wrap_cpp
/command/qt_wrap_ui
/command/remove_definitions
/command/return
/command/separate_arguments
/command/set_directory_properties
/command/set_property
/command/set
/command/set_source_files_properties
/command/set_target_properties
/command/set_tests_properties
/command/site_name
/command/source_group
/command/string
/command/target_compile_definitions
/command/target_compile_features
/command/target_compile_options
@ -100,9 +112,30 @@ These commands may be used freely in CMake projects.
/command/target_sources
/command/try_compile
/command/try_run
/command/unset
/command/variable_watch
/command/while
.. _`CTest Commands`:
CTest Commands
==============
These commands are available only in CTest scripts.
.. toctree::
:maxdepth: 1
/command/ctest_build
/command/ctest_configure
/command/ctest_coverage
/command/ctest_empty_binary_directory
/command/ctest_memcheck
/command/ctest_read_custom_files
/command/ctest_run_script
/command/ctest_sleep
/command/ctest_start
/command/ctest_submit
/command/ctest_test
/command/ctest_update
/command/ctest_upload
Deprecated Commands
===================
@ -129,27 +162,3 @@ versions of CMake. Do not use them in new code.
/command/utility_source
/command/variable_requires
/command/write_file
.. _`CTest Commands`:
CTest Commands
==============
These commands are available only in ctest scripts.
.. toctree::
:maxdepth: 1
/command/ctest_build
/command/ctest_configure
/command/ctest_coverage
/command/ctest_empty_binary_directory
/command/ctest_memcheck
/command/ctest_read_custom_files
/command/ctest_run_script
/command/ctest_sleep
/command/ctest_start
/command/ctest_submit
/command/ctest_test
/command/ctest_update
/command/ctest_upload

22
Help/manual/cmake-compile-features.7.rst
View File

@ -334,8 +334,8 @@ versions specified for each:
* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 6.2.
* ``Clang``: Clang compiler versions 2.9 through 3.4.
* ``GNU``: GNU compiler versions 4.4 through 5.0.
* ``MSVC``: Microsoft Visual Studio versions 2010 through 2015.
* ``SunPro``: Oracle SolarisStudio version 12.4.
* ``MSVC``: Microsoft Visual Studio versions 2010 through 2017.
* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.5.
* ``Intel``: Intel compiler versions 12.1 through 17.0.
CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>`
@ -343,9 +343,25 @@ and :prop_gbl:`compile features <CMAKE_C_KNOWN_FEATURES>` available from
the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the
versions specified for each:
* all compilers and versions listed above for C++
* all compilers and versions listed above for C++.
* ``GNU``: GNU compiler versions 3.4 through 5.0.
CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and
their associated meta-features (e.g. ``cxx_std_11``) available from the
following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the
versions specified for each:
* ``Cray``: Cray Compiler Environment version 8.1 through 8.5.8.
* ``PGI``: PGI version 12.10 through 17.5.
* ``XL``: IBM XL version 10.1 through 13.1.5.
CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and
their associated meta-features (e.g. ``c_std_99``) available from the
following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the
versions specified for each:
* all compilers and versions listed above with only meta-features for C++.
CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>`
from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the
versions specified for each:

24
Help/manual/cmake-developer.7.rst
View File

@ -13,30 +13,6 @@ Introduction
This manual is intended for reference by developers modifying the CMake
source tree itself, and by those authoring externally-maintained modules.
Permitted C++ Subset
====================
CMake is required to build with ancient C++ compilers and standard library
implementations. Some common C++ constructs may not be used in CMake in order
to build with such toolchains.
std::auto_ptr
-------------
The ``std::auto_ptr`` template is deprecated in C++11. We want to use it
so we can build on C++98 compilers but we do not want to turn off compiler
warnings about deprecated interfaces in general. Use the ``CM_AUTO_PTR``
macro instead.
size_t
------
Various implementations have differing implementation of ``size_t``. When
assigning the result of ``.size()`` on a container for example, the result
should be assigned to ``size_t`` not to ``std::size_t``, ``unsigned int`` or
similar types.
Adding Compile Features
=======================

15
Help/manual/cmake-generator-expressions.7.rst
View File

@ -117,7 +117,7 @@ Available logical expressions are:
.. code-block:: cmake
add_library(myapp_c foo.c)
add_library(myapp_cxx 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)
@ -205,6 +205,15 @@ Available informational expressions are:
Name of the linker generated program database file (.pdb).
``$<TARGET_PDB_FILE_DIR:tgt>``
Directory of the linker generated program database file (.pdb).
``$<TARGET_BUNDLE_DIR:tgt>``
Full path to the bundle directory (``my.app``, ``my.framework``, or
``my.bundle``) where ``tgt`` is the name of a target.
``$<TARGET_BUNDLE_CONTENT_DIR:tgt>``
Full path to the bundle content directory where ``tgt`` is the name of a
target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``,
or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to
``my.app``, ``my.framework``, or ``my.bundle`` due to the flat bundle
structure.
``$<TARGET_PROPERTY:tgt,prop>``
Value of the property ``prop`` on the target ``tgt``.
@ -281,9 +290,7 @@ Available output expressions are:
Content of ``...`` converted to a C identifier.
``$<TARGET_OBJECTS:objLib>``
List of objects resulting from build of ``objLib``. ``objLib`` must be an
object of type ``OBJECT_LIBRARY``. This expression may only be used in
the sources of :command:`add_library` and :command:`add_executable`
commands.
object of type ``OBJECT_LIBRARY``.
``$<SHELL_PATH:...>``
Content of ``...`` converted to shell path style. For example, slashes are
converted to backslashes in Windows shells and drive letters are converted

3
Help/manual/cmake-modules.7.rst
View File

@ -27,6 +27,7 @@ All Modules
/module/CheckFortranFunctionExists
/module/CheckFortranSourceCompiles
/module/CheckFunctionExists
/module/CheckIPOSupported
/module/CheckIncludeFileCXX
/module/CheckIncludeFile
/module/CheckIncludeFiles
@ -53,6 +54,7 @@ All Modules
/module/CMakePrintSystemInformation
/module/CMakePushCheckState
/module/CMakeVerifyManifest
/module/CPackArchive
/module/CPackBundle
/module/CPackComponent
/module/CPackCygwin
@ -229,6 +231,7 @@ All Modules
/module/GenerateExportHeader
/module/GetPrerequisites
/module/GNUInstallDirs
/module/GoogleTest
/module/InstallRequiredSystemLibraries
/module/MacroAddFileDependencies
/module/ProcessorCount

9
Help/manual/cmake-policies.7.rst
View File

@ -51,6 +51,15 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
to determine whether to report an error on use of deprecated macros or
functions.
Policies Introduced by CMake 3.9
================================
.. toctree::
:maxdepth: 1
CMP0069: INTERPROCEDURAL_OPTIMIZATION is enforced when enabled. </policy/CMP0069>
CMP0068: RPATH settings on macOS do not affect install_name. </policy/CMP0068>
Policies Introduced by CMake 3.8
================================

14
Help/manual/cmake-properties.7.rst
View File

@ -16,8 +16,11 @@ Properties of Global Scope
:maxdepth: 1
/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS
/prop_gbl/AUTOGEN_SOURCE_GROUP
/prop_gbl/AUTOGEN_TARGETS_FOLDER
/prop_gbl/AUTOMOC_SOURCE_GROUP
/prop_gbl/AUTOMOC_TARGETS_FOLDER
/prop_gbl/AUTORCC_SOURCE_GROUP
/prop_gbl/CMAKE_C_KNOWN_FEATURES
/prop_gbl/CMAKE_CXX_KNOWN_FEATURES
/prop_gbl/DEBUG_CONFIGURATIONS
@ -26,7 +29,9 @@ Properties of Global Scope
/prop_gbl/ENABLED_LANGUAGES
/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS
/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS
/prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS
/prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING
/prop_gbl/GENERATOR_IS_MULTI_CONFIG
/prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE
/prop_gbl/GLOBAL_DEPENDS_NO_CYCLES
/prop_gbl/IN_TRY_COMPILE
@ -114,15 +119,19 @@ Properties on Targets
/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY
/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG
/prop_tgt/ARCHIVE_OUTPUT_NAME
/prop_tgt/AUTOGEN_BUILD_DIR
/prop_tgt/AUTOGEN_TARGET_DEPENDS
/prop_tgt/AUTOMOC_DEPEND_FILTERS
/prop_tgt/AUTOMOC_MOC_OPTIONS
/prop_tgt/AUTOMOC
/prop_tgt/AUTOUIC
/prop_tgt/AUTOUIC_OPTIONS
/prop_tgt/AUTOUIC_SEARCH_PATHS
/prop_tgt/AUTORCC
/prop_tgt/AUTORCC_OPTIONS
/prop_tgt/BINARY_DIR
/prop_tgt/BUILD_RPATH
/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR
/prop_tgt/BUILD_WITH_INSTALL_RPATH
/prop_tgt/BUNDLE_EXTENSION
/prop_tgt/BUNDLE
@ -144,7 +153,9 @@ Properties on Targets
/prop_tgt/CONFIG_OUTPUT_NAME
/prop_tgt/CONFIG_POSTFIX
/prop_tgt/CROSSCOMPILING_EMULATOR
/prop_tgt/CUDA_PTX_COMPILATION
/prop_tgt/CUDA_SEPARABLE_COMPILATION
/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS
/prop_tgt/CUDA_EXTENSIONS
/prop_tgt/CUDA_STANDARD
/prop_tgt/CUDA_STANDARD_REQUIRED
@ -186,6 +197,8 @@ Properties on Targets
/prop_tgt/IMPORTED_LOCATION
/prop_tgt/IMPORTED_NO_SONAME_CONFIG
/prop_tgt/IMPORTED_NO_SONAME
/prop_tgt/IMPORTED_OBJECTS_CONFIG
/prop_tgt/IMPORTED_OBJECTS
/prop_tgt/IMPORTED
/prop_tgt/IMPORTED_SONAME_CONFIG
/prop_tgt/IMPORTED_SONAME
@ -318,6 +331,7 @@ Properties on Tests
/prop_test/ATTACHED_FILES
/prop_test/COST
/prop_test/DEPENDS
/prop_test/DISABLED
/prop_test/ENVIRONMENT
/prop_test/FAIL_REGULAR_EXPRESSION
/prop_test/FIXTURES_CLEANUP

37
Help/manual/cmake-qt.7.rst
View File

@ -63,26 +63,37 @@ If a ``Q_OBJECT`` or ``Q_GADGET`` macro is found in a header file, ``moc``
will be run on the file. The result will be put into a file named according
to ``moc_<basename>.cpp``. If the macro is found in a C++ implementation
file, the moc output will be put into a file named according to
``<basename>.moc``, following the Qt conventions. The ``moc file`` may be
included by the user in the C++ implementation file with a preprocessor
``#include``. If it is not so included, it will be added to a separate file
which is compiled into the target.
``<basename>.moc``, following the Qt conventions. The ``<basename>.moc`` must
be included by the user in the C++ implementation file with a preprocessor
``#include``.
Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the
``<AUTOGEN_BUILD_DIR>/include`` directory which is
automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
(This differs from CMake 3.7 and below; see their documentation for details.)
* See :prop_tgt:`AUTOGEN_BUILD_DIR`.
Not included ``moc_<basename>.cpp`` files will be generated in custom
folders to avoid name collisions and included in a separate
``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` file which is compiled
into the target.
* See :prop_tgt:`AUTOGEN_BUILD_DIR`.
The ``moc`` command line will consume the :prop_tgt:`COMPILE_DEFINITIONS` and
:prop_tgt:`INCLUDE_DIRECTORIES` target properties from the target it is being
invoked for, and for the appropriate build configuration.
The generated ``moc_*.cpp`` and ``*.moc`` files are placed in the
``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which is
automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
(This differs from CMake 3.7 and below; see their documentation for details.)
The :prop_tgt:`AUTOMOC` target property may be pre-set for all
following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The
:prop_tgt:`AUTOMOC_MOC_OPTIONS` target property may be populated to set
options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS`
variable may be populated to pre-set the options for all following targets.
Additional ``moc`` dependency file names can be extracted from source code
by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`.
Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by
enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`.
@ -97,13 +108,17 @@ be run, and to create rules to execute ``uic`` at the appropriate time.
If a preprocessor ``#include`` directive is found which matches
``ui_<basename>.h``, and a ``<basename>.ui`` file exists, then ``uic`` will
be executed to generate the appropriate file.
be executed to generate the appropriate file. The ``<basename>.ui`` file is
searched for first in the vicinity of including file and afterwards in the
optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target.
The generated generated ``ui_*.h`` files are placed in the
``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which is
``<AUTOGEN_BUILD_DIR>/include`` directory which is
automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
(This differs from CMake 3.7 and below; see their documentation for details.)
* See :prop_tgt:`AUTOGEN_BUILD_DIR`.
The :prop_tgt:`AUTOUIC` target property may be pre-set for all following
targets by setting the :variable:`CMAKE_AUTOUIC` variable. The
:prop_tgt:`AUTOUIC_OPTIONS` target property may be populated to set options

5
Help/manual/cmake-toolchains.7.rst
View File

@ -385,6 +385,11 @@ Configure use of an Android NDK with the following variables:
If not specified, a default for this variable will be chosen
as specified :ref:`above <Cross Compiling for Android>`.
:variable:`CMAKE_ANDROID_NDK_DEPRECATED_HEADERS`
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.
:variable:`CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION`
Set 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.

68
Help/manual/cmake-variables.7.rst
View File

@ -13,9 +13,9 @@ Variables that Provide Information
.. toctree::
:maxdepth: 1
/variable/CMAKE_AR
/variable/CMAKE_ARGC
/variable/CMAKE_ARGV0
/variable/CMAKE_AR
/variable/CMAKE_BINARY_DIR
/variable/CMAKE_BUILD_TOOL
/variable/CMAKE_CACHEFILE_DIR
@ -48,16 +48,20 @@ Variables that Provide Information
/variable/CMAKE_IMPORT_LIBRARY_SUFFIX
/variable/CMAKE_JOB_POOL_COMPILE
/variable/CMAKE_JOB_POOL_LINK
/variable/CMAKE_LANG_COMPILER_AR
/variable/CMAKE_LANG_COMPILER_RANLIB
/variable/CMAKE_LINK_LIBRARY_SUFFIX
/variable/CMAKE_LINK_SEARCH_END_STATIC
/variable/CMAKE_LINK_SEARCH_START_STATIC
/variable/CMAKE_MAJOR_VERSION
/variable/CMAKE_MAKE_PROGRAM
/variable/CMAKE_MATCH_COUNT
/variable/CMAKE_MATCH_n
/variable/CMAKE_MINIMUM_REQUIRED_VERSION
/variable/CMAKE_MINOR_VERSION
/variable/CMAKE_PARENT_LIST_FILE
/variable/CMAKE_PATCH_VERSION
/variable/CMAKE_PROJECT_DESCRIPTION
/variable/CMAKE_PROJECT_NAME
/variable/CMAKE_RANLIB
/variable/CMAKE_ROOT
@ -82,18 +86,21 @@ Variables that Provide Information
/variable/CMAKE_VS_NsightTegra_VERSION
/variable/CMAKE_VS_PLATFORM_NAME
/variable/CMAKE_VS_PLATFORM_TOOLSET
/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA
/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
/variable/CMAKE_XCODE_GENERATE_SCHEME
/variable/CMAKE_XCODE_PLATFORM_TOOLSET
/variable/PROJECT_BINARY_DIR
/variable/PROJECT-NAME_BINARY_DIR
/variable/PROJECT_NAME
/variable/PROJECT-NAME_SOURCE_DIR
/variable/PROJECT-NAME_VERSION
/variable/PROJECT-NAME_VERSION_MAJOR
/variable/PROJECT-NAME_VERSION_MINOR
/variable/PROJECT-NAME_VERSION_PATCH
/variable/PROJECT-NAME_VERSION_TWEAK
/variable/PROJECT_BINARY_DIR
/variable/PROJECT_DESCRIPTION
/variable/PROJECT_NAME
/variable/PROJECT_SOURCE_DIR
/variable/PROJECT_VERSION
/variable/PROJECT_VERSION_MAJOR
@ -127,9 +134,9 @@ Variables that Change Behavior
/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
/variable/CMAKE_EXPORT_COMPILE_COMMANDS
/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY
/variable/CMAKE_SYSROOT
/variable/CMAKE_FIND_APPBUNDLE
/variable/CMAKE_FIND_FRAMEWORK
/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX
/variable/CMAKE_FIND_LIBRARY_PREFIXES
/variable/CMAKE_FIND_LIBRARY_SUFFIXES
/variable/CMAKE_FIND_NO_INSTALL_PREFIX
@ -143,9 +150,9 @@ Variables that Change Behavior
/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
/variable/CMAKE_FRAMEWORK_PATH
/variable/CMAKE_IGNORE_PATH
/variable/CMAKE_INCLUDE_PATH
/variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE
/variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE
/variable/CMAKE_INCLUDE_PATH
/variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
/variable/CMAKE_INSTALL_MESSAGE
/variable/CMAKE_INSTALL_PREFIX
@ -163,6 +170,9 @@ Variables that Change Behavior
/variable/CMAKE_STAGING_PREFIX
/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
/variable/CMAKE_SYSROOT
/variable/CMAKE_SYSROOT_COMPILE
/variable/CMAKE_SYSROOT_LINK
/variable/CMAKE_SYSTEM_APPBUNDLE_PATH
/variable/CMAKE_SYSTEM_FRAMEWORK_PATH
/variable/CMAKE_SYSTEM_IGNORE_PATH
@ -187,23 +197,24 @@ Variables that Describe the System
/variable/CMAKE_COMPILER_2005
/variable/CMAKE_HOST_APPLE
/variable/CMAKE_HOST_SOLARIS
/variable/CMAKE_HOST_SYSTEM
/variable/CMAKE_HOST_SYSTEM_NAME
/variable/CMAKE_HOST_SYSTEM_PROCESSOR
/variable/CMAKE_HOST_SYSTEM
/variable/CMAKE_HOST_SYSTEM_VERSION
/variable/CMAKE_HOST_UNIX
/variable/CMAKE_HOST_WIN32
/variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX
/variable/CMAKE_LIBRARY_ARCHITECTURE
/variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX
/variable/CMAKE_OBJECT_PATH_MAX
/variable/CMAKE_SYSTEM
/variable/CMAKE_SYSTEM_NAME
/variable/CMAKE_SYSTEM_PROCESSOR
/variable/CMAKE_SYSTEM
/variable/CMAKE_SYSTEM_VERSION
/variable/CYGWIN
/variable/ENV
/variable/GHS-MULTI
/variable/MINGW
/variable/MSVC
/variable/MSVC10
/variable/MSVC11
/variable/MSVC12
@ -214,7 +225,6 @@ Variables that Describe the System
/variable/MSVC80
/variable/MSVC90
/variable/MSVC_IDE
/variable/MSVC
/variable/MSVC_VERSION
/variable/UNIX
/variable/WIN32
@ -245,6 +255,7 @@ Variables that Control the Build
/variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES
/variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES
/variable/CMAKE_ANDROID_NDK
/variable/CMAKE_ANDROID_NDK_DEPRECATED_HEADERS
/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG
/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
/variable/CMAKE_ANDROID_PROCESS_MAX
@ -256,31 +267,36 @@ Variables that Control the Build
/variable/CMAKE_ANDROID_STL_TYPE
/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY
/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_AUTOMOC_MOC_OPTIONS
/variable/CMAKE_AUTOMOC
/variable/CMAKE_AUTOMOC_DEPEND_FILTERS
/variable/CMAKE_AUTOMOC_MOC_OPTIONS
/variable/CMAKE_AUTORCC
/variable/CMAKE_AUTORCC_OPTIONS
/variable/CMAKE_AUTOUIC
/variable/CMAKE_AUTOUIC_OPTIONS
/variable/CMAKE_AUTOUIC_SEARCH_PATHS
/variable/CMAKE_BUILD_RPATH
/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR
/variable/CMAKE_BUILD_WITH_INSTALL_RPATH
/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_CONFIG_POSTFIX
/variable/CMAKE_DEBUG_POSTFIX
/variable/CMAKE_ENABLE_EXPORTS
/variable/CMAKE_EXE_LINKER_FLAGS
/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG
/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT
/variable/CMAKE_EXE_LINKER_FLAGS
/variable/CMAKE_EXE_LINKER_FLAGS_INIT
/variable/CMAKE_Fortran_FORMAT
/variable/CMAKE_Fortran_MODULE_DIRECTORY
/variable/CMAKE_GNUtoMS
/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE
/variable/CMAKE_INCLUDE_CURRENT_DIR
/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE
/variable/CMAKE_INSTALL_NAME_DIR
/variable/CMAKE_INSTALL_RPATH
/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH
/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION
/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG
/variable/CMAKE_IOS_INSTALL_COMBINED
/variable/CMAKE_LANG_CLANG_TIDY
/variable/CMAKE_LANG_COMPILER_LAUNCHER
@ -299,9 +315,9 @@ Variables that Control the Build
/variable/CMAKE_MACOSX_BUNDLE
/variable/CMAKE_MACOSX_RPATH
/variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG
/variable/CMAKE_MODULE_LINKER_FLAGS
/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG
/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT
/variable/CMAKE_MODULE_LINKER_FLAGS
/variable/CMAKE_MODULE_LINKER_FLAGS_INIT
/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX
/variable/CMAKE_NO_BUILTIN_CHRPATH
@ -314,15 +330,15 @@ Variables that Control the Build
/variable/CMAKE_POSITION_INDEPENDENT_CODE
/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY
/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_SHARED_LINKER_FLAGS
/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG
/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT
/variable/CMAKE_SHARED_LINKER_FLAGS
/variable/CMAKE_SHARED_LINKER_FLAGS_INIT
/variable/CMAKE_SKIP_BUILD_RPATH
/variable/CMAKE_SKIP_INSTALL_RPATH
/variable/CMAKE_STATIC_LINKER_FLAGS
/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG
/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT
/variable/CMAKE_STATIC_LINKER_FLAGS
/variable/CMAKE_STATIC_LINKER_FLAGS_INIT
/variable/CMAKE_TRY_COMPILE_CONFIGURATION
/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
@ -331,8 +347,8 @@ Variables that Control the Build
/variable/CMAKE_VISIBILITY_INLINES_HIDDEN
/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD
/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
/variable/CMAKE_WIN32_EXECUTABLE
/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute
/variable/EXECUTABLE_OUTPUT_PATH
/variable/LIBRARY_OUTPUT_PATH
@ -346,10 +362,6 @@ Variables for Languages
/variable/CMAKE_COMPILER_IS_GNUCC
/variable/CMAKE_COMPILER_IS_GNUCXX
/variable/CMAKE_COMPILER_IS_GNUG77
/variable/CMAKE_C_COMPILE_FEATURES
/variable/CMAKE_C_EXTENSIONS
/variable/CMAKE_C_STANDARD
/variable/CMAKE_C_STANDARD_REQUIRED
/variable/CMAKE_CUDA_EXTENSIONS
/variable/CMAKE_CUDA_STANDARD
/variable/CMAKE_CUDA_STANDARD_REQUIRED
@ -358,6 +370,10 @@ Variables for Languages
/variable/CMAKE_CXX_EXTENSIONS
/variable/CMAKE_CXX_STANDARD
/variable/CMAKE_CXX_STANDARD_REQUIRED
/variable/CMAKE_C_COMPILE_FEATURES
/variable/CMAKE_C_EXTENSIONS
/variable/CMAKE_C_STANDARD
/variable/CMAKE_C_STANDARD_REQUIRED
/variable/CMAKE_Fortran_MODDIR_DEFAULT
/variable/CMAKE_Fortran_MODDIR_FLAG
/variable/CMAKE_Fortran_MODOUT_FLAG
@ -368,27 +384,27 @@ Variables for Languages
/variable/CMAKE_LANG_ARCHIVE_APPEND
/variable/CMAKE_LANG_ARCHIVE_CREATE
/variable/CMAKE_LANG_ARCHIVE_FINISH
/variable/CMAKE_LANG_COMPILE_OBJECT
/variable/CMAKE_LANG_COMPILER
/variable/CMAKE_LANG_COMPILER_ABI
/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN
/variable/CMAKE_LANG_COMPILER_ID
/variable/CMAKE_LANG_COMPILER_LOADED
/variable/CMAKE_LANG_COMPILER
/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN
/variable/CMAKE_LANG_COMPILER_TARGET
/variable/CMAKE_LANG_COMPILER_VERSION
/variable/CMAKE_LANG_COMPILE_OBJECT
/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY
/variable/CMAKE_LANG_CREATE_SHARED_MODULE
/variable/CMAKE_LANG_CREATE_STATIC_LIBRARY
/variable/CMAKE_LANG_FLAGS
/variable/CMAKE_LANG_FLAGS_DEBUG
/variable/CMAKE_LANG_FLAGS_DEBUG_INIT
/variable/CMAKE_LANG_FLAGS_INIT
/variable/CMAKE_LANG_FLAGS_MINSIZEREL
/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT
/variable/CMAKE_LANG_FLAGS_RELEASE
/variable/CMAKE_LANG_FLAGS_RELEASE_INIT
/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO
/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT
/variable/CMAKE_LANG_FLAGS
/variable/CMAKE_LANG_FLAGS_INIT
/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG
/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL
/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE
@ -399,8 +415,8 @@ Variables for Languages
/variable/CMAKE_LANG_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES
/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES
/variable/CMAKE_LANG_LIBRARY_ARCHITECTURE
/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES
/variable/CMAKE_LANG_LINKER_PREFERENCE
/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES
/variable/CMAKE_LANG_LINK_EXECUTABLE
/variable/CMAKE_LANG_OUTPUT_EXTENSION
/variable/CMAKE_LANG_PLATFORM_ID

5
Help/manual/cmake.1.rst
View File

@ -227,7 +227,7 @@ Available commands are:
``copy <file>... <destination>``
Copy files to ``<destination>`` (either file or directory).
If multiple files are specified, the ``<destination>`` must be
directory and it must exist.
directory and it must exist. Wildcards are not supported.
``copy_directory <dir>... <destination>``
Copy directories to ``<destination>`` directory.
@ -317,6 +317,9 @@ The following ``cmake -E`` commands are available only on UNIX:
``create_symlink <old> <new>``
Create a symbolic link ``<new>`` naming ``<old>``.
.. note::
Path to where ``<new>`` symbolic link will be created has to exist beforehand.
Windows-specific Command-Line Tools
-----------------------------------

17
Help/manual/ctest.1.rst
View File

@ -117,6 +117,23 @@ Options
This option tells ctest to NOT run the tests whose labels match the
given regular expression.
``-FA <regex>, --fixture-exclude-any <regex>``
Exclude fixtures matching ``<regex>`` from automatically adding any tests to
the test set.
If a test in the set of tests to be executed requires a particular fixture,
that fixture's setup and cleanup tests would normally be added to the test set
automatically. This option prevents adding setup or cleanup tests for fixtures
matching the ``<regex>``. Note that all other fixture behavior is retained,
including test dependencies and skipping tests that have fixture setup tests
that fail.
``-FS <regex>, --fixture-exclude-setup <regex>``
Same as ``-FA`` except only matching setup tests are excluded.
``-FC <regex>, --fixture-exclude-cleanup <regex>``
Same as ``-FA`` except only matching cleanup tests are excluded.
``-D <dashboard>, --dashboard <dashboard>``
Execute dashboard test.

1
Help/module/CPackArchive.rst Normal file
View File

@ -0,0 +1 @@
.. cmake-module:: ../../Modules/CPackArchive.cmake

1
Help/module/CheckIPOSupported.rst Normal file
View File

@ -0,0 +1 @@
.. cmake-module:: ../../Modules/CheckIPOSupported.cmake

1
Help/module/GoogleTest.rst Normal file
View File

@ -0,0 +1 @@
.. cmake-module:: ../../Modules/GoogleTest.cmake

35
Help/policy/CMP0068.rst Normal file
View File

@ -0,0 +1,35 @@
CMP0068
-------
``RPATH`` settings on macOS do not affect ``install_name``.
CMake 3.9 and newer remove any effect the following settings may have on the
``install_name`` of a target on macOS:
* :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property
* :prop_tgt:`SKIP_BUILD_RPATH` target property
* :variable:`CMAKE_SKIP_RPATH` variable
* :variable:`CMAKE_SKIP_INSTALL_RPATH` variable
Previously, setting :prop_tgt:`BUILD_WITH_INSTALL_RPATH` had the effect of
setting both the ``install_name`` of a target to :prop_tgt:`INSTALL_NAME_DIR`
and the ``RPATH`` to :prop_tgt:`INSTALL_RPATH`. In CMake 3.9, it only affects
setting of ``RPATH``. However, if one wants :prop_tgt:`INSTALL_NAME_DIR` to
apply to the target in the build tree, one may set
:prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR`.
If :prop_tgt:`SKIP_BUILD_RPATH`, :variable:`CMAKE_SKIP_RPATH` or
:variable:`CMAKE_SKIP_INSTALL_RPATH` were used to strip the directory portion
of the ``install_name`` of a target, one may set ``INSTALL_NAME_DIR=""``
instead.
The ``OLD`` behavior of this policy is to use the ``RPATH`` settings for
``install_name`` on macOS. The ``NEW`` behavior of this policy is to ignore
the ``RPATH`` settings for ``install_name`` on macOS.
This policy was introduced in CMake version 3.9. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior.
Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt

92
Help/policy/CMP0069.rst Normal file
View File

@ -0,0 +1,92 @@
CMP0069
-------
:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` is enforced when enabled.
CMake 3.9 and newer prefer to add IPO flags whenever the
:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is enabled and
produce an error if flags are not known to CMake for the current compiler.
Since a given compiler may not support IPO flags in all environments in which
it is used, it is now the project's responsibility to use the
:module:`CheckIPOSupported` module to check for support before enabling the
:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property. This approach
allows a project to conditionally activate IPO when supported. It also
allows an end user to set the :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION`
variable in an environment known to support IPO even if the project does
not enable the property.
Since CMake 3.8 and lower only honored :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`
for the Intel compiler on Linux, some projects may unconditionally enable the
target property. Policy ``CMP0069`` provides compatibility with such projects.
This policy takes effect whenever the IPO property is enabled. The ``OLD``
behavior for this policy is to add IPO flags only for Intel compiler on Linux.
The ``NEW`` behavior for this policy is to add IPO flags for the current
compiler or produce an error if CMake does not know the flags.
This policy was introduced in CMake version 3.9. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior.
Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt
Examples
^^^^^^^^
Behave like CMake 3.8 and do not apply any IPO flags except for Intel compiler
on Linux:
.. code-block:: cmake
cmake_minimum_required(VERSION 3.8)
project(foo)
# ...
set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
Use the :module:`CheckIPOSupported` module to detect whether IPO is
supported by the current compiler, environment, and CMake version.
Produce a fatal error if support is not available:
.. code-block:: cmake
cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
project(foo)
include(CheckIPOSupport)
check_ipo_support()
# ...
set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
Apply IPO flags only if compiler supports it:
.. code-block:: cmake
cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
project(foo)
include(CheckIPOSupport)
# ...
check_ipo_support(RESULT result)
if(result)
set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
endif()
Apply IPO flags without any checks. This may lead to build errors if IPO
is not supported by the compiler in the current environment. Produce an
error if CMake does not know IPO flags for the current compiler:
.. code-block:: cmake
cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
project(foo)
# ...
set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)

6
Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst
View File

@ -17,7 +17,7 @@ pairs. Each such pair will be transformed into an entry in the
solution global section. Whitespace around key and value is ignored.
List elements which do not contain an equal sign are skipped.
This property only works for Visual Studio 7 and above; it is ignored
This property only works for Visual Studio 8 and above; it is ignored
on other generators. The property only applies when set on a
directory whose CMakeLists.txt contains a project() command.
@ -26,4 +26,6 @@ and ExtensibilityAddIns by default. If you set the corresponding
property, it will override the default section. For example, setting
VS_GLOBAL_SECTION_POST_ExtensibilityGlobals will override the default
contents of the ExtensibilityGlobals section, while keeping
ExtensibilityAddIns on its default.
ExtensibilityAddIns on its default. However, CMake will always
add a ``SolutionGuid`` to the ``ExtensibilityGlobals`` section
if it is not specified explicitly.

2
Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst
View File

@ -17,6 +17,6 @@ pairs. Each such pair will be transformed into an entry in the
solution global section. Whitespace around key and value is ignored.
List elements which do not contain an equal sign are skipped.
This property only works for Visual Studio 7 and above; it is ignored
This property only works for Visual Studio 8 and above; it is ignored
on other generators. The property only applies when set on a
directory whose CMakeLists.txt contains a project() command.

15
Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst Normal file
View File

@ -0,0 +1,15 @@
AUTOGEN_SOURCE_GROUP
--------------------
Name of the :command:`source_group` for :prop_tgt:`AUTOMOC` and
:prop_tgt:`AUTORCC` generated files.
Files generated by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` are not always
known at configure time and therefore can't be passed to
:command:`source_group`.
:prop_gbl:`AUTOGEN_SOURCE_GROUP` an be used instead to generate or select
a source group for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` generated files.
For :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` specific overrides see
:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP`
respectively.

4
Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst
View File

@ -1,8 +1,8 @@
AUTOGEN_TARGETS_FOLDER
----------------------
Name of :prop_tgt:`FOLDER` for ``*_autogen`` targets that are added automatically by
CMake for targets for which :prop_tgt:`AUTOMOC` is enabled.
Name of :prop_tgt:`FOLDER` for ``*_autogen`` targets that are added
automatically by CMake for targets for which :prop_tgt:`AUTOMOC` is enabled.
If not set, CMake uses the :prop_tgt:`FOLDER` property of the parent target as a
default value for this property. See also the documentation for the

7
Help/prop_gbl/AUTOMOC_SOURCE_GROUP.rst Normal file
View File

@ -0,0 +1,7 @@
AUTOMOC_SOURCE_GROUP
--------------------
Name of the :command:`source_group` for :prop_tgt:`AUTOMOC` generated files.
When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for
files generated by :prop_tgt:`AUTOMOC`.

7
Help/prop_gbl/AUTORCC_SOURCE_GROUP.rst Normal file
View File

@ -0,0 +1,7 @@
AUTORCC_SOURCE_GROUP
--------------------
Name of the :command:`source_group` for :prop_tgt:`AUTORCC` generated files.
When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for
files generated by :prop_tgt:`AUTORCC`.

2
Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst
View File

@ -8,3 +8,5 @@ Whether the :command:`find_library` command should automatically search
:command:`find_library` command should automatically search the ``lib32``
variant of directories called ``lib`` in the search path when building 32-bit
binaries.
See also the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable.

2
Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst
View File

@ -8,3 +8,5 @@ FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the
:command:`find_library` command should automatically search the lib64
variant of directories called lib in the search path when building
64-bit binaries.
See also the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable.

12
Help/prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS.rst Normal file
View File

@ -0,0 +1,12 @@
FIND_LIBRARY_USE_LIBX32_PATHS
-----------------------------
Whether the :command:`find_library` command should automatically search
``libx32`` directories.
``FIND_LIBRARY_USE_LIBX32_PATHS`` is a boolean specifying whether the
:command:`find_library` command should automatically search the ``libx32``
variant of directories called ``lib`` in the search path when building
x32-abi binaries.
See also the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable.

9
Help/prop_gbl/GENERATOR_IS_MULTI_CONFIG.rst Normal file
View File

@ -0,0 +1,9 @@
GENERATOR_IS_MULTI_CONFIG
-------------------------
Read-only property that is true on multi-configuration generators.
True when using a multi-configuration generator
(such as :ref:`Visual Studio Generators` or :generator:`Xcode`).
Multi-config generators use :variable:`CMAKE_CONFIGURATION_TYPES`
as the set of configurations and ignore :variable:`CMAKE_BUILD_TYPE`.

15
Help/prop_sf/HEADER_FILE_ONLY.rst
View File

@ -7,3 +7,18 @@ A property on a source file that indicates if the source file is a
header file with no associated implementation. This is set
automatically based on the file extension and is used by CMake to
determine if certain dependency information should be computed.
By setting this property to ``ON``, you can disable compilation of
the given source file, even if it should be compiled because it is
part of the library's/executable's sources.
This is useful if you have some source files which you somehow
pre-process, and then add these pre-processed sources via
:command:`add_library` or :command:`add_executable`. Normally, in IDE,
there would be no reference of the original sources, only of these
pre-processed sources. So by setting this property for all the original
source files to ``ON``, and then either calling :command:`add_library`
or :command:`add_executable` while passing both the pre-processed
sources and the original sources, or by using :command:`target_sources`
to add original source files will do exactly what would one expect, i.e.
the original source files would be visible in IDE, and will not be built.

7
Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst
View File

@ -21,3 +21,10 @@ extension is changed). See the :prop_tgt:`PUBLIC_HEADER`,
:prop_tgt:`PRIVATE_HEADER`, and :prop_tgt:`RESOURCE` target properties for
specifying files meant for ``Headers``, ``PrivateHeaders``, or
``Resources`` directories.
If the specified location is equal to ``Resources``, the resulting location
will be the same as if the :prop_tgt:`RESOURCE` property had been used. If
the specified location is a sub-folder of ``Resources``, it will be placed
into the respective sub-folder. Note: For iOS Apple uses a flat bundle layout
where no ``Resources`` folder exist. Therefore CMake strips the ``Resources``
folder name from the specified location.

15
Help/prop_test/DISABLED.rst Normal file
View File

@ -0,0 +1,15 @@
DISABLED
--------
If set to true, the test will be skipped and its status will be 'Not Run'. A
DISABLED test will not be counted in the total number of tests and its
completion status will be reported to CDash as 'Disabled'.
A DISABLED test does not participate in test fixture dependency resolution.
If a DISABLED test has fixture requirements defined in its
:prop_test:`FIXTURES_REQUIRED` property, it will not cause setup or cleanup
tests for those fixtures to be added to the test set.
If a test with the :prop_test:`FIXTURES_SETUP` property set is DISABLED, the
fixture behavior will be as though that setup test was passing and any test
case requiring that fixture will still run.

17
Help/prop_tgt/AUTOGEN_BUILD_DIR.rst Normal file
View File

@ -0,0 +1,17 @@
AUTOGEN_BUILD_DIR
-----------------
Directory where :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC`
generate files for the target.
The directory is created on demand and automatically added to the
:prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES`.
When unset or empty the directory ``<dir>/<target-name>_autogen`` is used where
``<dir>`` is :variable:`CMAKE_CURRENT_BINARY_DIR` and ``<target-name>``
is :prop_tgt:`NAME`.
By default :prop_tgt:`AUTOGEN_BUILD_DIR` is unset.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.

66
Help/prop_tgt/AUTOMOC.rst
View File

@ -8,31 +8,47 @@ preprocessor automatically, i.e. without having to use the
:module:`QT4_WRAP_CPP() <FindQt4>` or QT5_WRAP_CPP() macro. Currently Qt4 and Qt5 are
supported.
When this property is set ``ON``, CMake will scan the
When this property is set ``ON``, CMake will scan the header and
source files at build time and invoke moc accordingly.
* If an ``#include`` statement like ``#include "moc_foo.cpp"`` is found,
the ``Q_OBJECT`` class declaration is expected in the header, and
``moc`` is run on the header file. A ``moc_foo.cpp`` file will be
generated from the source's header into the
``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include``
directory which is automatically added to the target's
:prop_tgt:`INCLUDE_DIRECTORIES`. This allows the compiler to find the
included ``moc_foo.cpp`` file regardless of the location the original source.
However, if multiple source files in different directories do this then their
generated moc files would collide. In this case a diagnostic will be issued.
* If an ``#include`` statement like ``#include "moc_<basename>.cpp"`` is found,
the ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in an otherwise empty
line of the ``<basename>.h(xx)`` header file. ``moc`` is run on the header
file to generate ``moc_<basename>.cpp`` in the
``<AUTOGEN_BUILD_DIR>/include`` directory which is automatically added
to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
This allows the compiler to find the included ``moc_<basename>.cpp`` file
regardless of the location the original source.
* If an ``#include`` statement like ``#include "foo.moc"`` is found,
then a ``Q_OBJECT`` is expected in the current source file and ``moc``
is run on the file itself. Additionally, header files with the same
base name (like ``foo.h``) or ``_p`` appended to the base name (like
``foo_p.h``) are parsed for ``Q_OBJECT`` macros, and if found, ``moc``
is also executed on those files. ``AUTOMOC`` checks multiple header
alternative extensions, such as ``hpp``, ``hxx`` etc when searching
for headers. The resulting moc files, which are not included as shown
above in any of the source files are included in a generated
``moc_compilation.cpp`` file, which is compiled as part of the
target.
* See :prop_tgt:`AUTOGEN_BUILD_DIR`.
* If an ``#include`` statement like ``#include "<basename>.moc"`` is found,
then ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in the current source
file and ``moc`` is run on the source file itself.
* Header files that are not included by an ``#include "moc_<basename>.cpp"``
statement are nonetheless scanned for ``Q_OBJECT`` or ``Q_GADGET`` macros.
The resulting ``moc_<basename>.cpp`` files are generated in custom
directories and automatically included in a generated
``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` file,
which is compiled as part of the target.
* The custom directories with checksum
based names help to avoid name collisions for moc files with the same
``<basename>``.
* See :prop_tgt:`AUTOGEN_BUILD_DIR`.
* Additionally, header files with the same base name as a source file,
(like ``<basename>.h``) or ``_p`` appended to the base name (like
``<basename>_p.h``), are parsed for ``Q_OBJECT`` or ``Q_GADGET`` macros,
and if found, ``moc`` is also executed on those files.
* ``AUTOMOC`` always checks multiple header alternative extensions,
such as ``hpp``, ``hxx``, etc. when searching for headers.
* ``AUTOMOC`` looks for the ``Q_PLUGIN_METADATA`` macro and reruns the
``moc`` when the file addressed by the ``FILE`` argument of the macro changes.
This property is initialized by the value of the :variable:`CMAKE_AUTOMOC`
variable if it is set when a target is created.
@ -47,6 +63,12 @@ See the documentation for this variable for more details.
The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the
automoc targets together in an IDE, e.g. in MSVS.
The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group
files generated by :prop_tgt:`AUTOMOC` together in an IDE, e.g. in MSVS.
Additional ``moc`` dependency file names can be extracted from source code
by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`.
Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by
enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`.

45
Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst Normal file
View File

@ -0,0 +1,45 @@
AUTOMOC_DEPEND_FILTERS
----------------------
Filter definitions used by :prop_tgt:`AUTOMOC` to extract file names from
source code as additional dependencies for the ``moc`` file.
This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON``
for this target.
Filters are defined as ``KEYWORD;REGULAR_EXPRESSION`` pairs. First the file
content is searched for ``KEYWORD``. If it is found at least once, then file
names are extracted by successively searching for ``REGULAR_EXPRESSION`` and
taking the first match group.
Consider a filter extracts the file name ``DEP`` from the content of a file
``FOO``. If ``DEP`` changes, then the ``moc`` file for ``FOO`` gets rebuilt.
The file ``DEP`` is searched for first in the vicinity
of ``FOO`` and afterwards in the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
By default :prop_tgt:`AUTOMOC_DEPEND_FILTERS` is initialized from
:variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`, which is empty by default.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.
Example
-------
Consider a file ``FOO.hpp`` holds a custom macro ``OBJ_JSON_FILE`` and we
want the ``moc`` file to depend on the macro`s file name argument::
class My_Class : public QObject
{
Q_OBJECT
OBJ_JSON_FILE ( "DEP.json" )
...
};
Then we might use :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` to
define a filter like this::
set(CMAKE_AUTOMOC_DEPEND_FILTERS
"OBJ_JSON_FILE" "[\n][ \t]*OBJ_JSON_FILE[ \t]*\\([ \t]*\"([^\"]+)\""
)

3
Help/prop_tgt/AUTORCC.rst
View File

@ -19,6 +19,9 @@ Additional command line options for rcc can be set via the
The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group
the autorcc targets together in an IDE, e.g. in MSVS.
The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group
files generated by :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS.
When there are multiple ``.qrc`` files with the same name, CMake will
generate unspecified unique names for ``rcc``. Therefore if
``Q_INIT_RESOURCE()`` or ``Q_CLEANUP_RESOURCE()`` need to be used the

11
Help/prop_tgt/AUTOUIC.rst
View File

@ -10,8 +10,15 @@ Qt4 and Qt5 are supported.
When this property is ``ON``, CMake will scan the source files at build time
and invoke ``uic`` accordingly. If an ``#include`` statement like
``#include "ui_foo.h"`` is found in ``foo.cpp``, a ``foo.ui`` file is
expected next to ``foo.cpp``, and ``uic`` is run on the ``foo.ui`` file.
``#include "ui_foo.h"`` is found in ``source.cpp``, a ``foo.ui`` file is
searched for first in the vicinity of ``source.cpp`` and afterwards in the
optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target.
``uic`` is run on the ``foo.ui`` file to generate ``ui_foo.h`` in the directory
``<AUTOGEN_BUILD_DIR>/include``,
which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
* See :prop_tgt:`AUTOGEN_BUILD_DIR`.
This property is initialized by the value of the :variable:`CMAKE_AUTOUIC`
variable if it is set when a target is created.

2
Help/prop_tgt/AUTOUIC_OPTIONS.rst
View File

@ -1,7 +1,7 @@
AUTOUIC_OPTIONS
---------------
Additional options for uic when using :prop_tgt:`AUTOUIC`
Additional options for ``uic`` when using :prop_tgt:`AUTOUIC`
This property holds additional command line options which will be used when
``uic`` is executed during the build via :prop_tgt:`AUTOUIC`, i.e. it is

12
Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst Normal file
View File

@ -0,0 +1,12 @@
AUTOUIC_SEARCH_PATHS
--------------------
Search path list used by :prop_tgt:`AUTOUIC` to find included
``.ui`` files.
This property is initialized by the value of the
:variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable if it is set
when a target is created. Otherwise it is empty.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.

13
Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst Normal file
View File

@ -0,0 +1,13 @@
BUILD_WITH_INSTALL_NAME_DIR
---------------------------
``BUILD_WITH_INSTALL_NAME_DIR`` is a boolean specifying whether the macOS
``install_name`` of a target in the build tree uses the directory given by
:prop_tgt:`INSTALL_NAME_DIR`. This setting only applies to targets on macOS.
This property is initialized by the value of the variable
:variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` if it is set when a target is
created.
If this property is not set and policy :policy:`CMP0068` is not ``NEW``, the
value of :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is used in its place.

18
Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst
View File

@ -1,11 +1,15 @@
BUILD_WITH_INSTALL_RPATH
------------------------
Should build tree targets have install tree rpaths.
``BUILD_WITH_INSTALL_RPATH`` is a boolean specifying whether to link the target
in the build tree with the :prop_tgt:`INSTALL_RPATH`. This takes precedence
over :prop_tgt:`SKIP_BUILD_RPATH` and avoids the need for relinking before
installation.
BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the
target in the build tree with the INSTALL_RPATH. This takes
precedence over SKIP_BUILD_RPATH and avoids the need for relinking
before installation. This property is initialized by the value of the
variable CMAKE_BUILD_WITH_INSTALL_RPATH if it is set when a target is
created.
This property is initialized by the value of the
:variable:`CMAKE_BUILD_WITH_INSTALL_RPATH` variable if it is set when a target
is created.
If policy :policy:`CMP0068` is not ``NEW``, this property also controls use of
:prop_tgt:`INSTALL_NAME_DIR` in the build tree on macOS. Either way, the
:prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property takes precedence.

12
Help/prop_tgt/CUDA_PTX_COMPILATION.rst Normal file
View File

@ -0,0 +1,12 @@
CUDA_PTX_COMPILATION
--------------------
Compile CUDA sources to ``.ptx`` files instead of ``.obj`` files
within :ref:`Object Libraries`.
For example:
.. code-block:: cmake
add_library(myptx OBJECT a.cu b.cu)
set_property(TARGET myptx PROPERTY CUDA_PTX_COMPILATION ON)

15
Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst Normal file
View File

@ -0,0 +1,15 @@
CUDA_RESOLVE_DEVICE_SYMBOLS
---------------------------
CUDA only: Enables device linking for the specific static library target
If set this will enable device linking on this static library target. Normally
device linking is deferred until a shared library or executable is generated,
allowing for multiple static libraries to resolve device symbols at the same
time.
For instance:
.. code-block:: cmake
set_property(TARGET mystaticlib PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON)

2
Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst
View File

@ -3,6 +3,6 @@ EXCLUDE_FROM_DEFAULT_BUILD
Exclude target from "Build Solution".
This property is only used by Visual Studio generators 7 and above.
This property is only used by Visual Studio generators.
When set to TRUE, the target will not be built when you press "Build
Solution".

11
Help/prop_tgt/IMPORTED_OBJECTS.rst Normal file
View File

@ -0,0 +1,11 @@
IMPORTED_OBJECTS
----------------
:ref:`;-list <CMake Language Lists>` of absolute paths to the object
files on disk for an :ref:`imported <Imported targets>`
:ref:`object library <object libraries>`.
Ignored for non-imported targets.
Projects may skip ``IMPORTED_OBJECTS`` if the configuration-specific
property :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` is set instead.

7
Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst Normal file
View File

@ -0,0 +1,7 @@
IMPORTED_OBJECTS_<CONFIG>
-------------------------
<CONFIG>-specific version of :prop_tgt:`IMPORTED_OBJECTS` property.
Configuration names correspond to those provided by the project from
which the target is imported.

4
Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst
View File

@ -5,3 +5,7 @@ Enable interprocedural optimization for a target.
If set to true, enables interprocedural optimizations if they are
known to be supported by the compiler.
This property is initialized by the
:variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable if it is set when a
target is created.

4
Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst
View File

@ -6,3 +6,7 @@ Per-configuration interprocedural optimization for a target.
This is a per-configuration version of INTERPROCEDURAL_OPTIMIZATION.
If set, this property overrides the generic property for the named
configuration.
This property is initialized by the
:variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` variable if it is set
when a target is created.

45
Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst
View File

@ -23,3 +23,48 @@ is ignored for non-imported targets.
This property is initialized by the value of the
:variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` variable if it is set when a
target is created.
Example
^^^^^^^
For example creating imported C++ library ``foo``:
.. code-block:: cmake
add_library(foo STATIC IMPORTED)
Use ``foo_debug`` path for ``Debug`` build type:
.. code-block:: cmake
set_property(
TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS DEBUG
)
set_target_properties(foo PROPERTIES
IMPORTED_LINK_INTERFACE_LANGUAGES_DEBUG "CXX"
IMPORTED_LOCATION_DEBUG "${foo_debug}"
)
Use ``foo_release`` path for ``Release`` build type:
.. code-block:: cmake
set_property(
TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE
)
set_target_properties(foo PROPERTIES
IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "CXX"
IMPORTED_LOCATION_RELEASE "${foo_release}"
)
Use ``Release`` version of library for ``MinSizeRel`` and ``RelWithDebInfo``
build types:
.. code-block:: cmake
set_target_properties(foo PROPERTIES
MAP_IMPORTED_CONFIG_MINSIZEREL Release
MAP_IMPORTED_CONFIG_RELWITHDEBINFO Release
)

7
Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst
View File

@ -14,6 +14,13 @@ be automatically exported and imported by callers. This simplifies porting
projects to Windows by reducing the need for explicit ``dllexport`` markup,
even in ``C++`` classes.
When this property is enabled, zero or more ``.def`` files may also be
specified as source files of the target. The exports named by these files
will be merged with those detected from the object files to generate a
single module definition file to be passed to the linker. This can be
used to export symbols from a ``.dll`` that are not in any of its object
files but are added by the linker from dependencies (e.g. ``msvcrt.lib``).
This property is initialized by the value of
the :variable:`CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS` variable if it is set
when a target is created.

328
Help/release/3.9.rst Normal file
View File

@ -0,0 +1,328 @@
CMake 3.9 Release Notes
***********************
.. only:: html
.. contents::
Changes made since CMake 3.8 include the following.
New Features
============
Languages
---------
* ``CUDA`` is now supported by the :ref:`Visual Studio Generators`
for VS 2010 and above. This complements the existing support by the
:ref:`Makefile Generators` and the :generator:`Ninja` generator.
CUDA 8.0.61 or higher is recommended due to known bugs in the VS
integration by earlier versions.
* CMake is now aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and
:prop_tgt:`C standards <C_STANDARD>` and their associated meta-features for
the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>`: ``Cray``,
``PGI``, and ``XL``.
Generators
----------
* :ref:`Visual Studio Generators` for VS 2010 and above learned to support
the ``ASM_NASM`` language when ``nasm`` is installed.
* The :generator:`Xcode` generator learned to create Xcode schema files.
This is an experimental feature and can be activated by setting the
:variable:`CMAKE_XCODE_GENERATE_SCHEME` variable to a ``TRUE`` value.
* The :generator:`Xcode` generator now supports Xcode 9.
Commands
--------
* The :command:`add_library` command ``IMPORTED`` option learned to support
:ref:`Object Libraries`.
* All ``find_`` commands now have a ``PACKAGE_ROOT`` search path group that
is first in the search heuristics. If a ``find_`` command is called from
inside a find module, then the CMake variable and environment variable named
``<PackageName>_ROOT`` are used as prefixes and are the first set of paths
to be searched.
* The :command:`find_library` command learned to search ``libx32`` paths
when the build targets the ``x32`` ABI. See the
:prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property.
* The :command:`include_external_msproject` command learned to use
the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property
to map current configurations to the external configurations.
* The :command:`install(TARGETS)` command learned a new ``OBJECTS`` option to
specify where to install :ref:`Object Libraries`.
* The :command:`install(EXPORT)` command learned how to export
:ref:`Object Libraries`.
* The :command:`project` command learned an optional ``DESCRIPTION``
parameter to set the :variable:`PROJECT_DESCRIPTION` variable.
* The :command:`separate_arguments` command gained a ``NATIVE_COMMAND`` mode
that performs argument separation depending on the host operating system.
Variables
---------
* A :variable:`CMAKE_ANDROID_NDK_DEPRECATED_HEADERS` variable was added
for use when :ref:`Cross Compiling for Android with the NDK` to request
use of the deprecated headers even when unified headers are available.
The default is now to use unified headers if available.
* A :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` variable was introduced to
allow :variable:`CMAKE_AUTOMOC` to extract additional dependency file names
for ``moc`` from the contents of source files.
* A :variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable was introduced to
allow :variable:`CMAKE_AUTOUIC` to search for ``foo.ui`` in more
places than the vicinity of the file including ``ui_foo.h``.
* A :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable was added to
tell the :command:`find_library` command to search in a ``lib<suffix>``
directory before each ``lib`` directory that would normally be searched.
* A :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable was added to
initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` property on all
targets.
* A :variable:`CMAKE_<LANG>_COMPILER_AR` variable was added to hold
the path to the GCC/Clang wrapper of ``ar``.
* A :variable:`CMAKE_<LANG>_COMPILER_RANLIB` variable was added to hold
the path to the GCC/Clang wrapper of ``ranlib``.
* The :variable:`CMAKE_SYSROOT_COMPILE` and :variable:`CMAKE_SYSROOT_LINK`
variables were added to use separate sysroots for compiling and linking.
Properties
----------
* A new :prop_tgt:`AUTOGEN_BUILD_DIR` target property was introduced to set
a custom output directory for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC`,
and :prop_tgt:`AUTORCC`.
* A new :prop_tgt:`AUTOMOC_DEPEND_FILTERS` target property was introduced to
allow :prop_tgt:`AUTOMOC` to extract additional dependency file names
for ``moc`` from the contents of source files.
* A new :prop_tgt:`AUTOUIC_SEARCH_PATHS` target property was introduced to
allow :prop_tgt:`AUTOUIC` to search for ``foo.ui`` in more
places than the vicinity of the file including ``ui_foo.h``.
* Global properties :prop_gbl:`AUTOGEN_SOURCE_GROUP`,
:prop_gbl:`AUTOMOC_SOURCE_GROUP` and
:prop_gbl:`AUTORCC_SOURCE_GROUP` were
introduced to allow files generated by :prop_tgt:`AUTOMOC` or
:prop_tgt:`AUTORCC` to be placed in a :command:`source_group`.
* A :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property and corresponding
:variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` variable were added to
control whether to use the :prop_tgt:`INSTALL_NAME_DIR` target property
value for binaries in the build tree. This is for macOS ``install_name``
as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is for ``RPATH``.
* A :prop_tgt:`CUDA_PTX_COMPILATION` target property was added to
:ref:`Object Libraries` to support compiling to ``.ptx`` files
instead of host object files.
* A :prop_gbl:`GENERATOR_IS_MULTI_CONFIG` global property was
added to determine whether the current generator is a multi-configuration
generator (such as :ref:`Visual Studio Generators` or :generator:`Xcode`).
* The :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is now enforced
when enabled. CMake will add IPO flags unconditionally or produce an error
if it does not know the flags for the current compiler. The project is now
responsible to use the :module:`CheckIPOSupported` module to check for IPO
support before enabling the target property. See policy :policy:`CMP0069`.
* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property may now
be used in combination with explicit ``.def`` files in order to
export all symbols from the object files within a target plus
an explicit list of symbols that the linker finds in dependencies
(e.g. ``msvcrt.lib``).
Modules
-------
* A :module:`CheckIPOSupported` module was added to help projects
check whether interprocedural optimization (IPO) is supported by
the current toolchain and CMake version.
* The :module:`CMakeFindDependencyMacro` module ``find_dependency`` macro
now forwards all arguments to the underlying :command:`find_package`
call. Existing uses will continue to function as before, but callers can
now access the full suite of arguments that ``find_package`` accepts.
* The :module:`FeatureSummary` module :command:`feature_summary` command now
accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default
title for the selected package type.
* The :module:`FeatureSummary` module gained a new
:variable:`FeatureSummary_<TYPE>_DESCRIPTION` variable that can be defined
for each ``<TYPE>`` to replace the type name with the specified string
whenever the package type is used in an output string by the module.
* The :module:`FindDoxygen` module learned to control Doxygen behavior using
CMake variables and generate documentation via the newly added
:command:`doxygen_add_docs` function. The Doxygen input file (``Doxyfile``)
is automatically generated and doxygen is run as part of a custom target.
Additional components can be specified to find optional tools: ``dot``,
``mscgen`` and ``dia``.
* The :module:`FindMPI` module now provides imported targets.
* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp`
command gained an ``EXPORT_MACRO`` option to specify the name of
a DLL export markup macro.
* The :module:`FindProtobuf` module now supports usage of static libraries
for Unix via a new ``Protobuf_USE_STATIC_LIBS`` input variable.
* The :module:`FindProtobuf` module now provides imported targets
when the libraries are found.
* A new :module:`GoogleTest` module was added to provide the
:command:`gtest_add_tests` function independently of the :module:`FindGTest`
module. The function was also updated to support keyword arguments, with
functionality expanded to allow a test name prefix and suffix to be
specified, the dependency on the source files to be optional and the list of
discovered test cases to be returned to the caller.
CTest
-----
* The :command:`ctest_submit` command gained a ``HTTPHEADER`` option
to specify custom headers to send during submission.
* The :manual:`ctest(1)` executable gained new options which allow the
developer to disable automatically adding tests to the test set to satisfy
fixture dependencies. ``-FS`` prevents adding setup tests for fixtures
matching the provided regular expression, ``-FC`` prevents adding cleanup
tests for matching fixtures and ``-FA`` prevents adding any test for matching
fixtures.
* A :prop_test:`DISABLED` test property was added to mark tests that
are configured but explicitly disabled so they do not run.
CPack
-----
* The :module:`CPackArchive` module learned to modify the filename
per-component. See the :variable:`CPACK_ARCHIVE_FILE_NAME` variable and
its per-component version :variable:`CPACK_ARCHIVE_<component>_FILE_NAME`.
* The :module:`CPackComponent` module :command:`cpack_add_component` command
gained a new ``PLIST <filename>`` option to specify the ``pkgbuild``
``--component-plist`` argument when using the
:module:`productbuild <CPackProductBuild>` generator.
* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
:command:`cpack_ifw_configure_component_group` commands gained
internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION``
options.
* The :module:`CPackIFW` module learned the new hint :variable:`CPACK_IFW_ROOT`
variable for finding the QtIFW tool suite installed in a non-standard place.
* The :module:`CPackProductBuild` module gained a new
:variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to
specify resources to be copied into the ``Resources``
directory.
* The :module:`CPackRPM` module learned to modify the ``debuginfo`` package
name. See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable.
* The :module:`CPackWIX` module patching system now has the ability to set
additional attributes. This can be done by specifying attributes with
the ``CPackWiXFragment`` XML tag after the ``Id`` attribute.
See the :variable:`CPACK_WIX_PATCH_FILE` variable.
* The CPack WIX generator implemented a new
:variable:`CPACK_WIX_ROOT_FOLDER_ID` variable which allows
using a custom root folder ID instead of the default
``ProgramFilesFolder`` / ``ProgramFiles64Folder``.
Other
-----
* Interprocedural optimization (IPO) is now supported for GNU and Clang
compilers using link time optimization (LTO) flags. See the
:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property and
:module:`CheckIPOSupported` module.
* The ``TARGET_OBJECTS``
:manual:`generator expression <cmake-generator-expressions(7)>`
is now supported by the :command:`add_custom_command` and
:command:`file(GENERATE)` commands.
* Two new informational generator expressions to retrieve Apple Bundle
directories have been added. The first one ``$<TARGET_BUNDLE_DIR:tgt>``
outputs the full path to the Bundle directory, the other one
``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` outputs the full path to the
``Contents`` directory of macOS Bundles and App Bundles. For all other
bundle types and SDKs it is identical with ``$<TARGET_BUNDLE_DIR:tgt>``.
The new expressions are helpful to query Bundle locations independent of
the different Bundle types and layouts on macOS and iOS.
Deprecated and Removed Features
===============================
* An explicit deprecation diagnostic was added for policies ``CMP0036``
and below. The :manual:`cmake-policies(7)` manual explains that the
OLD behaviors of all policies are deprecated and that projects should
always port to the NEW behaviors as soon as possible.
* The :generator:`Visual Studio 8 2005` generator is now deprecated
and will be removed in a future version of CMake.
* The :generator:`Visual Studio 7 .NET 2003` generator has been removed.
* The :generator:`Xcode` generator dropped support for Xcode versions
older than 3.
* The :module:`FindDoxygen` module has deprecated several variables.
* The version of curl bundled with CMake no longer accepts URLs of the form
``file://c:/...`` on Windows due to a change in upstream curl 7.52. Use
the form ``file:///c:/...`` instead to work on all versions.
Other Changes
=============
* When using :prop_tgt:`AUTOMOC`, CMake now scans for the presence of the
``Q_PLUGIN_METADATA`` macro and reruns moc when the file from the
macro's ``FILE`` argument changes.
* When :prop_tgt:`AUTOMOC` detects an include statement of the form
``#include "moc_<basename>.cpp"`` the search for the respective header file
now looks in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well.
* When running tests, CTest learned to treat skipped tests (using the
:prop_test:`SKIP_RETURN_CODE` property) the same as tests with the new
:prop_test:`DISABLED` property. Due to this change, CTest will not indicate
failure when all tests are either skipped or pass.
* The :generator:`Ninja` generator has loosened the dependencies of object
compilation. Object compilation now depends only on custom targets
and custom commands associated with libraries on which the object's target
depends and no longer depends on the libraries themselves. Source files
in dependent targets may now compile without waiting for their targets'
dependencies to link.
* On macOS, the default application bundle ``Info.plist`` file now enables
Hi-DPI support.
* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH`
no longer affect the ``install_name`` field. See policy :policy:`CMP0068`.
* The :generator:`Visual Studio 14 2015` generator has been taught about
a change to the ``v140`` toolset made by a VS 2015 update. VS changed
the set of values it understands for the ``GenerateDebugInformation``
linker setting that produces the ``-DEBUG`` linker flag variants.

1
Help/release/index.rst
View File

@ -11,6 +11,7 @@ Releases
.. toctree::
:maxdepth: 1
3.9 <3.9>
3.8 <3.8>
3.7 <3.7>
3.6 <3.6>

9
Help/variable/CMAKE_ANDROID_NDK_DEPRECATED_HEADERS.rst Normal file
View File

@ -0,0 +1,9 @@
CMAKE_ANDROID_NDK_DEPRECATED_HEADERS
------------------------------------
When :ref:`Cross Compiling for Android with the NDK`, this variable
may be set to specify whether to use the deprecated per-api-level
headers instead of the unified headers.
If not specified, the default will be *false* if using a NDK version
that provides the unified headers and *true* otherwise.

12
Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst Normal file
View File

@ -0,0 +1,12 @@
CMAKE_AUTOMOC_DEPEND_FILTERS
----------------------------
Filter definitions used by :variable:`CMAKE_AUTOMOC`
to extract file names from source code as additional dependencies
for the ``moc`` file.
This variable is used to initialize the :prop_tgt:`AUTOMOC_DEPEND_FILTERS`
property on all the targets. See that target property for additional
information.
By default it is empty.

11
Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst Normal file
View File

@ -0,0 +1,11 @@
CMAKE_AUTOUIC_SEARCH_PATHS
--------------------------
Search path list used by :variable:`CMAKE_AUTOUIC` to find included
``.ui`` files.
This variable is used to initialize the :prop_tgt:`AUTOUIC_SEARCH_PATHS`
property on all the targets. See that target property for additional
information.
By default it is empty.

7
Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst Normal file
View File

@ -0,0 +1,7 @@
CMAKE_BUILD_WITH_INSTALL_NAME_DIR
---------------------------------
Whether to use :prop_tgt:`INSTALL_NAME_DIR` on targets in the build tree.
This variable is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR`
property on all targets.

2
Help/variable/CMAKE_CFG_INTDIR.rst
View File

@ -12,7 +12,7 @@ Example values:
::
$(ConfigurationName) = Visual Studio 7, 8, 9
$(ConfigurationName) = Visual Studio 8, 9
$(Configuration) = Visual Studio 10
$(CONFIGURATION) = Xcode
. = Make-based tools

12
Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst Normal file
View File

@ -0,0 +1,12 @@
CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX
------------------------------------
Specify a ``<suffix>`` to tell the :command:`find_library` command to
search in a ``lib<suffix>`` directory before each ``lib`` directory that
would normally be searched.
This overrides the behavior of related global properties:
* :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS`
* :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS`
* :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS`

15
Help/variable/CMAKE_GENERATOR_PLATFORM.rst
View File

@ -1,7 +1,7 @@
CMAKE_GENERATOR_PLATFORM
------------------------
Generator-specific target platform name specified by user.
Generator-specific target platform specification provided by user.
Some CMake generators support a target platform name to be given
to the native build system to choose a compiler toolchain.
@ -13,3 +13,16 @@ A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE`
variable may initialize ``CMAKE_GENERATOR_PLATFORM``. Once a given
build tree has been initialized with a particular value for this
variable, changing the value has undefined behavior.
Platform specification is supported only on specific generators:
* For :ref:`Visual Studio Generators` with VS 2005 and above this
specifies the target architecture.
See native build system documentation for allowed platform names.
Visual Studio Platform Selection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On :ref:`Visual Studio Generators` the selected platform name
is provided in the :variable:`CMAKE_VS_PLATFORM_NAME` variable.

45
Help/variable/CMAKE_GENERATOR_TOOLSET.rst
View File

@ -1,15 +1,50 @@
CMAKE_GENERATOR_TOOLSET
-----------------------
Native build system toolset name specified by user.
Native build system toolset specification provided by user.
Some CMake generators support a toolset name to be given to the native
build system to choose a compiler. If the user specifies a toolset
name (e.g. via the :manual:`cmake(1)` ``-T`` option) the value will be
available in this variable.
Some CMake generators support a toolset specification to tell the
native build system how to choose a compiler. If the user specifies
a toolset (e.g. via the :manual:`cmake(1)` ``-T`` option) the value
will be available in this variable.
The value of this variable should never be modified by project code.
A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE`
variable may initialize ``CMAKE_GENERATOR_TOOLSET``. Once a given
build tree has been initialized with a particular value for this
variable, changing the value has undefined behavior.
Toolset specification is supported only on specific generators:
* :ref:`Visual Studio Generators` for VS 2010 and above
* The :generator:`Xcode` generator for Xcode 3.0 and above
See native build system documentation for allowed toolset names.
Visual Studio Toolset Selection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :ref:`Visual Studio Generators` support toolset specification
using one of these forms:
* ``toolset``
* ``toolset[,key=value]*``
* ``key=value[,key=value]*``
The ``toolset`` specifies the toolset name. The selected toolset name
is provided in the :variable:`CMAKE_VS_PLATFORM_TOOLSET` variable.
The ``key=value`` pairs form a comma-separated list of options to
specify generator-specific details of the toolset selection.
Supported pairs are:
``cuda=<version>``
Specify the CUDA toolkit version to use. Supported by VS 2010
and above with the CUDA toolkit VS integration installed.
See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` variable.
``host=x64``
Request use of the native ``x64`` toolchain on ``x64`` hosts.
Supported by VS 2013 and above.
See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE`
variable.

4
Help/variable/CMAKE_HOST_WIN32.rst
View File

@ -1,6 +1,6 @@
CMAKE_HOST_WIN32
----------------
``True`` on Windows systems, including Win64.
``True`` if the host system is running Windows, including Windows 64-bit and MSYS.
Set to ``true`` when the host system is Windows and on Cygwin.
Set to ``false`` on Cygwin.

8
Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst Normal file
View File

@ -0,0 +1,8 @@
CMAKE_INTERPROCEDURAL_OPTIMIZATION
----------------------------------
Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` of targets.
This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`
property on all the targets. See that target property for additional
information.

8
Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst Normal file
View File

@ -0,0 +1,8 @@
CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
-------------------------------------------
Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` of targets.
This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>`
property on all the targets. See that target property for additional
information.

Some files were not shown because too many files have changed in this diff Show More