diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/FIND_XXX_ROOT.txt | 11 | ||||
| -rw-r--r-- | Help/command/build_command.rst | 45 | ||||
| -rw-r--r-- | Help/command/ctest_submit.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 3 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 6 | ||||
| -rw-r--r-- | Help/policy/CMP0037.rst | 17 | ||||
| -rw-r--r-- | Help/variable/CMAKE_BUILD_TOOL.rst | 11 | ||||
| -rw-r--r-- | Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst | 13 | ||||
| -rw-r--r-- | Help/variable/CMAKE_LANG_COMPILER_TARGET.rst | 11 | ||||
| -rw-r--r-- | Help/variable/CMAKE_MAKE_PROGRAM.rst | 50 | ||||
| -rw-r--r-- | Help/variable/CMAKE_SYSROOT.rst | 12 |
11 files changed, 139 insertions, 41 deletions
diff --git a/Help/command/FIND_XXX_ROOT.txt b/Help/command/FIND_XXX_ROOT.txt index 407375a..7f80dcb 100644 --- a/Help/command/FIND_XXX_ROOT.txt +++ b/Help/command/FIND_XXX_ROOT.txt @@ -1,10 +1,17 @@ The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directories to be prepended to all other search directories. This effectively "re-roots" the entire search under given locations. By -default it is empty. It is especially useful when cross-compiling to +default it is empty. + +The :variable:`CMAKE_SYSROOT` variable can also be used to specify exactly one +directory to use as a prefix. Setting :variable:`CMAKE_SYSROOT` also has other +effects. See the documentation for that variable for more. + +These variables are especially useful when cross-compiling to point to the root directory of the target environment and CMake will search there too. By default at first the directories listed in -CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be +CMAKE_FIND_ROOT_PATH are searched, then the :variable:`CMAKE_SYSROOT` directory is +searched, and then the non-rooted directories will be searched. The default behavior can be adjusted by setting |CMAKE_FIND_ROOT_PATH_MODE_XXX|. This behavior can be manually overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index f4a56f0..82a9a42 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -1,37 +1,44 @@ build_command ------------- -Get the command line to build this project. +Get a command line to build the current project. +This is mainly intended for internal use by the :module:`CTest` module. -:: +.. code-block:: cmake build_command(<variable> [CONFIGURATION <config>] - [PROJECT_NAME <projname>] - [TARGET <target>]) + [TARGET <target>] + [PROJECT_NAME <projname>] # legacy, causes warning + ) -Sets the given <variable> to a string containing the command line for -building one configuration of a target in a project using the build -tool appropriate for the current CMAKE_GENERATOR. +Sets the given ``<variable>`` to a command-line string of the form:: -If CONFIGURATION is omitted, CMake chooses a reasonable default value -for multi-configuration generators. CONFIGURATION is ignored for -single-configuration generators. + <cmake> --build . [--config <config>] [--target <target>] [-- -i] -If PROJECT_NAME is omitted, the resulting command line will build the -top level PROJECT in the current build tree. +where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line +tool, and ``<config>`` and ``<target>`` are the values provided to the +``CONFIGURATION`` and ``TARGET`` options, if any. The trailing ``-- -i`` +option is added for Makefile generators. -If TARGET is omitted, the resulting command line will build -everything, effectively using build target 'all' or 'ALL_BUILD'. +When invoked, this ``cmake --build`` command line will launch the +underlying build system tool. -:: +.. code-block:: cmake build_command(<cachevariable> <makecommand>) This second signature is deprecated, but still available for backwards compatibility. Use the first signature instead. -Sets the given <cachevariable> to a string containing the command to -build this project from the root of the build tree using the build -tool given by <makecommand>. <makecommand> should be the full path to -msdev, devenv, nmake, make or one of the end user build tools. +It sets the given ``<cachevariable>`` to a command-line string as +above but without the ``--config`` or ``--target`` options. +The ``<makecommand>`` is ignored but should be the full path to +msdev, devenv, nmake, make or one of the end user build tools +for legacy invocations. + +.. note:: + In CMake versions prior to 3.0 this command returned a command + line that directly invokes the native build tool for the current + generator. Their implementation of the ``PROJECT_NAME`` option + had no useful effects, so CMake now warns on use of the option. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index 29d2f5d..ed801bb 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -22,6 +22,7 @@ Valid part names are: MemCheck = ctest_memcheck results, in DynamicAnalysis.xml Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES + Upload = Files prepared for upload by ctest_upload(), in Upload.xml Submit = nothing The FILES option explicitly lists specific files to be submitted. diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 59e8064..dd82b40 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -91,6 +91,7 @@ Variables that Change Behavior /variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName /variable/CMAKE_ERROR_DEPRECATED /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_SYSROOT /variable/CMAKE_FIND_LIBRARY_PREFIXES /variable/CMAKE_FIND_LIBRARY_SUFFIXES /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE @@ -234,6 +235,8 @@ Variables for Languages /variable/CMAKE_LANG_COMPILER_ID /variable/CMAKE_LANG_COMPILER_LOADED /variable/CMAKE_LANG_COMPILER + /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN + /variable/CMAKE_LANG_COMPILER_TARGET /variable/CMAKE_LANG_COMPILER_VERSION /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index eee12fd..60d08dd 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -225,8 +225,8 @@ Options and or execute a test. The configure and test steps are optional. The arguments to this command line are the source and binary directories. By default this will run CMake on the Source/Bin - directories specified unless --build-nocmake is specified. Both - --build-makeprogram and --build-generator MUST be provided to use + directories specified unless --build-nocmake is specified. + The --build-generator option *must* be provided to use --build-and-test. If --test-command is specified then that will be run after the build is complete. Other options that affect this mode are --build-target --build-nocmake, --build-run-dir, @@ -265,7 +265,7 @@ Options Specify the name of the project to build. ``--build-makeprogram`` - Specify the make program to use. + Override the make program chosen by CTest with a given one. ``--build-noclean`` Skip the make clean step. diff --git a/Help/policy/CMP0037.rst b/Help/policy/CMP0037.rst index 5df3c00..059b2e6 100644 --- a/Help/policy/CMP0037.rst +++ b/Help/policy/CMP0037.rst @@ -1,19 +1,24 @@ CMP0037 ------- -Target names should match a validity pattern. +Target names should not be reserved and should match a validity pattern. -CMake 2.8.12 and lower allowed creating targets using :command:`add_library` and -:command:`add_executable` with unrestricted choice for the target name. Newer -cmake features such as :manual:`cmake-generator-expressions(7)` and some +CMake 2.8.12 and lower allowed creating targets using :command:`add_library`, +:command:`add_executable` and :command:`add_custom_target` with unrestricted +choice for the target name. Newer cmake features such +as :manual:`cmake-generator-expressions(7)` and some diagnostics expect target names to match a restricted pattern. Target names may contain upper and lower case letters, numbers, the underscore character (_), dot(.), plus(+) and minus(-). As a special case, ALIAS targets and INTERFACE library targets may contain two consequtive colons. -The OLD behavior for this policy is to allow creating targets which do not match -the validity pattern. The NEW behavior for this policy is to report an error +Target names reserved by one or more CMake generators are not allowed. +Among others these include "all", "help" and "test". + +The OLD behavior for this policy is to allow creating targets with +reserved names or which do not match the validity pattern. +The NEW behavior for this policy is to report an error if an add_* command is used with an invalid target name. This policy was introduced in CMake version 3.0.0. CMake version diff --git a/Help/variable/CMAKE_BUILD_TOOL.rst b/Help/variable/CMAKE_BUILD_TOOL.rst index f0bc938..6133491 100644 --- a/Help/variable/CMAKE_BUILD_TOOL.rst +++ b/Help/variable/CMAKE_BUILD_TOOL.rst @@ -1,11 +1,6 @@ CMAKE_BUILD_TOOL ---------------- -Tool used for the actual build process. - -This variable is set to the program that will be needed to build the -output of CMake. If the generator selected was Visual Studio 6, the -CMAKE_BUILD_TOOL will be set to msdev, for Unix Makefiles it will be -set to make or gmake, and for Visual Studio 7 it set to devenv. For -NMake Makefiles the value is nmake. This can be useful for adding -special flags and commands based on the final build environment. +This variable exists only for backwards compatibility. +It contains the same value as :variable:`CMAKE_MAKE_PROGRAM`. +Use that variable instead. diff --git a/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst new file mode 100644 index 0000000..86c0b0e --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN +---------------------------------------- + +The external toolchain for cross-compiling, if supported. + +Some compiler toolchains do not ship their own auxilliary utilities such as +archivers and linkers. The compiler driver may support a command-line argument +to specify the location of such tools. CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN +may be set to a path to a path to the external toolchain and will be passed +to the compiler driver if supported. + +This variable may only be set in a toolchain file specified by +the ``CMAKE_TOOLCHAIN_FILE`` variable. diff --git a/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst b/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst new file mode 100644 index 0000000..7c8efee --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_COMPILER_TARGET +---------------------------- + +The target for cross-compiling, if supported. + +Some compiler drivers are inherently cross-compilers, such as clang and +QNX qcc. These compiler drivers support a command-line argument to specify +the target to cross-compile for. + +This variable may only be set in a toolchain file specified by +the ``CMAKE_TOOLCHAIN_FILE`` variable. diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst index 8307bc6..0c851ad 100644 --- a/Help/variable/CMAKE_MAKE_PROGRAM.rst +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -1,7 +1,51 @@ CMAKE_MAKE_PROGRAM ------------------ -See CMAKE_BUILD_TOOL. +Tool that can launch the native build system. +The value may be the full path to an executable or just the tool +name if it is expected to be in the ``PATH``. -This variable is around for backwards compatibility, see -CMAKE_BUILD_TOOL. +The tool selected depends on the :variable:`CMAKE_GENERATOR` used +to configure the project: + +* The Makefile generators set this to ``make``, ``gmake``, or + a generator-specific tool (e.g. ``nmake`` for "NMake Makefiles"). + + These generators store ``CMAKE_MAKE_PROGRAM`` in the CMake cache + so that it may be edited by the user. + +* The Ninja generator sets this to ``ninja``. + + This generator stores ``CMAKE_MAKE_PROGRAM`` in the CMake cache + so that it may be edited by the user. + +* The Xcode generator sets this to ``xcodebuild`` (or possibly an + otherwise undocumented ``cmakexbuild`` wrapper implementing some + workarounds). + + This generator stores ``CMAKE_MAKE_PROGRAM`` in the CMake cache + so that it may be edited by the user. + +* The Visual Studio generators set this to the full path to + ``MSBuild.exe`` (VS >= 10), ``devenv.com`` (VS 7,8,9), + ``VCExpress.exe`` (VS Express 8,9), or ``msdev.exe`` (VS 6). + + These generators prefer to lookup the build tool at build time + rather than to store ``CMAKE_MAKE_PROGRAM`` in the CMake cache + ahead of time. This is because the tools are version-specific + and can be located using the Windows Registry. It is also + necessary because the proper build tool may depend on the + project content (e.g. the Intel Fortran plugin to VS 10 and 11 + requires ``devenv.com`` to build its ``.vfproj`` project files + even though ``MSBuild.exe`` is normally preferred to support + the :variable:`CMAKE_GENERATOR_TOOLSET`). + + For compatibility with versions of CMake prior to 3.0, if + a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to + the CMake cache then CMake will use the specified value if + possible. + +The ``CMAKE_MAKE_PROGRAM`` variable is set for use by project code. +The value is also used by the :manual:`cmake(1)` ``--build`` and +:manual:`ctest(1)` ``--build-and-test`` tools to launch the native +build process. diff --git a/Help/variable/CMAKE_SYSROOT.rst b/Help/variable/CMAKE_SYSROOT.rst new file mode 100644 index 0000000..e42e63a --- /dev/null +++ b/Help/variable/CMAKE_SYSROOT.rst @@ -0,0 +1,12 @@ +CMAKE_SYSROOT +------------- + +Path to pass to the compiler in the ``--sysroot`` flag. + +The ``CMAKE_SYSROOT`` content is passed to the compiler in the ``--sysroot`` +flag, if supported. The path is also stripped from the RPATH/RUNPATH if +necessary on installation. The ``CMAKE_SYSROOT`` is also used to prefix +paths searched by the ``find_*`` commands. + +This variable may only be set in a toolchain file specified by +the ``CMAKE_TOOLCHAIN_FILE`` variable. |