mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-04-30 11:10:06 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'docs_try_commands'

Browse Source 
4d55c1f541 Help: Caveat for try_compile() and CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
861dbef4e7 Help: Consistency in try_compile() docs for target type
df8aa3c8ad Help: try_compile() readability and grammar improvements
7975edeac5 Help: User-provided variable names for try_* commands

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !3013
This commit is contained in:
Brad King
2019-02-25 12:55:28 +00:00
committed by Kitware Robot
parent 2cc6eedde4 4d55c1f541
commit 224a5c9b07
2 changed files with 33 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Help/command/try_compile.rst
+26 -18
View File
@@ -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,
Help/command/try_run.rst
+7 -7
View File
@@ -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.