diff --git a/.clang-format b/.clang-format index 88bfbd335..162c56d76 100644 --- a/.clang-format +++ b/.clang-format @@ -1,8 +1,21 @@ --- -# This configuration requires clang-format 3.8 or higher. +# This configuration requires clang-format version 6.0 exactly. BasedOnStyle: Mozilla AlignOperands: false -AlwaysBreakAfterReturnType: None +AllowShortFunctionsOnASingleLine: InlineOnly AlwaysBreakAfterDefinitionReturnType: None +AlwaysBreakAfterReturnType: None +BinPackArguments: true +BinPackParameters: true +BraceWrapping: + AfterClass: true + AfterEnum: true + AfterFunction: true + AfterStruct: true + AfterUnion: true +BreakBeforeBraces: Custom ColumnLimit: 79 +IndentPPDirectives: AfterHash +SortUsingDeclarations: false +SpaceAfterTemplateKeyword: true ... diff --git a/CMakeLists.txt b/CMakeLists.txt index 3ab679ea9..e20d77024 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -285,7 +285,7 @@ if(CMake_RUN_IWYU) 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;-w") + "${IWYU_COMMAND};-Xiwyu;--mapping_file=${CMake_SOURCE_DIR}/Utilities/IWYU/mapping.imp;-w;-DCMAKE_IWYU") endif() @@ -573,22 +573,24 @@ macro (CMAKE_BUILD_UTILITIES) #--------------------------------------------------------------------- # Use curses? if (UNIX) - # there is a bug in the Syllable libraries which makes linking ccmake fail, Alex - if(NOT CMAKE_SYSTEM_NAME MATCHES syllable) - set(CURSES_NEED_NCURSES TRUE) - find_package(Curses QUIET) - if (CURSES_LIBRARY) - option(BUILD_CursesDialog "Build the CMake Curses Dialog ccmake" ON) - else () - message("Curses libraries were not found. Curses GUI for CMake will not be built.") - set(BUILD_CursesDialog 0) - endif () - else() - set(BUILD_CursesDialog 0) + if(NOT DEFINED BUILD_CursesDialog) + include(${CMake_SOURCE_DIR}/Source/Checks/Curses.cmake) + option(BUILD_CursesDialog "Build the CMake Curses Dialog ccmake" "${CMakeCheckCurses_COMPILED}") endif() else () set(BUILD_CursesDialog 0) endif () + if(BUILD_CursesDialog) + set(CURSES_NEED_NCURSES TRUE) + find_package(Curses) + if(NOT CURSES_FOUND) + message(WARNING + "'ccmake' will not be built because Curses was not found.\n" + "Turn off BUILD_CursesDialog to suppress this message." + ) + set(BUILD_CursesDialog 0) + endif() + endif() if(BUILD_CursesDialog) if(NOT CMAKE_USE_SYSTEM_FORM) add_subdirectory(Source/CursesDialog/form) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 381769d16..01987be09 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -29,11 +29,14 @@ To contribute patches: #. Base all new work on the upstream ``master`` branch. Base work on the upstream ``release`` branch only if it fixes a regression or bug in a feature new to that release. + If in doubt, prefer ``master``. Reviewers may simply ask for + a rebase if deemed appropriate in particular cases. #. Create commits making incremental, distinct, logically complete changes with appropriate `commit messages`_. #. Push a topic branch to a personal repository fork on GitLab. #. Create a GitLab Merge Request targeting the upstream ``master`` branch (even if the change is intended for merge to the ``release`` branch). + Check the box to allow edits from maintainers. The merge request will enter the `CMake Review Process`_ for consideration. diff --git a/CompileFlags.cmake b/CompileFlags.cmake index 32e7005b5..ec9b31bd9 100644 --- a/CompileFlags.cmake +++ b/CompileFlags.cmake @@ -82,3 +82,26 @@ endif () if (CMAKE_ANSI_CFLAGS) set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${CMAKE_ANSI_CFLAGS}") endif () + +# Allow per-translation-unit parallel builds when using MSVC +if(CMAKE_GENERATOR MATCHES "Visual Studio" AND + (CMAKE_C_COMPILER_ID MATCHES "MSVC|Intel" OR + CMAKE_CXX_COMPILER_ID MATCHES "MSVC|Intel")) + + set(CMake_MSVC_PARALLEL ON CACHE STRING "\ +Enables /MP flag for parallel builds using MSVC. Specify an \ +integer value to control the number of threads used (Only \ +works on some older versions of Visual Studio). Setting to \ +ON lets the toolchain decide how many threads to use. Set to \ +OFF to disable /MP completely." ) + + if(CMake_MSVC_PARALLEL) + if(CMake_MSVC_PARALLEL GREATER 0) + string(APPEND CMAKE_C_FLAGS " /MP${CMake_MSVC_PARALLEL}") + string(APPEND CMAKE_CXX_FLAGS " /MP${CMake_MSVC_PARALLEL}") + else() + string(APPEND CMAKE_C_FLAGS " /MP") + string(APPEND CMAKE_CXX_FLAGS " /MP") + endif() + endif() +endif() diff --git a/Copyright.txt b/Copyright.txt index 660455f61..743c63418 100644 --- a/Copyright.txt +++ b/Copyright.txt @@ -78,6 +78,7 @@ The following individuals and institutions are among the Contributors: * Nikita Krupen'ko * NVIDIA Corporation * OpenGamma Ltd. +* Patrick Stotko * Per Øyvind Karlsen * Peter Collingbourne * Petr Gotthard diff --git a/Help/command/COMPILE_OPTIONS_SHELL.txt b/Help/command/COMPILE_OPTIONS_SHELL.txt new file mode 100644 index 000000000..a1316c871 --- /dev/null +++ b/Help/command/COMPILE_OPTIONS_SHELL.txt @@ -0,0 +1,9 @@ +The final set of compile options used for a target is constructed by +accumulating options from the current target and the usage requirements of +it dependencies. The set of options is de-duplicated to avoid repetition. +While beneficial for individual options, the de-duplication step can break +up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may +specify a group of options using shell-like quoting along with a ``SHELL:`` +prefix. The ``SHELL:`` prefix is dropped and the rest of the option string +is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. +For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 7db221cb8..38c231a67 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -16,6 +16,7 @@ The general signature is: [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [NO_DEFAULT_PATH] + [NO_PACKAGE_ROOT_PATH] [NO_CMAKE_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] @@ -60,6 +61,13 @@ 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 ```` in the + :variable:`_ROOT` CMake variable and the + :envvar:`_ROOT` environment variable if + called from within a find module loaded by + :command:`find_package()` + .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: |prefix_XXX_SUBDIR| for each ```` in :variable:`CMAKE_PREFIX_PATH` @@ -71,7 +79,22 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ```` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. Search paths specified in cmake-specific cache variables. +1. If called from within a find module loaded by + :command:`find_package()`, search prefixes unique to the + current package being found. Specifically look in the + :variable:`_ROOT` CMake variable and the + :envvar:`_ROOT` environment variable. + 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 + searched after paths from the current module, + i.e. ``_ROOT``, ``ENV{_ROOT}``, + ``_ROOT``, ``ENV{_ROOT}``, etc. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. + See policy :policy:`CMP0074`. + + * |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 `. This can be skipped if ``NO_CMAKE_PATH`` is passed. @@ -80,7 +103,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: * |CMAKE_XXX_PATH| * |CMAKE_XXX_MAC_PATH| -2. Search paths specified in cmake-specific environment variables. +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). @@ -90,17 +113,17 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: * |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. @@ -108,7 +131,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. diff --git a/Help/command/add_compile_definitions.rst b/Help/command/add_compile_definitions.rst new file mode 100644 index 000000000..48815d44f --- /dev/null +++ b/Help/command/add_compile_definitions.rst @@ -0,0 +1,23 @@ +add_compile_definitions +----------------------- + +Adds preprocessor definitions to the compilation of source files. + +:: + + add_compile_definitions( ...) + +Adds preprocessor definitions to the compiler command line for targets in the +current directory and below (whether added before or after this command is +invoked). See documentation of the :prop_dir:`directory ` +and :prop_tgt:`target ` ``COMPILE_DEFINITIONS`` properties. + +Definitions are specified using the syntax ``VAR`` or ``VAR=value``. +Function-style definitions are not supported. CMake will automatically +escape the value correctly for the native build system (note that CMake +language syntax may require escapes to specify some values). + +Arguments to ``add_compile_definitions`` may use "generator expressions" with +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. diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 3fe2a3330..c445608c3 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -14,10 +14,12 @@ See documentation of the :prop_dir:`directory ` and This command can be used to add any options, but alternative commands exist to add preprocessor definitions (:command:`target_compile_definitions` -and :command:`add_definitions`) or include directories +and :command:`add_compile_definitions`) or include directories (:command:`target_include_directories` and :command:`include_directories`). Arguments to ``add_compile_options`` may use "generator expressions" with 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. + +.. include:: COMPILE_OPTIONS_SHELL.txt diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index d4f644a68..5f74c543e 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -216,10 +216,9 @@ When the command will happen is determined by which of the following is specified: ``PRE_BUILD`` - Run before any other rules are executed within the target. - This is supported only on Visual Studio 8 or later. - For all other generators ``PRE_BUILD`` will be treated as - ``PRE_LINK``. + On :ref:`Visual Studio Generators`, run before any other rules are + executed within the target. + On other generators, run just before ``PRE_LINK`` commands. ``PRE_LINK`` Run after sources have been compiled but before linking the binary or running the librarian or archiver tool of a static library. diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst index a04faf591..1da15a61f 100644 --- a/Help/command/add_definitions.rst +++ b/Help/command/add_definitions.rst @@ -10,8 +10,16 @@ Adds -D define flags to the compilation of source files. Adds definitions to the compiler command line for targets in the current directory and below (whether added before or after this command is invoked). This command can be used to add any flags, but it is intended to add -preprocessor definitions (see the :command:`add_compile_options` command -to add other flags). +preprocessor definitions. + +.. note:: + + This command has been superseded by alternatives: + + * Use :command:`add_compile_definitions` to add preprocessor definitions. + * Use :command:`include_directories` to add include directories. + * Use :command:`add_compile_options` to add other options. + Flags beginning in -D or /D that look like preprocessor definitions are automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory property for the current directory. Definitions with non-trivial values diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 3706153c3..f20b2743e 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -83,8 +83,11 @@ about the imported library are specified by setting properties whose names begin in ``IMPORTED_`` and ``INTERFACE_``. The most important such property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration variant :prop_tgt:`IMPORTED_LOCATION_`) which specifies the -location of the main library file on disk. See documentation of the -``IMPORTED_*`` and ``INTERFACE_*`` properties for more information. +location of the main library file on disk. Or, for object libraries, +:prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_`) +specifies the locations of object files on disk. +See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties +for more information. Object Libraries ^^^^^^^^^^^^^^^^ @@ -110,10 +113,10 @@ along with those compiled from their own sources. Object libraries 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 linked. Some native build systems (such as Xcode) may not like -targets that have only object files, so consider adding at least one real -source file to any target that references ``$``. +``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Some native build +systems (such as Xcode) may not like targets that have only object files, so +consider adding at least one real source file to any target that references +``$``. Alias Libraries ^^^^^^^^^^^^^^^ diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 7199874ce..989315194 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -27,13 +27,13 @@ Key Description ``IS_64BIT`` One if processor is 64Bit ``HAS_FPU`` One if processor has floating point unit ``HAS_MMX`` One if processor supports MMX instructions -``HAS_MMX_PLUS`` One if porcessor supports Ext. MMX instructions -``HAS_SSE`` One if porcessor supports SSE instructions -``HAS_SSE2`` One if porcessor supports SSE2 instructions -``HAS_SSE_FP`` One if porcessor supports SSE FP instructions -``HAS_SSE_MMX`` One if porcessor supports SSE MMX instructions -``HAS_AMD_3DNOW`` One if porcessor supports 3DNow instructions -``HAS_AMD_3DNOW_PLUS`` One if porcessor supports 3DNow+ instructions +``HAS_MMX_PLUS`` One if processor supports Ext. MMX instructions +``HAS_SSE`` One if processor supports SSE instructions +``HAS_SSE2`` One if processor supports SSE2 instructions +``HAS_SSE_FP`` One if processor supports SSE FP instructions +``HAS_SSE_MMX`` One if processor supports SSE MMX instructions +``HAS_AMD_3DNOW`` One if processor supports 3DNow instructions +``HAS_AMD_3DNOW_PLUS`` One if processor supports 3DNow+ instructions ``HAS_IA64`` One if IA64 processor emulating x86 ``HAS_SERIAL_NUMBER`` One if processor has serial number ``PROCESSOR_SERIAL_NUMBER`` Processor serial number diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index 9535bf34f..2f1ab6012 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -4,11 +4,19 @@ cmake_minimum_required Set the minimum required version of cmake for a project and update `Policy Settings`_ to match the version given:: - cmake_minimum_required(VERSION major.minor[.patch[.tweak]] - [FATAL_ERROR]) + cmake_minimum_required(VERSION [...] [FATAL_ERROR]) -If the current version of CMake is lower than that required it will -stop processing the project and report an error. +```` and the optional ```` are each CMake versions of the form +``major.minor[.patch[.tweak]]``, and the ``...`` is literal. + +If the running version of CMake is lower than the ```` required +version it will stop processing the project and report an error. +The optional ```` version, if specified, must be at least the +```` version and affects policy settings as described below. +If the running version of CMake is older than 3.12, the extra ``...`` +dots will be seen as version component separators, resulting in the +``...`` part being ignored and preserving the pre-3.12 behavior +of basing policies on ````. The ``FATAL_ERROR`` option is accepted but ignored by CMake 2.6 and higher. It should be specified so CMake versions 2.4 and lower fail @@ -30,21 +38,23 @@ Policy Settings The ``cmake_minimum_required(VERSION)`` command implicitly invokes the :command:`cmake_policy(VERSION)` command to specify that the current -project code is written for the given version of CMake. -All policies introduced in the specified version or earlier will be -set to use NEW behavior. All policies introduced after the specified -version will be unset. This effectively requests behavior preferred +project code is written for the given range of CMake versions. +All policies known to the running version of CMake and introduced +in the ```` (or ````, if specified) version or earlier will +be set to use ``NEW`` behavior. All policies introduced in later +versions will be unset. This effectively requests behavior preferred as of a given CMake version and tells newer CMake versions to warn about their new policies. -When a version higher than 2.4 is specified the command implicitly -invokes:: +When a ```` version higher than 2.4 is specified the command +implicitly invokes:: - cmake_policy(VERSION major[.minor[.patch[.tweak]]]) + cmake_policy(VERSION [...]) -which sets the cmake policy version level to the version specified. -When version 2.4 or lower is given the command implicitly invokes:: +which sets CMake policies based on the range of versions specified. +When a ```` version 2.4 or lower is given the command implicitly +invokes:: - cmake_policy(VERSION 2.4) + cmake_policy(VERSION 2.4[...]) which enables compatibility features for CMake 2.4 and lower. diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index b51b9512c..c3f7cfb96 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -24,17 +24,25 @@ The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW`` behavior. While setting policies individually is supported, we encourage projects to set policies based on CMake versions:: - cmake_policy(VERSION major.minor[.patch[.tweak]]) - -Specify that the current CMake code is written for the given -version of CMake. All policies introduced in the specified version or -earlier will be set to use ``NEW`` behavior. All policies introduced -after the specified version will be unset (unless the + cmake_policy(VERSION [...]) + +```` and the optional ```` are each CMake versions of the form +``major.minor[.patch[.tweak]]``, and the ``...`` is literal. The ```` +version must be at least ``2.4`` and at most the running version of CMake. +The ```` version, if specified, must be at least the ```` version +but may exceed the running version of CMake. If the running version of +CMake is older than 3.12, the extra ``...`` dots will be seen as version +component separators, resulting in the ``...`` part being ignored and +preserving the pre-3.12 behavior of basing policies on ````. + +This specifies that the current CMake code is written for the given +range of CMake versions. All policies known to the running version of CMake +and introduced in the ```` (or ````, if specified) version +or earlier will be set to use ``NEW`` behavior. All policies +introduced in later versions will be unset (unless the :variable:`CMAKE_POLICY_DEFAULT_CMP` variable sets a default). This effectively requests behavior preferred as of a given CMake version and tells newer CMake versions to warn about their new policies. -The policy version specified must be at least 2.4 or the command will -report an error. Note that the :command:`cmake_minimum_required(VERSION)` command implicitly calls ``cmake_policy(VERSION)`` too. diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index 63db32f4e..6db9a485a 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -5,21 +5,78 @@ Starts the testing for a given model :: - ctest_start(Model [TRACK ] [APPEND] [source [binary]] [QUIET]) + ctest_start( [ []] [TRACK ] [QUIET]) + + ctest_start([ [ []]] [TRACK ] APPEND [QUIET]) Starts the testing for a given model. The command should be called -after the binary directory is initialized. If the 'source' and -'binary' directory are not specified, it reads the -:variable:`CTEST_SOURCE_DIRECTORY` and :variable:`CTEST_BINARY_DIRECTORY`. -If the track is -specified, the submissions will go to the specified track. If APPEND -is used, the existing TAG is used rather than creating a new one based -on the current time stamp. If ``QUIET`` is used, CTest will suppress any -non-error messages that it otherwise would have printed to the console. - -If the :variable:`CTEST_CHECKOUT_COMMAND` variable -(or the :variable:`CTEST_CVS_CHECKOUT` variable) -is set, its content is treated as command-line. The command is -invoked with the current working directory set to the parent of the source -directory, even if the source directory already exists. This can be used -to create the source tree from a version control repository. +after the binary directory is initialized. + +The parameters are as follows: + +```` + Set the dashboard model. Must be one of ``Experimental``, ``Continuous``, or + ``Nightly``. This parameter is required unless ``APPEND`` is specified. + +```` + Set the source directory. If not specified, the value of + :variable:`CTEST_SOURCE_DIRECTORY` is used instead. + +```` + Set the binary directory. If not specified, the value of + :variable:`CTEST_BINARY_DIRECTORY` is used instead. + +``TRACK `` + If ``TRACK`` is used, the submissions will go to the specified track on the + CDash server. If no ``TRACK`` is specified, the name of the model is used by + default. + +``APPEND`` + If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new + one based on the current time stamp. If you use ``APPEND``, you can omit the + ```` and ``TRACK `` parameters, because they will be read from + the generated ``TAG`` file. For example: + + .. code-block:: cmake + + ctest_start(Experimental TRACK TrackExperimental) + + Later, in another ``ctest -S`` script: + + .. code-block:: cmake + + ctest_start(APPEND) + + When the second script runs ``ctest_start(APPEND)``, it will read the + ``Experimental`` model and ``TrackExperimental`` track from the ``TAG`` file + generated by the first ``ctest_start()`` command. Please note that if you + call ``ctest_start(APPEND)`` and specify a different model or track than + in the first ``ctest_start()`` command, a warning will be issued, and the + new model and track will be used. + +``QUIET`` + If ``QUIET`` is used, CTest will suppress any non-error messages that it + otherwise would have printed to the console. + +The parameters for ``ctest_start()`` can be issued in any order, with the +exception that ````, ````, and ```` have to appear +in that order with respect to each other. The following are all valid and +equivalent: + +.. code-block:: cmake + + ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND) + + ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary) + + ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack path/to/binary) + +However, for the sake of readability, it is recommended that you order your +parameters in the order listed at the top of this page. + +If the :variable:`CTEST_CHECKOUT_COMMAND` variable (or the +:variable:`CTEST_CVS_CHECKOUT` variable) is set, its content is treated as +command-line. The command is invoked with the current working directory set +to the parent of the source directory, even if the source directory already +exists. This can be used to create the source tree from a version control +repository. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index 6b49da392..cc9612bcc 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -68,7 +68,7 @@ Submit to CDash Upload API [QUIET]) This second signature is used to upload files to CDash via the CDash -file upload API. The api first sends a request to upload to CDash along +file upload API. The API first sends a request to upload to CDash along 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. diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst index 873c6cabb..da2631c09 100644 --- a/Help/command/define_property.rst +++ b/Help/command/define_property.rst @@ -34,10 +34,24 @@ actual scope needs to be given; only the kind of scope is important. The required ``PROPERTY`` option is immediately followed by the name of the property being defined. -If the ``INHERITED`` option then the :command:`get_property` command will -chain up to the next higher scope when the requested property is not set -in the scope given to the command. ``DIRECTORY`` scope chains to -``GLOBAL``. ``TARGET``, ``SOURCE``, and ``TEST`` chain to ``DIRECTORY``. +If the ``INHERITED`` option is given, then the :command:`get_property` command +will chain up to the next higher scope when the requested property is not set +in the scope given to the command. + +* ``DIRECTORY`` scope chains to its parent directory's scope, continuing the + walk up parent directories until a directory has the property set or there + are no more parents. If still not found at the top level directory, it + chains to the ``GLOBAL`` scope. +* ``TARGET``, ``SOURCE`` and ``TEST`` properties chain to ``DIRECTORY`` scope, + including further chaining up the directories, etc. as needed. + +Note that this scope chaining behavior only applies to calls to +:command:`get_property`, :command:`get_directory_property`, +:command:`get_target_property`, :command:`get_source_file_property` and +:command:`get_test_property`. There is no inheriting behavior when *setting* +properties, so using ``APPEND`` or ``APPEND_STRING`` with the +:command:`set_property` command will not consider inherited values when working +out the contents to append to. The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be associated with the property as its brief and full documentation. diff --git a/Help/command/export.rst b/Help/command/export.rst index 53675a756..0c676c6a7 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -40,6 +40,15 @@ policy CMP0022 is NEW. If a library target is included in the export but a target to which it links is not included the behavior is unspecified. +.. note:: + + :ref:`Object Libraries` under :generator:`Xcode` have special handling if + multiple architectures are listed in :variable:`CMAKE_OSX_ARCHITECTURES`. + In this case they will be exported as :ref:`Interface Libraries` with + no object files available to clients. This is sufficient to satisfy + transitive usage requirements of other targets that link to the + object libraries in their implementation. + :: export(PACKAGE ) diff --git a/Help/command/file.rst b/Help/command/file.rst index 5ce86e5cc..d4a60062d 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -3,23 +3,44 @@ file File manipulation command. ------------------------------------------------------------------------------- +Synopsis +^^^^^^^^ -:: +.. parsed-literal:: - file(WRITE ...) - file(APPEND ...) + `Reading`_ + file(`READ`_ [...]) + file(`STRINGS`_ [...]) + file(`\ `_ ) + file(`TIMESTAMP`_ [...]) -Write ```` into a file called ````. If the file does -not exist, it will be created. If the file already exists, ``WRITE`` -mode will overwrite it and ``APPEND`` mode will append to the end. -Any directories in the path specified by ```` that do not -exist will be created. + `Writing`_ + file({`WRITE`_ | `APPEND`_} ...) + file({`TOUCH`_ | `TOUCH_NOCREATE`_} [...]) + file(`GENERATE`_ OUTPUT [...]) -If the file is a build input, use the :command:`configure_file` command -to update the file only when its content changes. + `Filesystem`_ + file({`GLOB`_ | `GLOB_RECURSE`_} [...] [...]) + file(`RENAME`_ ) + file({`REMOVE`_ | `REMOVE_RECURSE`_ } [...]) + file(`MAKE_DIRECTORY`_ [...]) + file({`COPY`_ | `INSTALL`_} ... DESTINATION [...]) + + `Path Conversion`_ + file(`RELATIVE_PATH`_ ) + file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} ) + + `Transfer`_ + file(`DOWNLOAD`_ [...]) + file(`UPLOAD`_ [...]) + + `Locking`_ + file(`LOCK`_ [...]) + +Reading +^^^^^^^ ------------------------------------------------------------------------------- +.. _READ: :: @@ -31,7 +52,7 @@ Read content from a file called ```` and store it in a read at most ```` bytes. The ``HEX`` option causes data to be converted to a hexadecimal representation (useful for binary data). ------------------------------------------------------------------------------- +.. _STRINGS: :: @@ -82,7 +103,7 @@ For example, the code stores a list in the variable ``myfile`` in which each item is a line from the input file. ------------------------------------------------------------------------------- +.. _HASH: :: @@ -93,15 +114,116 @@ store it in a ````. The supported ```` algorithm names are those listed by the :ref:`string(\) ` command. ------------------------------------------------------------------------------- +.. _TIMESTAMP: + +:: + + file(TIMESTAMP [] [UTC]) + +Compute a string representation of the modification time of ```` +and store it in ````. Should the command be unable to obtain a +timestamp variable will be set to the empty string (""). + +See the :command:`string(TIMESTAMP)` command for documentation of +the ```` and ``UTC`` options. + +Writing +^^^^^^^ + +.. _WRITE: +.. _APPEND: + +:: + + file(WRITE ...) + file(APPEND ...) + +Write ```` into a file called ````. If the file does +not exist, it will be created. If the file already exists, ``WRITE`` +mode will overwrite it and ``APPEND`` mode will append to the end. +Any directories in the path specified by ```` that do not +exist will be created. + +If the file is a build input, use the :command:`configure_file` command +to update the file only when its content changes. + +.. _TOUCH: +.. _TOUCH_NOCREATE: + +:: + + file(TOUCH [...]) + file(TOUCH_NOCREATE [...]) + +Create a file with no content if it does not yet exist. If the file already +exists, its access and/or modification will be updated to the time when the +function call is executed. + +Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file +does not exist it will be silently ignored. + +With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be +modified. + +.. _GENERATE: + +:: + + file(GENERATE OUTPUT output-file + + [CONDITION expression]) + +Generate an output file for each build configuration supported by the current +:manual:`CMake Generator `. Evaluate +:manual:`generator expressions ` +from the input content to produce the output content. The options are: + +``CONDITION `` + Generate the output file for a particular configuration only if + the condition is true. The condition must be either ``0`` or ``1`` + after evaluating generator expressions. + +``CONTENT `` + Use the content given explicitly as input. + +``INPUT `` + Use the content from a given file as input. + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. + +``OUTPUT `` + Specify the output file name to generate. Use generator expressions + such as ``$`` to specify a configuration-specific output file + name. Multiple configurations may generate the same output file only + if the generated content is identical. Otherwise, the ```` + must evaluate to an unique name for each configuration. + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. + +Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific +``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. +Generated files are modified and their timestamp updated on subsequent cmake +runs only if their content is changed. + +Note also that ``file(GENERATE)`` does not create the output file until the +generation phase. The output file will not yet have been written when the +``file(GENERATE)`` command returns, it is written only after processing all +of a project's ``CMakeLists.txt`` files. + +Filesystem +^^^^^^^^^^ + +.. _GLOB: +.. _GLOB_RECURSE: :: file(GLOB - [LIST_DIRECTORIES true|false] [RELATIVE ] + [LIST_DIRECTORIES true|false] [RELATIVE ] [CONFIGURE_DEPENDS] [...]) file(GLOB_RECURSE [FOLLOW_SYMLINKS] - [LIST_DIRECTORIES true|false] [RELATIVE ] + [LIST_DIRECTORIES true|false] [RELATIVE ] [CONFIGURE_DEPENDS] [...]) Generate a list of files that match the ```` and @@ -110,6 +232,11 @@ regular expressions, but much simpler. If ``RELATIVE`` flag is specified, the results will be returned as relative paths to the given path. The results will be ordered lexicographically. +If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic +to the main build system check target to rerun the flagged ``GLOB`` commands +at build time. If any of the outputs change, CMake will regenerate the build +system. + By default ``GLOB`` lists directories - directories are omitted in result if ``LIST_DIRECTORIES`` is set to false. @@ -118,6 +245,10 @@ By default ``GLOB`` lists directories - directories are omitted in result if your source tree. If no CMakeLists.txt file changes when a source is added or removed then the generated build system cannot know when to ask CMake to regenerate. + The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or if + a new generator is added in the future that cannot support it, projects using + it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there is + still a cost to perform the check on every rebuild. Examples of globbing expressions include:: @@ -139,7 +270,7 @@ Examples of recursive globbing include:: /dir/*.py - match all python files in /dir and subdirectories ------------------------------------------------------------------------------- +.. _RENAME: :: @@ -148,7 +279,8 @@ Examples of recursive globbing include:: Move a file or directory within a filesystem from ```` to ````, replacing the destination atomically. ------------------------------------------------------------------------------- +.. _REMOVE: +.. _REMOVE_RECURSE: :: @@ -159,7 +291,7 @@ Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given files and directories, also non-empty directories. No error is emitted if a given file does not exist. ------------------------------------------------------------------------------- +.. _MAKE_DIRECTORY: :: @@ -167,7 +299,44 @@ given file does not exist. Create the given directories and their parents as needed. ------------------------------------------------------------------------------- +.. _COPY: +.. _INSTALL: + +:: + + file( ... DESTINATION + [FILE_PERMISSIONS ...] + [DIRECTORY_PERMISSIONS ...] + [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] + [FILES_MATCHING] + [[PATTERN | REGEX ] + [EXCLUDE] [PERMISSIONS ...]] [...]) + +The ``COPY`` signature copies files, directories, and symlinks to a +destination folder. Relative input paths are evaluated with respect +to the current source directory, and a relative destination is +evaluated with respect to the current build directory. Copying +preserves input file timestamps, and optimizes out a file if it exists +at the destination with the same timestamp. Copying preserves input +permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` +are given (default is ``USE_SOURCE_PERMISSIONS``). + +See the :command:`install(DIRECTORY)` command for documentation of +permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and +``EXCLUDE`` options. Copying directories preserves the structure +of their content even if options are used to select a subset of +files. + +The ``INSTALL`` signature differs slightly from ``COPY``: it prints +status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), +and ``NO_SOURCE_PERMISSIONS`` is default. +Installation scripts generated by the :command:`install` command +use this signature (with some undocumented options for internal use). + +Path Conversion +^^^^^^^^^^^^^^^ + +.. _RELATIVE_PATH: :: @@ -176,7 +345,8 @@ Create the given directories and their parents as needed. Compute the relative path from a ```` to a ```` and store it in the ````. ------------------------------------------------------------------------------- +.. _TO_CMAKE_PATH: +.. _TO_NATIVE_PATH: :: @@ -194,7 +364,11 @@ path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere). Always use double quotes around the ```` to be sure it is treated as a single argument to this command. ------------------------------------------------------------------------------- +Transfer +^^^^^^^^ + +.. _DOWNLOAD: +.. _UPLOAD: :: @@ -281,99 +455,10 @@ check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content. If neither ``TLS`` option is given CMake will check variables ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively. ------------------------------------------------------------------------------- - -:: - - file(TIMESTAMP [] [UTC]) - -Compute a string representation of the modification time of ```` -and store it in ````. Should the command be unable to obtain a -timestamp variable will be set to the empty string (""). - -See the :command:`string(TIMESTAMP)` command for documentation of -the ```` and ``UTC`` options. - ------------------------------------------------------------------------------- - -:: - - file(GENERATE OUTPUT output-file - - [CONDITION expression]) - -Generate an output file for each build configuration supported by the current -:manual:`CMake Generator `. Evaluate -:manual:`generator expressions ` -from the input content to produce the output content. The options are: - -``CONDITION `` - Generate the output file for a particular configuration only if - the condition is true. The condition must be either ``0`` or ``1`` - after evaluating generator expressions. - -``CONTENT `` - Use the content given explicitly as input. - -``INPUT `` - Use the content from a given file as input. - A relative path is treated with respect to the value of - :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. - -``OUTPUT `` - Specify the output file name to generate. Use generator expressions - such as ``$`` to specify a configuration-specific output file - name. Multiple configurations may generate the same output file only - if the generated content is identical. Otherwise, the ```` - must evaluate to an unique name for each configuration. - A relative path (after evaluating generator expressions) is treated - with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. - See policy :policy:`CMP0070`. - -Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific -``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. -Generated files are modified and their timestamp updated on subsequent cmake -runs only if their content is changed. - -Note also that ``file(GENERATE)`` does not create the output file until the -generation phase. The output file will not yet have been written when the -``file(GENERATE)`` command returns, it is written only after processing all -of a project's ``CMakeLists.txt`` files. - ------------------------------------------------------------------------------- - -:: - - file( ... DESTINATION - [FILE_PERMISSIONS ...] - [DIRECTORY_PERMISSIONS ...] - [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] - [FILES_MATCHING] - [[PATTERN | REGEX ] - [EXCLUDE] [PERMISSIONS ...]] [...]) - -The ``COPY`` signature copies files, directories, and symlinks to a -destination folder. Relative input paths are evaluated with respect -to the current source directory, and a relative destination is -evaluated with respect to the current build directory. Copying -preserves input file timestamps, and optimizes out a file if it exists -at the destination with the same timestamp. Copying preserves input -permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` -are given (default is ``USE_SOURCE_PERMISSIONS``). - -See the :command:`install(DIRECTORY)` command for documentation of -permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and -``EXCLUDE`` options. Copying directories preserves the structure -of their content even if options are used to select a subset of -files. - -The ``INSTALL`` signature differs slightly from ``COPY``: it prints -status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), -and ``NO_SOURCE_PERMISSIONS`` is default. -Installation scripts generated by the :command:`install` command -use this signature (with some undocumented options for internal use). +Locking +^^^^^^^ ------------------------------------------------------------------------------- +.. _LOCK: :: diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index e56097bea..2a14ad72f 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -8,6 +8,9 @@ find_file .. |prefix_XXX_SUBDIR| replace:: ``/include`` .. |entry_XXX_SUBDIR| replace:: ``/include`` +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: + ``/include/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``/include/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index f774f17ec..0861d6789 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -8,6 +8,9 @@ find_library .. |prefix_XXX_SUBDIR| replace:: ``/lib`` .. |entry_XXX_SUBDIR| replace:: ``/lib`` +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: + ``/lib/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, + and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``/lib/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index b2e70f2ad..a4416abd3 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -64,6 +64,7 @@ The complete Config mode command signature is:: [PATHS path1 [path2 ... ]] [PATH_SUFFIXES suffix1 [suffix2 ...]] [NO_DEFAULT_PATH] + [NO_PACKAGE_ROOT_PATH] [NO_CMAKE_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] @@ -208,12 +209,12 @@ Each entry is meant for installation trees following Windows (W), UNIX /(cmake|CMake)/ (W) /*/ (W) /*/(cmake|CMake)/ (W) - /(lib/|lib|share)/cmake/*/ (U) - /(lib/|lib|share)/*/ (U) - /(lib/|lib|share)/*/(cmake|CMake)/ (U) - /*/(lib/|lib|share)/cmake/*/ (W/U) - /*/(lib/|lib|share)/*/ (W/U) - /*/(lib/|lib|share)/*/(cmake|CMake)/ (W/U) + /(lib/|lib*|share)/cmake/*/ (U) + /(lib/|lib*|share)/*/ (U) + /(lib/|lib*|share)/*/(cmake|CMake)/ (U) + /*/(lib/|lib*|share)/cmake/*/ (W/U) + /*/(lib/|lib*|share)/*/ (W/U) + /*/(lib/|lib*|share)/*/(cmake|CMake)/ (W/U) On systems supporting OS X Frameworks and Application Bundles the following directories are searched for frameworks or bundles @@ -228,10 +229,22 @@ containing a configuration file:: In all cases the ```` is treated as case-insensitive and corresponds to any of the names specified (```` or names given by ``NAMES``). + Paths with ``lib/`` are enabled if the -:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. If ``PATH_SUFFIXES`` -is specified the suffixes are appended to each (W) or (U) directory entry -one-by-one. +:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one +or more of the values ``lib64``, ``lib32``, ``libx32`` or ``lib`` (searched in +that order). + +* Paths with ``lib64`` are searched on 64 bit platforms if the + :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` property is set to ``TRUE``. +* Paths with ``lib32`` are searched on 32 bit platforms if the + :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` property is set to ``TRUE``. +* Paths with ``libx32`` are searched on platforms using the x32 ABI + if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``. +* The ``lib`` path is always searched. + +If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each +(W) or (U) directory entry one-by-one. This set of directories is intended to work in cooperation with projects that provide configuration files in their installation trees. @@ -249,7 +262,16 @@ 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 :variable:`_ROOT` CMake + variable and the :envvar:`_ROOT` environment variable, + where ```` is the package to be found. + 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. + See policy :policy:`CMP0074`. + +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 `. This can be skipped if ``NO_CMAKE_PATH`` is passed:: @@ -258,7 +280,7 @@ enabled. CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH -2. Search paths specified in cmake-specific environment variables. +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). @@ -269,26 +291,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:: @@ -296,14 +318,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 diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index 76342d020..988a3fae4 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -8,6 +8,9 @@ find_path .. |prefix_XXX_SUBDIR| replace:: ``/include`` .. |entry_XXX_SUBDIR| replace:: ``/include`` +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: + ``/include/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``/include/`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index d3430c054..4f00773b3 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -8,6 +8,8 @@ find_program .. |prefix_XXX_SUBDIR| replace:: ``/[s]bin`` .. |entry_XXX_SUBDIR| replace:: ``/[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` diff --git a/Help/command/get_directory_property.rst b/Help/command/get_directory_property.rst index e50abe0e9..bf8349cb1 100644 --- a/Help/command/get_directory_property.rst +++ b/Help/command/get_directory_property.rst @@ -7,11 +7,16 @@ Get a property of ``DIRECTORY`` scope. get_directory_property( [DIRECTORY ] ) -Store a property of directory scope in the named variable. If the -property is not defined the empty-string is returned. The ``DIRECTORY`` -argument specifies another directory from which to retrieve the -property value. The specified directory must have already been -traversed by CMake. +Store a property of directory scope in the named ````. +The ``DIRECTORY`` argument specifies another directory from which +to retrieve the property value instead of the current directory. +The specified directory must have already been traversed by CMake. + +If the property is not defined for the nominated directory scope, +an empty string is returned. In the case of ``INHERITED`` properties, +if the property is not found for the nominated directory scope, +the search will chain to a parent scope as described for the +:command:`define_property` command. :: diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index 14c8cf279..f11c0fce6 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -45,7 +45,7 @@ to the given base directory ````. If no base directory is provided, the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. -Paths are returned with forward slashes and have no trailing slahes. If the +Paths are returned with forward slashes and have no trailing slashes. If the optional ``CACHE`` argument is specified, the result variable is added to the cache. diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index 632ece65c..8b85f7d6f 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -50,7 +50,10 @@ be one of the following: The required ``PROPERTY`` option is immediately followed by the name of the property to get. If the property is not set an empty value is -returned. If the ``SET`` option is given the variable is set to a boolean +returned, although some properties support inheriting from a parent scope +if defined to behave that way (see :command:`define_property`). + +If the ``SET`` option is given the variable is set to a boolean value indicating whether the property has been set. If the ``DEFINED`` option is given the variable is set to a boolean value indicating whether the property has been defined such as with the diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst index 3e975c2f9..51fbd33a6 100644 --- a/Help/command/get_source_file_property.rst +++ b/Help/command/get_source_file_property.rst @@ -8,9 +8,15 @@ Get a property for a source file. get_source_file_property(VAR file property) Get a property from a source file. The value of the property is -stored in the variable ``VAR``. If the property is not found, ``VAR`` -will be set to "NOTFOUND". Use :command:`set_source_files_properties` -to set property values. Source file properties usually control how the -file is built. One property that is always there is :prop_sf:`LOCATION` +stored in the variable ``VAR``. If the source property is not found, the +behavior depends on whether it has been defined to be an ``INHERITED`` property +or not (see :command:`define_property`). Non-inherited properties will set +``VAR`` to "NOTFOUND", whereas inherited properties will search the relevant +parent scope as described for the :command:`define_property` command and +if still unable to find the property, ``VAR`` will be set to an empty string. + +Use :command:`set_source_files_properties` to set property values. Source +file properties usually control how the file is built. One property that is +always there is :prop_sf:`LOCATION`. See also the more general :command:`get_property` command. diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst index 2a72c3af7..98e9db30a 100644 --- a/Help/command/get_target_property.rst +++ b/Help/command/get_target_property.rst @@ -8,8 +8,15 @@ Get a property from a target. get_target_property(VAR target property) Get a property from a target. The value of the property is stored in -the variable ``VAR``. If the property is not found, ``VAR`` will be set to -"NOTFOUND". Use :command:`set_target_properties` to set property values. +the variable ``VAR``. If the target property is not found, the behavior +depends on whether it has been defined to be an ``INHERITED`` property +or not (see :command:`define_property`). Non-inherited properties will +set ``VAR`` to "NOTFOUND", whereas inherited properties will search the +relevant parent scope as described for the :command:`define_property` +command and if still unable to find the property, ``VAR`` will be set to +an empty string. + +Use :command:`set_target_properties` to set target property values. Properties are usually used to control how a target is built, but some query the target instead. This command can get properties for any target so far created. The targets do not need to be in the current diff --git a/Help/command/get_test_property.rst b/Help/command/get_test_property.rst index e359f4b3d..555c3b26d 100644 --- a/Help/command/get_test_property.rst +++ b/Help/command/get_test_property.rst @@ -8,8 +8,14 @@ Get a property of the test. get_test_property(test property VAR) Get a property from the test. The value of the property is stored in -the variable ``VAR``. If the test or property is not found, ``VAR`` will -be set to "NOTFOUND". For a list of standard properties you can type -``cmake --help-property-list``. +the variable ``VAR``. If the test property is not found, the behavior +depends on whether it has been defined to be an ``INHERITED`` property +or not (see :command:`define_property`). Non-inherited properties will +set ``VAR`` to "NOTFOUND", whereas inherited properties will search the +relevant parent scope as described for the :command:`define_property` +command and if still unable to find the property, ``VAR`` will be set to +an empty string. + +For a list of standard properties you can type ``cmake --help-property-list``. See also the more general :command:`get_property` command. diff --git a/Help/command/install.rst b/Help/command/install.rst index 2506f98c5..6cea996f0 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -1,11 +1,19 @@ install ------- -.. only:: html +Specify rules to run at install time. - .. contents:: +Synopsis +^^^^^^^^ -Specify rules to run at install time. +.. parsed-literal:: + + install(`TARGETS`_ ... [...]) + install({`FILES`_ | `PROGRAMS`_} ... DESTINATION [...]) + install(`DIRECTORY`_ ... DESTINATION [...]) + install(`SCRIPT`_ [...]) + install(`CODE`_ [...]) + install(`EXPORT`_ DESTINATION [...]) Introduction ^^^^^^^^^^^^ @@ -84,6 +92,8 @@ to control which messages are printed. Installing Targets ^^^^^^^^^^^^^^^^^^ +.. _TARGETS: + :: install(TARGETS targets... [EXPORT ] @@ -93,6 +103,7 @@ Installing Targets [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT ] + [NAMELINK_COMPONENT ] [OPTIONAL] [EXCLUDE_FROM_ALL] [NAMELINK_ONLY|NAMELINK_SKIP] ] [...] @@ -100,63 +111,144 @@ Installing Targets ) The ``TARGETS`` form specifies rules for installing targets from a -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. -Module libraries are always treated as ``LIBRARY`` targets. -For non-DLL platforms shared libraries are treated as ``LIBRARY`` -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. 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). - -The ``PRIVATE_HEADER``, ``PUBLIC_HEADER``, and ``RESOURCE`` arguments -cause subsequent properties to be applied to installing a ``FRAMEWORK`` -shared library target's associated files on non-Apple platforms. Rules -defined by these arguments are ignored on Apple platforms because the -associated files are installed into the appropriate locations inside -the framework folder. See documentation of the -:prop_tgt:`PRIVATE_HEADER`, :prop_tgt:`PUBLIC_HEADER`, and -:prop_tgt:`RESOURCE` target properties for details. - -Either ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` may be specified as a -``LIBRARY`` option. On some platforms a versioned shared library -has a symbolic link such as:: - - lib.so -> lib.so.1 - -where ``lib.so.1`` is the soname of the library and ``lib.so`` -is a "namelink" allowing linkers to find the library when given -``-l``. The ``NAMELINK_ONLY`` option causes installation of only the -namelink when a library target is installed. The ``NAMELINK_SKIP`` option -causes installation of library files other than the namelink when a -library target is installed. When neither option is given both -portions are installed. On platforms where versioned shared libraries -do not have namelinks or when a library is not versioned the -``NAMELINK_SKIP`` option installs the library and the ``NAMELINK_ONLY`` -option installs nothing. See the :prop_tgt:`VERSION` and -:prop_tgt:`SOVERSION` target properties for details on creating versioned -shared libraries. - -The ``INCLUDES DESTINATION`` specifies a list of directories -which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` -target property of the ```` when exported by the -:command:`install(EXPORT)` command. If a relative path is -specified, it is treated as relative to the ``$``. -This is independent of the rest of the argument groups and does -not actually install anything. +project. There are several kinds of target files that may be installed: + +``ARCHIVE`` + Static libraries are treated as ``ARCHIVE`` targets, except those + marked with the ``FRAMEWORK`` property on OS X (see ``FRAMEWORK`` + below.) For DLL platforms (all Windows-based systems including + Cygwin), the DLL import library is treated as an ``ARCHIVE`` target. + +``LIBRARY`` + Module libraries are always treated as ``LIBRARY`` targets. For non- + DLL platforms shared libraries are treated as ``LIBRARY`` targets, + except those marked with the ``FRAMEWORK`` property on OS X (see + ``FRAMEWORK`` below.) + +``RUNTIME`` + Executables are treated as ``RUNTIME`` objects, except those marked + with the ``MACOSX_BUNDLE`` property on OS X (see ``BUNDLE`` below.) + For DLL platforms (all Windows-based systems including Cygwin), the + DLL part of a shared library is treated as a ``RUNTIME`` target. + +``OBJECTS`` + Object libraries (a simple group of object files) are always treated + as ``OBJECTS`` targets. + +``FRAMEWORK`` + Both static and shared libraries marked with the ``FRAMEWORK`` + property are treated as ``FRAMEWORK`` targets on OS X. + +``BUNDLE`` + Executables marked with the ``MACOSX_BUNDLE`` property are treated as + ``BUNDLE`` targets on OS X. + +``PUBLIC_HEADER`` + Any ``PUBLIC_HEADER`` files associated with a library are installed in + the destination specified by the ``PUBLIC_HEADER`` argument on non-Apple + platforms. Rules defined by this argument are ignored for ``FRAMEWORK`` + libraries on Apple platforms because the associated files are installed + into the appropriate locations inside the framework folder. See + :prop_tgt:`PUBLIC_HEADER` for details. + +``PRIVATE_HEADER`` + Similar to ``PUBLIC_HEADER``, but for ``PRIVATE_HEADER`` files. See + :prop_tgt:`PRIVATE_HEADER` for details. + +``RESOURCE`` + Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for + ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details. + +For each of these arguments given, the arguments following them only apply +to the target or file type specified in the argument. 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.) + +In addition to the common options listed above, each target can accept +the following additional arguments: + +``NAMELINK_COMPONENT`` + On some platforms a versioned shared library has a symbolic link such + as:: + + lib.so -> lib.so.1 + + where ``lib.so.1`` is the soname of the library and ``lib.so`` + is a "namelink" allowing linkers to find the library when given + ``-l``. The ``NAMELINK_COMPONENT`` option is similar to the + ``COMPONENT`` option, but it changes the installation component of a shared + library namelink if one is generated. If not specified, this defaults to the + value of ``COMPONENT``. It is an error to use this parameter outside of a + ``LIBRARY`` block. + + Consider the following example: + + .. code-block:: cmake + + install(TARGETS mylib + LIBRARY + DESTINATION lib + COMPONENT Libraries + NAMELINK_COMPONENT Development + PUBLIC_HEADER + DESTINATION include + COMPONENT Development + ) + + In this scenario, if you choose to install only the ``Development`` + component, both the headers and namelink will be installed without the + library. (If you don't also install the ``Libraries`` component, the + namelink will be a dangling symlink, and projects that link to the library + will have build errors.) If you install only the ``Libraries`` component, + only the library will be installed, without the headers and namelink. + + This option is typically used for package managers that have separate + runtime and development packages. For example, on Debian systems, the + library is expected to be in the runtime package, and the headers and + namelink are expected to be in the development package. + + See the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties for + details on creating versioned shared libraries. + +``NAMELINK_ONLY`` + This option causes the installation of only the namelink when a library + target is installed. On platforms where versioned shared libraries do not + have namelinks or when a library is not versioned, the ``NAMELINK_ONLY`` + option installs nothing. It is an error to use this parameter outside of a + ``LIBRARY`` block. + + When ``NAMELINK_ONLY`` is given, either ``NAMELINK_COMPONENT`` or + ``COMPONENT`` may be used to specify the installation component of the + namelink, but ``COMPONENT`` should generally be preferred. + +``NAMELINK_SKIP`` + Similar to ``NAMELINK_ONLY``, but it has the opposite effect: it causes the + installation of library files other than the namelink when a library target + is installed. When neither ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` are given, + both portions are installed. On platforms where versioned shared libraries + do not have symlinks or when a library is not versioned, ``NAMELINK_SKIP`` + installs the library. It is an error to use this parameter outside of a + ``LIBRARY`` block. + + If ``NAMELINK_SKIP`` is specified, ``NAMELINK_COMPONENT`` has no effect. It + is not recommended to use ``NAMELINK_SKIP`` in conjunction with + ``NAMELINK_COMPONENT``. + +The ``install(TARGETS)`` command can also accept the following options at the +top level: + +``EXPORT`` + This option associates the installed target files with an export called + ````. It must appear before any target options. To actually + install the export file itself, call ``install(EXPORT)``, documented below. + +``INCLUDES DESTINATION`` + This option specifies a list of directories which will be added to the + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the + ```` when exported by the :command:`install(EXPORT)` command. If a + relative path is specified, it is treated as relative to the + ``$``. One or more groups of properties may be specified in a single call to the ``TARGETS`` form of this command. A target may be installed more than @@ -178,10 +270,12 @@ the ``mySharedLib`` DLL will be installed to ``/bin`` and ``/some/full/path`` and its import library will be installed to ``/lib/static`` and ``/some/full/path``. -The ``EXPORT`` option associates the installed target files with an -export called ````. It must appear before any ``RUNTIME``, -``LIBRARY``, ``ARCHIVE``, or ``OBJECTS`` options. To actually install the -export file itself, call ``install(EXPORT)``, documented below. +:ref:`Interface Libraries` may be listed among the targets to install. +They install no artifacts but will be included in an associated ``EXPORT``. +If :ref:`Object Libraries` are listed but given no destination for their +object files, they will be exported as :ref:`Interface Libraries`. +This is sufficient to satisfy transitive usage requirements of other +targets that link to the object libraries in their implementation. Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property set to ``TRUE`` has undefined behavior. @@ -193,6 +287,9 @@ use "generator expressions" with the syntax ``$<...>``. See the Installing Files ^^^^^^^^^^^^^^^^ +.. _FILES: +.. _PROGRAMS: + :: install( files... DESTINATION @@ -226,6 +323,8 @@ use "generator expressions" with the syntax ``$<...>``. See the Installing Directories ^^^^^^^^^^^^^^^^^^^^^^ +.. _DIRECTORY: + :: install(DIRECTORY dirs... DESTINATION @@ -307,6 +406,9 @@ manual for available expressions. Custom Installation Logic ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _CODE: +.. _SCRIPT: + :: install([[SCRIPT ] [CODE ]] @@ -328,16 +430,18 @@ will print a message during installation. Installing Exports ^^^^^^^^^^^^^^^^^^ +.. _EXPORT: + :: install(EXPORT DESTINATION [NAMESPACE ] [[FILE .cmake]| - [EXPORT_ANDROID_MK .mk]] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [EXPORT_LINK_INTERFACE_LIBRARIES] [COMPONENT ] [EXCLUDE_FROM_ALL]) + install(EXPORT_ANDROID_MK DESTINATION [...]) The ``EXPORT`` form generates and installs a CMake file containing code to import targets from the installation tree into another project. @@ -354,14 +458,28 @@ generated import file will reference only the matching target configurations. The ``EXPORT_LINK_INTERFACE_LIBRARIES`` keyword, if present, causes the contents of the properties matching ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_)?`` to be exported, when -policy :policy:`CMP0022` is ``NEW``. If a ``COMPONENT`` option is -specified that does not match that given to the targets associated with -```` the behavior is undefined. If a library target is -included in the export but a target to which it links is not included -the behavior is unspecified. - -In addition to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe -used to specify an export to the android ndk build system. The Android +policy :policy:`CMP0022` is ``NEW``. + +When a ``COMPONENT`` option is given, the listed ```` implicitly +depends on all components mentioned in the export set. The exported +``.cmake`` file will require each of the exported components to be +present in order for dependent projects to build properly. For example, a +project may define components ``Runtime`` and ``Development``, with shared +libraries going into the ``Runtime`` component and static libraries and +headers going into the ``Development`` component. The export set would also +typically be part of the ``Development`` component, but it would export +targets from both the ``Runtime`` and ``Development`` components. Therefore, +the ``Runtime`` component would need to be installed if the ``Development`` +component was installed, but not vice versa. If the ``Development`` component +was installed without the ``Runtime`` component, dependent projects that try +to link against it would have build errors. Package managers, such as APT and +RPM, typically handle this by listing the ``Runtime`` component as a dependency +of the ``Development`` component in the package metadata, ensuring that the +library is always installed if the headers and CMake export file are present. + +In addition to cmake language files, the ``EXPORT_ANDROID_MK`` mode maybe +used to specify an export to the android ndk build system. This mode +accepts the same options as the normal export mode. The Android NDK supports the use of prebuilt libraries, both static and shared. This allows cmake to build the libraries of a project and make them available to an ndk build system complete with transitive dependencies, include flags @@ -378,7 +496,7 @@ and installed by the current project. For example, the code will install the executable myexe to ``/bin`` and code to import it in the file ``/lib/myproj/myproj.cmake`` and -``/lib/share/ndk-modules/Android.mk``. An outside project +``/share/ndk-modules/Android.mk``. An outside project may load this file with the include command and reference the ``myexe`` executable from the installation tree using the imported target name ``mp_myexe`` as if the target were built in its own tree. @@ -392,3 +510,26 @@ executable from the installation tree using the imported target name those generated by :command:`install_targets`, :command:`install_files`, and :command:`install_programs` commands is not defined. + +Generated Installation Script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``install()`` command generates a file, ``cmake_install.cmake``, inside +the build directory, which is used internally by the generated install target +and by CPack. You can also invoke this script manually with ``cmake -P``. This +script accepts several variables: + +``COMPONENT`` + Set this variable to install only a single CPack component as opposed to all + of them. For example, if you only want to install the ``Development`` + component, run ``cmake -DCOMPONENT=Development -P cmake_install.cmake``. + +``BUILD_TYPE`` + Set this variable to change the build type if you are using a multi-config + generator. For example, to install with the ``Debug`` configuration, run + ``cmake -DBUILD_TYPE=Debug -P cmake_install.cmake``. + +``DESTDIR`` + This is an environment variable rather than a CMake variable. It allows you + to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for + details. diff --git a/Help/command/list.rst b/Help/command/list.rst index f6b75bc19..589e57253 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -3,66 +3,257 @@ list List operations. +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Reading`_ + list(`LENGTH`_ ) + list(`GET`_ [ ...] ) + list(`JOIN`_ ) + list(`SUBLIST`_ ) + + `Search`_ + list(`FIND`_ ) + + `Modification`_ + list(`APPEND`_ [...]) + list(`FILTER`_ {INCLUDE | EXCLUDE} REGEX ) + list(`INSERT`_ [...]) + list(`REMOVE_ITEM`_ ...) + list(`REMOVE_AT`_ ...) + list(`REMOVE_DUPLICATES`_ ) + list(`TRANSFORM`_ [...]) + + `Ordering`_ + list(`REVERSE`_ ) + list(`SORT`_ ) + +Introduction +^^^^^^^^^^^^ + +The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, +``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create +new values for the list within the current CMake variable scope. Similar to +the :command:`set` command, the LIST command creates new variable values in +the current scope, even if the list itself is actually defined in a parent +scope. To propagate the results of these operations upwards, use +:command:`set` with ``PARENT_SCOPE``, :command:`set` with +``CACHE INTERNAL``, or some other means of value propagation. + +.. note:: + + A list in cmake is a ``;`` separated group of strings. To create a + list the set command can be used. For example, ``set(var a b c d e)`` + creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a + string or a list with one item in it. (Note macro arguments are not + variables, and therefore cannot be used in LIST commands.) + +.. note:: + + When specifying index values, if ```` is 0 or greater, it + is indexed from the beginning of the list, with 0 representing the + first list element. If ```` is -1 or lesser, it is indexed + from the end of the list, with -1 representing the last list element. + Be careful when counting with negative indices: they do not start from + 0. -0 is equivalent to 0, the first list element. + +Reading +^^^^^^^ + +.. _LENGTH: + :: list(LENGTH ) - list(GET [ ...] - ) + +Returns the list's length. + +.. _GET: + +:: + + list(GET [ ...] ) + +Returns the list of elements specified by indices from the list. + +.. _JOIN: + +:: + + list(JOIN ) + +Returns a string joining all list's elements using the glue string. +To join multiple strings, which are not part of a list, use ``JOIN`` operator +from :command:`string` command. + +.. _SUBLIST: + +:: + + list(SUBLIST ) + +Returns a sublist of the given list. +If ```` is 0, an empty list will be returned. +If ```` is -1 or the list is smaller than ``+`` then +the remaining elements of the list starting at ```` will be returned. + +Search +^^^^^^ + +.. _FIND: + +:: + + list(FIND ) + +Returns the index of the element specified in the list or -1 +if it wasn't found. + +Modification +^^^^^^^^^^^^ + +.. _APPEND: + +:: + list(APPEND [ ...]) + +Appends elements to the list. + +.. _FILTER: + +:: + list(FILTER REGEX ) - list(FIND ) + +Includes or removes items from the list that match the mode's pattern. +In ``REGEX`` mode, items will be matched against the given regular expression. + +For more information on regular expressions see also the +:command:`string` command. + +.. _INSERT: + +:: + list(INSERT [ ...]) + +Inserts elements to the list to the specified location. + +.. _REMOVE_ITEM: + +:: + list(REMOVE_ITEM [ ...]) + +Removes the given items from the list. + +.. _REMOVE_AT: + +:: + list(REMOVE_AT [ ...]) + +Removes items at given indices from the list. + +.. _REMOVE_DUPLICATES: + +:: + list(REMOVE_DUPLICATES ) - list(REVERSE ) - list(SORT ) -``LENGTH`` will return a given list's length. +Removes duplicated items in the list. -``GET`` will return list of elements specified by indices from the list. +.. _TRANSFORM: -``APPEND`` will append elements to the list. +:: -``FILTER`` will include or remove items from the list that match the -mode's pattern. -In ``REGEX`` mode, items will be matched against the given regular expression. -For more information on regular expressions see also the :command:`string` -command. + list(TRANSFORM [] + [OUTPUT_VARIABLE ]) -``FIND`` will return the index of the element specified in the list or -1 -if it wasn't found. +Transforms the list by applying an action to all or, by specifying a +````, to the selected elements of the list, storing result in-place +or in the specified output variable. -``INSERT`` will insert elements to the list to the specified location. +.. note:: -``REMOVE_AT`` and ``REMOVE_ITEM`` will remove items from the list. The -difference is that ``REMOVE_ITEM`` will remove the given items, while -``REMOVE_AT`` will remove the items at the given indices. + ``TRANSFORM`` sub-command does not change the number of elements of the + list. If a ```` is specified, only some elements will be changed, + the other ones will remain same as before the transformation. -``REMOVE_DUPLICATES`` will remove duplicated items in the list. +```` specify the action to apply to the elements of list. +The actions have exactly the same semantics as sub-commands of +:command:`string` command. -``REVERSE`` reverses the contents of the list in-place. +The ```` may be one of: -``SORT`` sorts the list in-place alphabetically. +``APPEND``, ``PREPEND``: Append, prepend specified value to each element of +the list. :: + + list(TRANSFORM ...) + +``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower +characters. :: + + list(TRANSFORM ...) + +``STRIP``: Remove leading and trailing spaces from each element of the +list. :: + + list(TRANSFORM STRIP ...) + +``GENEX_STRIP``: Strip any +:manual:`generator expressions ` from each +element of the list. :: + + list(TRANSFORM GENEX_STRIP ...) + +``REPLACE``: Match the regular expression as many times as possible and +substitute the replacement expression for the match for each element +of the list +(Same semantic as ``REGEX REPLACE`` from :command:`string` command). :: + + list(TRANSFORM REPLACE + ...) + +```` select which elements of the list will be transformed. Only one +type of selector can be specified at a time. + +The ```` may be one of: + +``AT``: Specify a list of indexes. :: + + list(TRANSFORM AT [ ...] ...) + +``FOR``: Specify a range with, optionally, an increment used to iterate over +the range. :: + + list(TRANSFORM FOR [] ...) + +``REGEX``: Specify a regular expression. Only elements matching the regular +expression will be transformed. :: + + list(TRANSFORM REGEX ...) + + +Ordering +^^^^^^^^ + +.. _REVERSE: + +:: + + list(REVERSE ) + +Reverses the contents of the list in-place. + +.. _SORT: + +:: + + list(SORT ) -The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, -``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create new -values for the list within the current CMake variable scope. Similar to the -:command:`set` command, the LIST command creates new variable values in the -current scope, even if the list itself is actually defined in a parent -scope. To propagate the results of these operations upwards, use -:command:`set` with ``PARENT_SCOPE``, :command:`set` with -``CACHE INTERNAL``, or some other means of value propagation. -NOTES: A list in cmake is a ``;`` separated group of strings. To create a -list the set command can be used. For example, ``set(var a b c d e)`` -creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a -string or a list with one item in it. (Note macro arguments are not -variables, and therefore cannot be used in LIST commands.) - -When specifying index values, if ```` is 0 or greater, it -is indexed from the beginning of the list, with 0 representing the -first list element. If ```` is -1 or lesser, it is indexed -from the end of the list, with -1 representing the last list element. -Be careful when counting with negative indices: they do not start from -0. -0 is equivalent to 0, the first list element. +Sorts the list in-place alphabetically. diff --git a/Help/command/project.rst b/Help/command/project.rst index eb185e404..c1de05786 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -1,7 +1,7 @@ project ------- -Set a name, version, and enable languages for the entire project. +Sets project details such as name, version, etc. and enables languages. .. code-block:: cmake @@ -9,6 +9,7 @@ Set a name, version, and enable languages for the entire project. project( [VERSION [.[.[.]]]] [DESCRIPTION ] + [HOMEPAGE_URL ] [LANGUAGES ...]) Sets the name of the project and stores the name in the @@ -41,9 +42,18 @@ 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). +If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION` +and :variable:`_DESCRIPTION` will be set to its argument. +The description is expected to be a relatively short string, usually no more +than a few words. + +The optional ``HOMEPAGE_URL`` sets the analogous variables +:variable:`PROJECT_HOMEPAGE_URL` and :variable:`_HOMEPAGE_URL`. +When this option is given, the URL provided should be the canonical home for +the project. + +Note that the description and homepage URL may be used as defaults for +things like packaging meta-data, documentation, etc. Optionally you can specify which languages your project supports. Example languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, @@ -63,7 +73,12 @@ The top-level ``CMakeLists.txt`` file for a project must contain a literal, direct call to the :command:`project` command; loading one through the :command:`include` command is not sufficient. If no such call exists CMake will implicitly add one to the top that enables the -default languages (``C`` and ``CXX``). +default languages (``C`` and ``CXX``). The name of the project set in +the top level ``CMakeLists.txt`` file is available from the +:variable:`CMAKE_PROJECT_NAME` variable, its description from +:variable:`CMAKE_PROJECT_DESCRIPTION`, its homepage URL from +:variable:`CMAKE_PROJECT_HOMEPAGE_URL` and its version from +:variable:`CMAKE_PROJECT_VERSION`. .. note:: Call the :command:`cmake_minimum_required` command at the beginning diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index 5ed788e4a..c89e1ced3 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -59,11 +59,17 @@ be one of the following: The required ``PROPERTY`` option is immediately followed by the name of the property to set. Remaining arguments are used to compose the -property value in the form of a semicolon-separated list. If the -``APPEND`` option is given the list is appended to any existing property -value. If the ``APPEND_STRING`` option is given the string is append to any -existing property value as string, i.e. it results in a longer string -and not a list of strings. +property value in the form of a semicolon-separated list. + +If the ``APPEND`` option is given the list is appended to any existing +property value. If the ``APPEND_STRING`` option is given the string is +appended to any existing property value as string, i.e. it results in a +longer string and not a list of strings. When using ``APPEND`` or +``APPEND_STRING`` with a property defined to support ``INHERITED`` +behavior (see :command:`define_property`), no inheriting occurs when +finding the initial value to append to. If the property is not already +directly set in the nominated scope, the command will behave as though +``APPEND`` or ``APPEND_STRING`` had not been given. See the :manual:`cmake-properties(7)` manual for a list of properties in each scope. diff --git a/Help/command/set_target_properties.rst b/Help/command/set_target_properties.rst index b894eace3..7db952d6d 100644 --- a/Help/command/set_target_properties.rst +++ b/Help/command/set_target_properties.rst @@ -9,10 +9,12 @@ Targets can have properties that affect how they are built. PROPERTIES prop1 value1 prop2 value2 ...) -Set properties on a target. The syntax for the command is to list all -the files you want to change, and then provide the values you want to +Set properties on targets. The syntax for the command is to list all +the targets you want to change, and then provide the values you want to set next. You can use any prop value pair you want and extract it later with the :command:`get_property` or :command:`get_target_property` command. +See also the :command:`set_property(TARGET)` command. + See :ref:`Target Properties` for the list of properties known to CMake. diff --git a/Help/command/string.rst b/Help/command/string.rst index fb3893f2b..efa923b70 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -1,17 +1,52 @@ string ------ -.. only:: html - - .. contents:: - String operations. +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Search and Replace`_ + string(`FIND`_ [...]) + string(`REPLACE`_ ...) + + `Regular Expressions`_ + string(`REGEX MATCH`_ ...) + string(`REGEX MATCHALL`_ ...) + string(`REGEX REPLACE`_ ...) + + `Manipulation`_ + string(`APPEND`_ [...]) + string(`PREPEND`_ [...]) + string(`CONCAT`_ [...]) + string(`JOIN`_ [...]) + string(`TOLOWER`_ ) + string(`TOUPPER`_ ) + string(`LENGTH`_ ) + string(`SUBSTRING`_ ) + string(`STRIP`_ ) + string(`GENEX_STRIP`_ ) + + `Comparison`_ + string(`COMPARE`_ ) + + `Hashing`_ + string(`\ `_ ) + + `Generation`_ + string(`ASCII`_ ... ) + string(`CONFIGURE`_ [...]) + string(`MAKE_C_IDENTIFIER`_ ) + string(`RANDOM`_ [