diff options
| -rw-r--r-- | Help/command/try_compile.rst | 39 | ||||
| -rw-r--r-- | Help/command/try_run.rst | 37 |
2 files changed, 37 insertions, 39 deletions
diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 21b063f..8abb6e0 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -14,7 +14,7 @@ Try Compiling Whole Projects .. code-block:: cmake - try_compile(<resultVar> PROJECT <projectName> + try_compile(<compileResultVar> PROJECT <projectName> SOURCE_DIR <srcdir> [BINARY_DIR <bindir>] [TARGET <targetName>] @@ -26,8 +26,8 @@ Try Compiling Whole Projects .. versionadded:: 3.25 -Try building a project. The success or failure of the ``try_compile``, -i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``. +Try building a project. Build success returns ``TRUE`` and build failure +returns ``FALSE`` in ``<compileResultVar>``. In this form, ``<srcdir>`` should contain a complete CMake project with a ``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>`` @@ -47,16 +47,13 @@ below for the meaning of other options. :ref:`configure-log try_compile event <try_compile configure-log event>` if the ``NO_LOG`` option is not specified. -This command also supports an alternate signature -which was present in older versions of CMake: +This command supports an alternate signature for CMake older than 3.25. +The signature above is recommended for clarity. .. code-block:: cmake - try_compile(<resultVar> <bindir> <srcdir> + try_compile(<compileResultVar> <bindir> <srcdir> <projectName> [<targetName>] - [LOG_DESCRIPTION <text>] - [NO_CACHE] - [NO_LOG] [CMAKE_FLAGS <flags>...] [OUTPUT_VARIABLE <var>]) @@ -67,7 +64,7 @@ Try Compiling Source Files .. code-block:: cmake - try_compile(<resultVar> + try_compile(<compileResultVar> <SOURCES <srcfile...> | SOURCE_FROM_CONTENT <name> <content> | SOURCE_FROM_VAR <name> <var> | @@ -90,8 +87,8 @@ Try Compiling Source Files Try building an executable or static library from one or more source files (which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` -variable). The success or failure of the ``try_compile``, i.e. ``TRUE`` or -``FALSE`` respectively, is returned in ``<resultVar>``. +variable). Build success returns ``TRUE`` and build failure returns ``FALSE`` +in ``<compileResultVar>``. In this form, one or more source files must be provided. Additionally, one of ``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords. @@ -120,15 +117,12 @@ with an unspecified name. These directories are cleaned automatically unless Such directories from previous runs are also unconditionally cleaned at the beginning of any :program:`cmake` execution. -This command also supports an alternate signature -which was present in older versions of CMake: +This command supports an alternate signature for CMake older than 3.25. +The signature above is recommended for clarity. .. code-block:: cmake - try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...> - [LOG_DESCRIPTION <text>] - [NO_CACHE] - [NO_LOG] + try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...> [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] @@ -300,8 +294,13 @@ Other Behavior Settings The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated through to the generated test project. -Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose -a build configuration. +Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build +configuration: + +* For multi-config generators, this selects which configuration to build. + +* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in + the test project. .. versionadded:: 3.6 Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index 7566264..3a4e203 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -32,20 +32,20 @@ Try Compiling and Running Source Files [RUN_OUTPUT_VARIABLE <var>] [RUN_OUTPUT_STDOUT_VARIABLE <var>] [RUN_OUTPUT_STDERR_VARIABLE <var>] - [OUTPUT_VARIABLE <var>] [WORKING_DIRECTORY <var>] [ARGS <args>...] ) .. versionadded:: 3.25 -Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success -or failure in ``<compileResultVar>``. If the compile succeeded, runs the -executable and returns its exit code in ``<runResultVar>``. If the -executable was built, but failed to run, then ``<runResultVar>`` will be -set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for -documentation of options common to both commands, and for information on how -the test project is constructed to build the source file. +Try building an executable from one or more source files. Build success +returns ``TRUE`` and build failure returns ``FALSE`` in ``<compileResultVar>``. +If the build succeeds, this runs the executable and stores the exit code in +``<runResultVar>``. If the executable was built, but failed to run, then +``<runResultVar>`` will be set to ``FAILED_TO_RUN``. See command +:command:`try_compile` for documentation of options common to both commands, +and for information on how the test project is constructed to build the source +file. One or more source files must be provided. Additionally, one of ``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords. @@ -55,16 +55,13 @@ and/or ``SOURCE_FROM_*`` must precede other keywords. :ref:`configure-log try_run event <try_run configure-log event>` if the ``NO_LOG`` option is not specified. -This command also supports an alternate signature -which was present in older versions of CMake: +This command supports an alternate signature for CMake older than 3.25. +The signature above is recommended for clarity. .. code-block:: cmake try_run(<runResultVar> <compileResultVar> <bindir> <srcfile|SOURCES srcfile...> - [LOG_DESCRIPTION <text>] - [NO_CACHE] - [NO_LOG] [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] @@ -75,8 +72,6 @@ which was present in older versions of CMake: [<LANG>_STANDARD_REQUIRED <bool>] [<LANG>_EXTENSIONS <bool>] [RUN_OUTPUT_VARIABLE <var>] - [RUN_OUTPUT_STDOUT_VARIABLE <var>] - [RUN_OUTPUT_STDERR_VARIABLE <var>] [OUTPUT_VARIABLE <var>] [WORKING_DIRECTORY <var>] [ARGS <args>...] @@ -119,15 +114,19 @@ The options specific to ``try_run`` are: Other Behavior Settings ^^^^^^^^^^^^^^^^^^^^^^^ -Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose -a build configuration. +Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build +configuration: + +* For multi-config generators, this selects which configuration to build. + +* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in + the test project. Behavior when Cross Compiling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. versionadded:: 3.3 - Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled - binaries. + Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled binaries. When cross compiling, the executable compiled in the first step usually cannot be run on the build host. The ``try_run`` command checks |