From 7975edeac5885634af347e6774e7928277d6bc17 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sun, 24 Feb 2019 17:13:45 +1100 Subject: Help: User-provided variable names for try_* commands All uppercase is typically used for command keywords. Non-keyword arguments should generally be shown as `` according to the CMake documentation guide. --- Help/command/try_compile.rst | 10 +++++----- Help/command/try_run.rst | 14 +++++++------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 77f42a1..032e8ed 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -12,12 +12,12 @@ Try Compiling Whole Projects .. code-block:: cmake - try_compile(RESULT_VAR + try_compile( [] [CMAKE_FLAGS ...] [OUTPUT_VARIABLE ]) Try building a project. The success or failure of the ``try_compile``, -i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``RESULT_VAR``. +i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ````. In this form, ```` should contain a complete CMake project with a ``CMakeLists.txt`` file and all sources. The ```` and ```` @@ -30,7 +30,7 @@ Try Compiling Source Files .. code-block:: cmake - try_compile(RESULT_VAR + try_compile( [CMAKE_FLAGS ...] [COMPILE_DEFINITIONS ...] [LINK_OPTIONS ...] @@ -44,7 +44,7 @@ Try Compiling Source Files Try building an executable from one or more source files. The success or failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is -returned in ``RESULT_VAR``. +returned in ````. In this form the user need only supply one or more source files that include a definition for ``main``. CMake will create a ``CMakeLists.txt`` file to build @@ -114,7 +114,7 @@ passed to ``cmake`` to avoid this clean. However, multiple sequential ``try_compile`` operations reuse this single output directory. If you use ``--debug-trycompile``, you can only debug one ``try_compile`` call at a time. The recommended procedure is to protect all ``try_compile`` calls in your -project by ``if(NOT DEFINED RESULT_VAR)`` logic, configure with cmake +project by ``if(NOT DEFINED )`` logic, configure with cmake all the way through once, then delete the cache entry associated with the try_compile call of interest, and then re-run cmake again with ``--debug-trycompile``. diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index 137402f..d401ebe 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -12,8 +12,8 @@ Try Compiling and Running Source Files .. code-block:: cmake - try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR - bindir srcfile [CMAKE_FLAGS ...] + try_run( + [CMAKE_FLAGS ...] [COMPILE_DEFINITIONS ...] [LINK_OPTIONS ...] [LINK_LIBRARIES ...] @@ -23,9 +23,9 @@ Try Compiling and Running Source Files [ARGS ...]) Try compiling a ````. Returns ``TRUE`` or ``FALSE`` for success -or failure in ``COMPILE_RESULT_VAR``. If the compile succeeded, runs the -executable and returns its exit code in ``RUN_RESULT_VAR``. If the -executable was built, but failed to run, then ``RUN_RESULT_VAR`` will be +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 information on how the test project is constructed to build the source file. @@ -85,10 +85,10 @@ presetting them in some CMake script file to the values the executable would have produced if it had been run on its actual target platform. These cache entries are: -```` +```` Exit code if the executable were to be run on the target platform. -``__TRYRUN_OUTPUT`` +``__TRYRUN_OUTPUT`` Output from stdout and stderr if the executable were to be run on the target platform. This is created only if the ``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` option was used. -- cgit v0.12 From df8aa3c8add4de253c8eb80129b0893c16d63f2d Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sun, 24 Feb 2019 17:19:45 +1100 Subject: Help: try_compile() readability and grammar improvements --- Help/command/try_compile.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 032e8ed..7c6bc65 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -88,12 +88,12 @@ The options are: given to the ``CMAKE_FLAGS`` option will be ignored. ``LINK_OPTIONS ...`` - Specify link step options to pass to :command:`target_link_options` or - to :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated - project, depending of the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. + Specify link step options to pass to :command:`target_link_options` or to + set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated + project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. ``OUTPUT_VARIABLE `` - Store the output from the build process the given variable. + Store the output from the build process in the given variable. ``_STANDARD `` Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`, @@ -139,8 +139,8 @@ behavior at link time, the ``check_pie_supported()`` command from the :module:`CheckPIESupported` module must be called before using the :command:`try_compile` command. -The current settings of :policy:`CMP0065` and :policy:`CMP0083` are set in the -generated project. +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. -- cgit v0.12 From 861dbef4e718a8500721f48b617c33088067a3a1 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sun, 24 Feb 2019 17:22:53 +1100 Subject: Help: Consistency in try_compile() docs for target type --- Help/command/try_compile.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 7c6bc65..7e13ab1 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -42,13 +42,19 @@ Try Compiling Source Files [_EXTENSIONS ] ) -Try building an executable from one or more source files. The success or -failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is -returned in ````. - -In this form the user need only supply one or more source files that include a -definition for ``main``. CMake will create a ``CMakeLists.txt`` file to build -the source(s) as an executable that looks something like this: +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 ````. + +In this form, one or more source files must be provided. If +:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``, +the sources must include a definition for ``main`` and CMake will create a +``CMakeLists.txt`` file to build the source(s) as an executable. +If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``, +a static library will be built instead and no definition for ``main`` is +required. For an executable, the generated ``CMakeLists.txt`` file would +contain something like the following: .. code-block:: cmake @@ -73,7 +79,7 @@ The options are: in the generated test project. ``COPY_FILE `` - Copy the linked executable to the given ````. + Copy the built executable or static library to the given ````. ``COPY_FILE_ERROR `` Use after ``COPY_FILE`` to capture into variable ```` any error -- cgit v0.12 From 4d55c1f541f2fd31522192e0e8f0838f20de2a29 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sun, 24 Feb 2019 17:23:58 +1100 Subject: Help: Caveat for try_compile() and CMAKE_TRY_COMPILE_PLATFORM_VARIABLES --- Help/command/try_compile.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 7e13ab1..ca8fc77 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -156,7 +156,9 @@ the type of target used for the source file signature. Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify variables that must be propagated into the test project. This variable is -meant for use only in toolchain files. +meant for use only in toolchain files and is only honored by the +``try_compile()`` command for the source files form, not when given a whole +project. If :policy:`CMP0067` is set to ``NEW``, or any of the ``_STANDARD``, ``_STANDARD_REQUIRED``, or ``_EXTENSIONS`` options are used, -- cgit v0.12