Commit 0e8b0ae6 authored by Brad King's avatar Brad King
Browse files

Merge branch 'docs_try_commands' into release-3.14

Merge-request: !3013
parents b3b081cc 4d55c1f5
......@@ -12,12 +12,12 @@ Try Compiling Whole Projects
.. code-block:: cmake
try_compile(RESULT_VAR <bindir> <srcdir>
try_compile(<resultVar> <bindir> <srcdir>
<projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
[OUTPUT_VARIABLE <var>])
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 ``<resultVar>``.
In this form, ``<srcdir>`` should contain a complete CMake project with a
``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>``
......@@ -30,7 +30,7 @@ Try Compiling Source Files
.. code-block:: cmake
try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
......@@ -42,13 +42,19 @@ Try Compiling Source Files
[<LANG>_EXTENSIONS <bool>]
)
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``.
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>``.
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:
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 <fileName>``
Copy the linked executable to the given ``<fileName>``.
Copy the built executable or static library to the given ``<fileName>``.
``COPY_FILE_ERROR <var>``
Use after ``COPY_FILE`` to capture into variable ``<var>`` any error
......@@ -88,12 +94,12 @@ The options are:
given to the ``CMAKE_FLAGS`` option will be ignored.
``LINK_OPTIONS <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 <var>``
Store the output from the build process the given variable.
Store the output from the build process in the given variable.
``<LANG>_STANDARD <std>``
Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`,
......@@ -114,7 +120,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 <resultVar>)`` 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``.
......@@ -139,8 +145,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.
......@@ -150,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 ``<LANG>_STANDARD``,
``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_EXTENSIONS`` options are used,
......
......@@ -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 <flags>...]
try_run(<runResultVar> <compileResultVar>
<bindir> <srcfile> [CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
[LINK_LIBRARIES <libs>...]
......@@ -23,9 +23,9 @@ Try Compiling and Running Source Files
[ARGS <args>...])
Try compiling a ``<srcfile>``. 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 ``<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
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:
``<RUN_RESULT_VAR>``
``<runResultVar>``
Exit code if the executable were to be run on the target platform.
``<RUN_RESULT_VAR>__TRYRUN_OUTPUT``
``<runResultVar>__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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment