diff options
Diffstat (limited to 'Help')
22 files changed, 180 insertions, 39 deletions
diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst index c088796..6763620 100644 --- a/Help/command/add_executable.rst +++ b/Help/command/add_executable.rst @@ -7,14 +7,15 @@ Add an executable to the project using the specified source files. add_executable(<name> [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] - source1 [source2 ...]) + [source1] [source2 ...]) Adds an executable target called ``<name>`` to be built from the source -files listed in the command invocation. The ``<name>`` corresponds to the -logical target name and must be globally unique within a project. The -actual file name of the executable built is constructed based on -conventions of the native platform (such as ``<name>.exe`` or just -``<name>``). +files listed in the command invocation. (The source files can be omitted +here if they are added later using :command:`target_sources`.) The +``<name>`` corresponds to the logical target name and must be globally +unique within a project. The actual file name of the executable built is +constructed based on conventions of the native platform (such as +``<name>.exe`` or just ``<name>``). By default the executable file will be created in the build tree directory corresponding to the source tree directory in which the diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index de5335e..78b316d 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -14,13 +14,14 @@ Normal Libraries add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] - source1 [source2 ...]) + [source1] [source2 ...]) Adds a library target called ``<name>`` to be built from the source files -listed in the command invocation. The ``<name>`` corresponds to the -logical target name and must be globally unique within a project. The -actual file name of the library built is constructed based on -conventions of the native platform (such as ``lib<name>.a`` or +listed in the command invocation. (The source files can be omitted here +if they are added later using :command:`target_sources`.) The ``<name>`` +corresponds to the logical target name and must be globally unique within +a project. The actual file name of the library built is constructed based +on conventions of the native platform (such as ``lib<name>.a`` or ``<name>.lib``). ``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index ec4ffed..b334a89 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -43,15 +43,18 @@ macro which can be followed by more than one value, like e.g. the ``<multi_value_keywords>``. A warning will be emitted if uniqueness is violated. -When done, ``cmake_parse_arguments`` will have defined for each of the +When done, ``cmake_parse_arguments`` will consider for each of the keywords listed in ``<options>``, ``<one_value_keywords>`` and ``<multi_value_keywords>`` a variable composed of the given ``<prefix>`` followed by ``"_"`` and the name of the respective keyword. These -variables will then hold the respective value from the argument list. -For the ``<options>`` keywords this will be ``TRUE`` or ``FALSE``. +variables will then hold the respective value from the argument list +or be undefined if the associated option could not be found. +For the ``<options>`` keywords, these will always be defined, +to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not. All remaining arguments are collected in a variable -``<prefix>_UNPARSED_ARGUMENTS``, this can be checked afterwards to see +``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all argument +where recognized. This can be checked afterwards to see whether your macro was called with unrecognized parameters. As an example here a ``my_install()`` macro, which takes similar arguments @@ -74,16 +77,16 @@ Assume ``my_install()`` has been called like this: my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub) -After the ``cmake_parse_arguments`` call the macro will have set the -following variables:: +After the ``cmake_parse_arguments`` call the macro will have set or undefined +the following variables:: MY_INSTALL_OPTIONAL = TRUE - MY_INSTALL_FAST = FALSE (was not used in call to my_install) + MY_INSTALL_FAST = FALSE # was not used in call to my_install MY_INSTALL_DESTINATION = "bin" - MY_INSTALL_RENAME = "" (was not used) + MY_INSTALL_RENAME <UNDEFINED> # was not used MY_INSTALL_TARGETS = "foo;bar" - MY_INSTALL_CONFIGURATIONS = "" (was not used) - MY_INSTALL_UNPARSED_ARGUMENTS = "blub" (nothing expected after "OPTIONAL") + MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used + MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL" You can then continue and process these variables. diff --git a/Help/command/file.rst b/Help/command/file.rst index edccac5..4d4ebb4 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -232,6 +232,31 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: ``HTTPHEADER <HTTP-header>`` HTTP header for operation. Suboption can be repeated several times. +``NETRC <level>`` + Specify whether the .netrc file is to be used for operation. If this + option is not specified, the value of the ``CMAKE_NETRC`` variable + will be used instead. + Valid levels are: + + ``IGNORED`` + The .netrc file is ignored. + This is the default. + ``OPTIONAL`` + The .netrc file is optional, and information in the URL is preferred. + The file will be scanned to find which ever information is not specified + in the URL. + ``REQUIRED`` + The .netrc file is required, and information in the URL is ignored. + +``NETRC_FILE <file>`` + Specify an alternative .netrc file to the one in your home directory, + if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option + is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will + be used instead. + +If neither ``NETRC`` option is given CMake will check variables +``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively. + Additional options to ``DOWNLOAD`` are: ``EXPECTED_HASH ALGO=<value>`` diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index 2ac0449..2cf1aa0 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -19,13 +19,17 @@ 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. +The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a +cache entry containing the absolute path to a Visual Studio instance. +If the value is not specified explicitly by the user or a toolchain file, +CMake queries the Visual Studio Installer to locate VS instances, chooses +one, and sets the variable as a cache entry to hold the value persistently. + +When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment +variable is set and points to the ``Common7/Tools`` directory within +one of the instances, that instance will be used. Otherwise, if more +than one instance is installed we do not define which one is chosen +by default. Toolset Selection ^^^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index debaf23..ae538ed 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -687,7 +687,8 @@ property are treated as ``SYSTEM`` include directories, as if they were listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the dependency. This can result in omission of compiler warnings for headers found in those directories. This behavior for :ref:`imported targets` may -be controlled with the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property. +be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target +property on the *consumers* of imported targets. If a binary target is linked transitively to a Mac OX framework, the ``Headers`` directory of the framework is also treated as a usage requirement. @@ -970,7 +971,6 @@ are: * ``EXPORT_NAME`` * ``IMPORTED`` * ``NAME`` -* ``NO_SYSTEM_FROM_IMPORTED`` * Properties matching ``IMPORTED_LIBNAME_*`` * Properties matching ``MAP_IMPORTED_CONFIG_*`` diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 8f4b252..9fd92ec 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -80,6 +80,7 @@ All Modules /module/ExternalData /module/ExternalProject /module/FeatureSummary + /module/FetchContent /module/FindALSA /module/FindArmadillo /module/FindASPELL diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 2e369e3..b37d473 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -42,6 +42,7 @@ Variables that Provide Information /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION /variable/CMAKE_FIND_PACKAGE_SORT_ORDER /variable/CMAKE_GENERATOR + /variable/CMAKE_GENERATOR_INSTANCE /variable/CMAKE_GENERATOR_PLATFORM /variable/CMAKE_GENERATOR_TOOLSET /variable/CMAKE_HOME_DIRECTORY @@ -60,6 +61,8 @@ Variables that Provide Information /variable/CMAKE_MATCH_n /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION + /variable/CMAKE_NETRC + /variable/CMAKE_NETRC_FILE /variable/CMAKE_PARENT_LIST_FILE /variable/CMAKE_PATCH_VERSION /variable/CMAKE_PROJECT_DESCRIPTION diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 6a21683..ff8c6c7 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -11,6 +11,7 @@ Synopsis cmake [<options>] (<path-to-source> | <path-to-existing-build>) cmake [(-D <var>=<value>)...] -P <cmake-script-file> cmake --build <dir> [<options>...] [-- <build-tool-options>...] + cmake --open <dir> cmake -E <command> [<options>...] cmake --find-package <options>... @@ -51,6 +52,10 @@ Options ``--build <dir>`` See `Build Tool Mode`_. +``--open <dir>`` + Open the generated project in the associated application. This is + only supported by some generators. + ``-N`` View mode only. diff --git a/Help/module/FetchContent.rst b/Help/module/FetchContent.rst new file mode 100644 index 0000000..c130a6d --- /dev/null +++ b/Help/module/FetchContent.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FetchContent.cmake diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index 30a612d..0762033 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -6,7 +6,8 @@ The C++ standard whose features are requested to build this target. This property specifies the C++ standard whose features are requested to build this target. For some compilers, this results in adding a flag such as ``-std=gnu++11`` to the compile line. For compilers that -have no notion of a standard level, such as MSVC, this has no effect. +have no notion of a standard level, such as Microsoft Visual C++ before +2015 Update 3, this has no effect. Supported values are ``98``, ``11``, ``14``, and ``17``. diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst index 815a686..e7f7904 100644 --- a/Help/prop_tgt/C_STANDARD.rst +++ b/Help/prop_tgt/C_STANDARD.rst @@ -6,7 +6,8 @@ The C standard whose features are requested to build this target. This property specifies the C standard whose features are requested to build this target. For some compilers, this results in adding a flag such as ``-std=gnu11`` to the compile line. For compilers that -have no notion of a standard level, such as MSVC, this has no effect. +have no notion of a standard level, such as Microsoft Visual C++ before +2015 Update 3, this has no effect. Supported values are ``90``, ``99`` and ``11``. diff --git a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst index 070dd30..880343d 100644 --- a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst +++ b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst @@ -1,11 +1,15 @@ NO_SYSTEM_FROM_IMPORTED ----------------------- -Do not treat includes from IMPORTED target interfaces as SYSTEM. +Do not treat include directories from the interfaces of consumed +:ref:`imported targets` as ``SYSTEM``. -The contents of the INTERFACE_INCLUDE_DIRECTORIES of IMPORTED targets -are treated as SYSTEM includes by default. If this property is -enabled, the contents of the INTERFACE_INCLUDE_DIRECTORIES of IMPORTED -targets are not treated as system includes. This property is -initialized by the value of the variable CMAKE_NO_SYSTEM_FROM_IMPORTED -if it is set when a target is created. +The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property +of imported targets are treated as ``SYSTEM`` includes by default. If this +property is enabled on a target, compilation of sources in that target will +not treat the contents of the ``INTERFACE_INCLUDE_DIRECTORIES`` of consumed +imported targets as system includes. + +This property is initialized by the value of the +:variable:`CMAKE_NO_SYSTEM_FROM_IMPORTED` variable if it is set when a target +is created. diff --git a/Help/release/dev/FetchContent.rst b/Help/release/dev/FetchContent.rst new file mode 100644 index 0000000..3b12977 --- /dev/null +++ b/Help/release/dev/FetchContent.rst @@ -0,0 +1,11 @@ +FetchContent +------------ + +* A new :module:`FetchContent` module was added which supports populating + content at configure time using any of the download/update methods + supported by :command:`ExternalProject_Add`. This allows the content + to be used immediately during the configure stage, such as with + :command:`add_subdirectory`, etc. Hierarchical project structures are + well supported, allowing parent projects to override the content details + of child projects and ensuring content is not populated multiple times + throughout the whole project tree. diff --git a/Help/release/dev/cmake-open.rst b/Help/release/dev/cmake-open.rst new file mode 100644 index 0000000..a8f77ae --- /dev/null +++ b/Help/release/dev/cmake-open.rst @@ -0,0 +1,6 @@ +cmake-open +---------- + +* The :manual:`cmake(1)` ``--open <dir>`` command line option can now + be used to open generated IDE projects like Visual Studio solutions + or Xcode projects. diff --git a/Help/release/dev/curl_netrc_options.rst b/Help/release/dev/curl_netrc_options.rst new file mode 100644 index 0000000..850c9ce --- /dev/null +++ b/Help/release/dev/curl_netrc_options.rst @@ -0,0 +1,14 @@ +curl_netrc_options +------------------ + +* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands + gained ``NETRC`` and ``NETRC_FILE`` options to specify use of a + ``.netrc`` file. + +* The :module:`ExternalProject` module gained ``NETRC`` and ``NETRC_FILE`` + options to specify use of a ``.netrc`` file. + +* The :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables + were added to specify use of a ``.netrc`` file by the + :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and + the :module:`ExternalProject` module. diff --git a/Help/release/dev/defer-target-source-check.rst b/Help/release/dev/defer-target-source-check.rst new file mode 100644 index 0000000..65f5488 --- /dev/null +++ b/Help/release/dev/defer-target-source-check.rst @@ -0,0 +1,6 @@ +defer-target-source-check +------------------------- + +* :command:`add_library` and :command:`add_executable` commands can now be + called without any sources and will not complain as long as sources will + be added later via :command:`target_sources`. diff --git a/Help/release/dev/generator-instance.rst b/Help/release/dev/generator-instance.rst new file mode 100644 index 0000000..a3ff658 --- /dev/null +++ b/Help/release/dev/generator-instance.rst @@ -0,0 +1,8 @@ +generator-instance +------------------ + +* A :variable:`CMAKE_GENERATOR_INSTANCE` variable was introduced + to hold the selected instance of the generator's corresponding + native tools if multiple are available. This is used by the + :generator:`Visual Studio 15 2017` generator to hold the + selected instance of Visual Studio persistently. diff --git a/Help/release/dev/ti-compiler-depfile-support.rst b/Help/release/dev/ti-compiler-depfile-support.rst new file mode 100644 index 0000000..f870afd --- /dev/null +++ b/Help/release/dev/ti-compiler-depfile-support.rst @@ -0,0 +1,4 @@ +ti-compiler-depfile-support +--------------------------- + +* TI C/C++ compilers are now supported by the :generator:`Ninja` generator. diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst new file mode 100644 index 0000000..78c81b1 --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst @@ -0,0 +1,24 @@ +CMAKE_GENERATOR_INSTANCE +------------------------ + +Generator-specific instance specification provided by user. + +Some CMake generators support selection of an instance of the native build +system when multiple instances are available. If the user specifies an +instance (e.g. by setting this cache entry), or after a default instance is +chosen when a build tree is first configured, 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_INSTANCE`` as a cache entry. +Once a given build tree has been initialized with a particular value +for this variable, changing the value has undefined behavior. + +Instance specification is supported only on specific generators: + +* For the :generator:`Visual Studio 15 2017` generator (and above) + this specifies the absolute path to the VS installation directory + of the selected VS instance. + +See native build system documentation for allowed instance values. diff --git a/Help/variable/CMAKE_NETRC.rst b/Help/variable/CMAKE_NETRC.rst new file mode 100644 index 0000000..52f857e --- /dev/null +++ b/Help/variable/CMAKE_NETRC.rst @@ -0,0 +1,9 @@ +CMAKE_NETRC +----------- + +This variable is used to initialize the ``NETRC`` option for +:command:`file(DOWNLOAD)` and :command:`file(DOWNLOAD)` commands and the +module :module:`ExternalProject`. See those commands for additional +information. + +The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_NETRC_FILE.rst b/Help/variable/CMAKE_NETRC_FILE.rst new file mode 100644 index 0000000..1508f1e --- /dev/null +++ b/Help/variable/CMAKE_NETRC_FILE.rst @@ -0,0 +1,9 @@ +CMAKE_NETRC_FILE +---------------- + +This variable is used to initialize the ``NETRC_FILE`` option for +:command:`file(DOWNLOAD)` and :command:`file(DOWNLOAD)` commands and the +module :module:`ExternalProject`. See those commands for additional +information. + +The local option takes precedence over this variable. |