From b6cfbe7b170868eb646b143769840d64aa7b0c3b Mon Sep 17 00:00:00 2001 From: scivision Date: Mon, 27 Feb 2023 23:36:22 -0500 Subject: Help:try_{compile,run}: clarify, encourage new syntax --- Help/command/try_compile.rst | 39 +++++++++++++++++++-------------------- 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( PROJECT + try_compile( PROJECT SOURCE_DIR [BINARY_DIR ] [TARGET ] @@ -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 ````. +Try building a project. Build success returns ``TRUE`` and build failure +returns ``FALSE`` in ````. In this form, ```` should contain a complete CMake project with a ``CMakeLists.txt`` file and all sources. The ```` and ```` @@ -47,16 +47,13 @@ below for the meaning of other options. :ref:`configure-log try_compile 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( + try_compile( [] - [LOG_DESCRIPTION ] - [NO_CACHE] - [NO_LOG] [CMAKE_FLAGS ...] [OUTPUT_VARIABLE ]) @@ -67,7 +64,7 @@ Try Compiling Source Files .. code-block:: cmake - try_compile( + try_compile( | SOURCE_FROM_CONTENT | SOURCE_FROM_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 ````. +variable). Build success returns ``TRUE`` and build failure returns ``FALSE`` +in ````. 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( - [LOG_DESCRIPTION ] - [NO_CACHE] - [NO_LOG] + try_compile( [CMAKE_FLAGS ...] [COMPILE_DEFINITIONS ...] [LINK_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 ] [RUN_OUTPUT_STDOUT_VARIABLE ] [RUN_OUTPUT_STDERR_VARIABLE ] - [OUTPUT_VARIABLE ] [WORKING_DIRECTORY ] [ARGS ...] ) .. versionadded:: 3.25 -Try compiling a ````. Returns ``TRUE`` or ``FALSE`` for success -or failure in ````. If the compile succeeded, runs the -executable and returns its exit code in ````. If the -executable was built, but failed to run, then ```` 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 ````. +If the build succeeds, this runs the executable and stores the exit code in +````. If the executable was built, but failed to run, then +```` 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 ` 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( - [LOG_DESCRIPTION ] - [NO_CACHE] - [NO_LOG] [CMAKE_FLAGS ...] [COMPILE_DEFINITIONS ...] [LINK_OPTIONS ...] @@ -75,8 +72,6 @@ which was present in older versions of CMake: [_STANDARD_REQUIRED ] [_EXTENSIONS ] [RUN_OUTPUT_VARIABLE ] - [RUN_OUTPUT_STDOUT_VARIABLE ] - [RUN_OUTPUT_STDERR_VARIABLE ] [OUTPUT_VARIABLE ] [WORKING_DIRECTORY ] [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 -- cgit v0.12