Help: Revise try_compile and try_run documentation (#15358)
Rewrite the documentation using better reStructuredText markup constructs. Clarify interaction of options like LINK_LIBRARIES and CMAKE_FLAGS.
This commit is contained in:
Brad King
parent
aec11372a5
commit
219797e4be
|
|
@ -1,72 +1,100 @@
|
|||
try_compile
|
||||
-----------
|
||||
|
||||
.. only:: html
|
||||
|
||||
.. contents::
|
||||
|
||||
Try building some code.
|
||||
|
||||
Try Compiling Whole Projects
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
try_compile(RESULT_VAR <bindir> <srcdir>
|
||||
<projectName> [targetName] [CMAKE_FLAGS flags...]
|
||||
<projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
|
||||
[OUTPUT_VARIABLE <var>])
|
||||
|
||||
Try building a project. In this form, srcdir should contain a
|
||||
complete CMake project with a CMakeLists.txt file and all sources.
|
||||
The bindir and srcdir will not be deleted after this command is run.
|
||||
Specify targetName to build a specific target instead of the 'all' or
|
||||
'ALL_BUILD' target.
|
||||
Try building a project. The success or failure of the ``try_compile``,
|
||||
i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``RESULT_VAR``.
|
||||
|
||||
In this form, ``<srcdir>`` should contain a complete CMake project with a
|
||||
``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>``
|
||||
will not be deleted after this command is run. Specify ``<targetName>`` to
|
||||
build a specific target instead of the ``all`` or ``ALL_BUILD`` target. See
|
||||
below for the meaning of other options.
|
||||
|
||||
Try Compiling Source Files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
|
||||
[CMAKE_FLAGS flags...]
|
||||
[COMPILE_DEFINITIONS flags...]
|
||||
[LINK_LIBRARIES libs...]
|
||||
[CMAKE_FLAGS <flags>...]
|
||||
[COMPILE_DEFINITIONS <defs>...]
|
||||
[LINK_LIBRARIES <libs>...]
|
||||
[OUTPUT_VARIABLE <var>]
|
||||
[COPY_FILE <fileName> [COPY_FILE_ERROR <var>]])
|
||||
|
||||
Try building an executable from one or more source files. 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. Specify COPY_FILE to get a copy
|
||||
of the linked executable at the given fileName and optionally
|
||||
COPY_FILE_ERROR to capture any error.
|
||||
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``.
|
||||
|
||||
In this version all files in bindir/CMakeFiles/CMakeTmp will be
|
||||
cleaned automatically. For debugging, --debug-trycompile can be
|
||||
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
|
||||
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::
|
||||
|
||||
add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
|
||||
include_directories(${INCLUDE_DIRECTORIES})
|
||||
link_directories(${LINK_DIRECTORIES})
|
||||
add_executable(cmTryCompileExec <srcfile>...)
|
||||
target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
|
||||
|
||||
The options are:
|
||||
|
||||
``CMAKE_FLAGS <flags>...``
|
||||
Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to
|
||||
the ``cmake`` command-line used to drive the test build.
|
||||
The above example shows how values for variables
|
||||
``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
|
||||
are used.
|
||||
|
||||
``COMPILE_DEFINITIONS <defs>...``
|
||||
Specify ``-Ddefinition`` arguments to pass to ``add_definitions``
|
||||
in the generated test project.
|
||||
|
||||
``COPY_FILE <fileName>``
|
||||
Copy the linked executable to the given ``<fileName>``.
|
||||
|
||||
``COPY_FILE_ERROR <var>``
|
||||
Use after ``COPY_FILE`` to capture into variable ``<var>`` any error
|
||||
message encountered while trying to copy the file.
|
||||
|
||||
``LINK_LIBRARIES <libs>...``
|
||||
Specify libraries to be linked in the generated project.
|
||||
The list of libraries may refer to system libraries and to
|
||||
:ref:`Imported Targets <Imported Targets>` from the calling project.
|
||||
|
||||
If this option is specified, any ``-DLINK_LIBRARIES=...`` value
|
||||
given to the ``CMAKE_FLAGS`` option will be ignored.
|
||||
|
||||
``OUTPUT_VARIABLE <var>``
|
||||
Store the output from the build process the given variable.
|
||||
|
||||
In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be
|
||||
cleaned automatically. For debugging, ``--debug-trycompile`` can be
|
||||
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
|
||||
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.
|
||||
``--debug-trycompile``.
|
||||
|
||||
Some extra flags that can be included are, INCLUDE_DIRECTORIES,
|
||||
LINK_DIRECTORIES, and LINK_LIBRARIES. COMPILE_DEFINITIONS are
|
||||
-Ddefinition that will be passed to the compile line.
|
||||
Other Behavior Settings
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The srcfile signature also accepts a LINK_LIBRARIES argument which may
|
||||
contain a list of libraries or IMPORTED targets which will be linked
|
||||
to in the generated project. If LINK_LIBRARIES is specified as a
|
||||
parameter to try_compile, then any LINK_LIBRARIES passed as
|
||||
CMAKE_FLAGS will be ignored.
|
||||
|
||||
try_compile creates a CMakeList.txt file on the fly that looks like
|
||||
this:
|
||||
|
||||
::
|
||||
|
||||
add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>)
|
||||
include_directories(${INCLUDE_DIRECTORIES})
|
||||
link_directories(${LINK_DIRECTORIES})
|
||||
add_executable(cmTryCompileExec sources)
|
||||
target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
|
||||
|
||||
In both versions of the command, if OUTPUT_VARIABLE is specified, then
|
||||
the output from the build process is stored in the given variable.
|
||||
The success or failure of the try_compile, i.e. TRUE or FALSE
|
||||
respectively, is returned in RESULT_VAR. CMAKE_FLAGS can be used to
|
||||
pass -DVAR:TYPE=VALUE flags to the cmake that is run during the build.
|
||||
Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
|
||||
configuration.
|
||||
Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
|
||||
a build configuration.
|
||||
|
|
|
|||
|
|
@ -1,59 +1,97 @@
|
|||
try_run
|
||||
-------
|
||||
|
||||
.. only:: html
|
||||
|
||||
.. contents::
|
||||
|
||||
Try compiling and then running some code.
|
||||
|
||||
Try Compiling and Running Source Files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
|
||||
bindir srcfile [CMAKE_FLAGS <flags>]
|
||||
[COMPILE_DEFINITIONS <flags>]
|
||||
[LINK_LIBRARIES <libs>]
|
||||
[COMPILE_OUTPUT_VARIABLE comp]
|
||||
[RUN_OUTPUT_VARIABLE run]
|
||||
[OUTPUT_VARIABLE var]
|
||||
[ARGS <arg1> <arg2>...])
|
||||
bindir srcfile [CMAKE_FLAGS <flags>...]
|
||||
[COMPILE_DEFINITIONS <defs>...]
|
||||
[LINK_LIBRARIES <libs>...]
|
||||
[COMPILE_OUTPUT_VARIABLE <var>]
|
||||
[RUN_OUTPUT_VARIABLE <var>]
|
||||
[OUTPUT_VARIABLE <var>]
|
||||
[ARGS <args>...])
|
||||
|
||||
Try compiling a srcfile. Return TRUE or FALSE for success or failure
|
||||
in COMPILE_RESULT_VAR. Then if the compile succeeded, run the
|
||||
executable and return its exit code in RUN_RESULT_VAR. If the
|
||||
executable was built, but failed to run, then RUN_RESULT_VAR will be
|
||||
set to FAILED_TO_RUN. COMPILE_OUTPUT_VARIABLE specifies the variable
|
||||
where the output from the compile step goes. RUN_OUTPUT_VARIABLE
|
||||
specifies the variable where the output from the running executable
|
||||
goes.
|
||||
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
|
||||
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.
|
||||
|
||||
The srcfile signature also accepts a LINK_LIBRARIES argument which may
|
||||
contain a list of libraries or IMPORTED targets which will be linked
|
||||
to in the generated project. If LINK_LIBRARIES is specified as a
|
||||
parameter to try_run, then any LINK_LIBRARIES passed as
|
||||
CMAKE_FLAGS will be ignored.
|
||||
The options are:
|
||||
|
||||
For compatibility reasons OUTPUT_VARIABLE is still supported, which
|
||||
gives you the output from the compile and run step combined.
|
||||
``CMAKE_FLAGS <flags>...``
|
||||
Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to
|
||||
the ``cmake`` command-line used to drive the test build.
|
||||
The example in :command:`try_compile` shows how values for variables
|
||||
``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
|
||||
are used.
|
||||
|
||||
Cross compiling issues
|
||||
``COMPILE_DEFINITIONS <defs>...``
|
||||
Specify ``-Ddefinition`` arguments to pass to ``add_definitions``
|
||||
in the generated test project.
|
||||
|
||||
``COMPILE_OUTPUT_VARIABLE <var>``
|
||||
Report the compile step build output in a given variable.
|
||||
|
||||
``LINK_LIBRARIES <libs>...``
|
||||
Specify libraries to be linked in the generated project.
|
||||
The list of libraries may refer to system libraries and to
|
||||
:ref:`Imported Targets <Imported Targets>` from the calling project.
|
||||
|
||||
If this option is specified, any ``-DLINK_LIBRARIES=...`` value
|
||||
given to the ``CMAKE_FLAGS`` option will be ignored.
|
||||
|
||||
``OUTPUT_VARIABLE <var>``
|
||||
Report the compile build output and the output from running the executable
|
||||
in the given variable. This option exists for legacy reasons. Prefer
|
||||
``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead.
|
||||
|
||||
``RUN_OUTPUT_VARIABLE <var>``
|
||||
Report the output from running the executable in a given variable.
|
||||
|
||||
Other Behavior Settings
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
|
||||
a build configuration.
|
||||
|
||||
Behavior when Cross Compiling
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When cross compiling, the executable compiled in the first step
|
||||
usually cannot be run on the build host. try_run() checks the
|
||||
CMAKE_CROSSCOMPILING variable to detect whether CMake is in
|
||||
crosscompiling mode. If that's the case, it will still try to compile
|
||||
usually cannot be run on the build host. The ``try_run`` command checks
|
||||
the :variable:`CMAKE_CROSSCOMPILING` variable to detect whether CMake is in
|
||||
cross-compiling mode. If that is the case, it will still try to compile
|
||||
the executable, but it will not try to run the executable. Instead it
|
||||
will create cache variables which must be filled by the user or by
|
||||
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 variables are RUN_RESULT_VAR (explanation see above) and if
|
||||
RUN_OUTPUT_VARIABLE (or OUTPUT_VARIABLE) was used, an additional cache
|
||||
variable RUN_RESULT_VAR__COMPILE_RESULT_VAR__TRYRUN_OUTPUT.This is
|
||||
intended to hold stdout and stderr from the executable.
|
||||
These cache entries are:
|
||||
|
||||
In order to make cross compiling your project easier, use try_run only
|
||||
if really required. If you use try_run, use RUN_OUTPUT_VARIABLE (or
|
||||
OUTPUT_VARIABLE) only if really required. Using them will require
|
||||
that when crosscompiling, the cache variables will have to be set
|
||||
manually to the output of the executable. You can also "guard" the
|
||||
calls to try_run with if(CMAKE_CROSSCOMPILING) and provide an
|
||||
easy-to-preset alternative for this case.
|
||||
``<RUN_RESULT_VAR>``
|
||||
Exit code if the executable were to be run on the target platform.
|
||||
|
||||
Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
|
||||
configuration.
|
||||
``<RUN_RESULT_VAR>__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.
|
||||
|
||||
In order to make cross compiling your project easier, use ``try_run``
|
||||
only if really required. If you use ``try_run``, use the
|
||||
``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` options only if really
|
||||
required. Using them will require that when cross-compiling, the cache
|
||||
variables will have to be set manually to the output of the executable.
|
||||
You can also "guard" the calls to ``try_run`` with an :command:`if`
|
||||
block checking the :variable:`CMAKE_CROSSCOMPILING` variable and
|
||||
provide an easy-to-preset alternative for this case.
|
||||
|
|
|
|||
Loading…
Reference in New Issue