Skip to content
Snippets Groups Projects
Commit 0ae11b1f authored by Brad King's avatar Brad King Committed by Kitware Robot
Browse files

Merge topic 'doc-try_compile' 

219797e4 Help: Revise try_compile and try_run documentation (#15358)
parents 5c29e889 219797e4
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Help/command/try_compile.rst
+ 77
− 49
View file @ 0ae11b1f
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.
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.
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.
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 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_compile creates a CMakeList.txt file on the fly that looks like
this:
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 calling cmake>)
add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
include_directories(${INCLUDE_DIRECTORIES})
link_directories(${LINK_DIRECTORIES})
add_executable(cmTryCompileExec sources)
add_executable(cmTryCompileExec <srcfile>...)
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.
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``.
Other Behavior Settings
^^^^^^^^^^^^^^^^^^^^^^^
Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
a build configuration.
Help/command/try_run.rst
+ 83
− 45
View file @ 0ae11b1f
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>...])
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.
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.
For compatibility reasons OUTPUT_VARIABLE is still supported, which
gives you the output from the compile and run step combined.
Cross compiling issues
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>``. 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 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 example in :command:`try_compile` 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.
``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.
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.
Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
configuration.
These cache entries are:
``<RUN_RESULT_VAR>``
Exit code if the executable were to be run on the target platform.
``<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.
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