kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge topic 'doc-try_compile' 

219797e4 Help: Revise try_compile and try_run documentation (#15358)
This commit is contained in:
Brad King 2015-02-05 09:25:12 -05:00 committed by CMake Topic Stage
parent 5c29e88972 219797e4be
commit 0ae11b1fb0
2 changed files with 154 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
Help/command/try_compile.rst
View File

@ -1,72 +1,100 @@
try_compile try_compile
----------- -----------
.. only:: html
.. contents::
Try building some code. Try building some code.
Try Compiling Whole Projects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:: ::
try_compile(RESULT_VAR <bindir> <srcdir> try_compile(RESULT_VAR <bindir> <srcdir>
<projectName> [targetName] [CMAKE_FLAGS flags...] <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
[OUTPUT_VARIABLE <var>]) [OUTPUT_VARIABLE <var>])
Try building a project. In this form, srcdir should contain a Try building a project. The success or failure of the ``try_compile``,
complete CMake project with a CMakeLists.txt file and all sources. i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``RESULT_VAR``.
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 In this form, ``<srcdir>`` should contain a complete CMake project with a
'ALL_BUILD' target. ``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...> try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
[CMAKE_FLAGS flags...] [CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS flags...] [COMPILE_DEFINITIONS <defs>...]
[LINK_LIBRARIES libs...] [LINK_LIBRARIES <libs>...]
[OUTPUT_VARIABLE <var>] [OUTPUT_VARIABLE <var>]
[COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]) [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]])
Try building an executable from one or more source files. In this Try building an executable from one or more source files. The success or
form the user need only supply one or more source files that include a failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is
definition for 'main'. CMake will create a CMakeLists.txt file to returned in ``RESULT_VAR``.
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 In this form the user need only supply one or more source files that include a
cleaned automatically. For debugging, --debug-trycompile can be definition for ``main``. CMake will create a ``CMakeLists.txt`` file to build
passed to cmake to avoid this clean. However, multiple sequential the source(s) as an executable that looks something like this::
try_compile operations reuse this single output directory. If you use
--debug-trycompile, you can only debug one try_compile call at a time. add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
The recommended procedure is to protect all try_compile calls in your 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 project by ``if(NOT DEFINED RESULT_VAR)`` logic, configure with cmake
all the way through once, then delete the cache entry associated with 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 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, Other Behavior Settings
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 Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
contain a list of libraries or IMPORTED targets which will be linked a build configuration.
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.

116
Help/command/try_run.rst
View File

@ -1,59 +1,97 @@
try_run try_run
------- -------
.. only:: html
.. contents::
Try compiling and then running some code. Try compiling and then running some code.
Try Compiling and Running Source Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:: ::
try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
bindir srcfile [CMAKE_FLAGS <flags>] bindir srcfile [CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <flags>] [COMPILE_DEFINITIONS <defs>...]
[LINK_LIBRARIES <libs>] [LINK_LIBRARIES <libs>...]
[COMPILE_OUTPUT_VARIABLE comp] [COMPILE_OUTPUT_VARIABLE <var>]
[RUN_OUTPUT_VARIABLE run] [RUN_OUTPUT_VARIABLE <var>]
[OUTPUT_VARIABLE var] [OUTPUT_VARIABLE <var>]
[ARGS <arg1> <arg2>...]) [ARGS <args>...])
Try compiling a srcfile. Return TRUE or FALSE for success or failure Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success
in COMPILE_RESULT_VAR. Then if the compile succeeded, run the or failure in ``COMPILE_RESULT_VAR``. If the compile succeeded, runs the
executable and return its exit code in RUN_RESULT_VAR. If 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 executable was built, but failed to run, then ``RUN_RESULT_VAR`` will be
set to FAILED_TO_RUN. COMPILE_OUTPUT_VARIABLE specifies the variable set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for
where the output from the compile step goes. RUN_OUTPUT_VARIABLE information on how the test project is constructed to build the source file.
specifies the variable where the output from the running executable
goes.
The srcfile signature also accepts a LINK_LIBRARIES argument which may The options are:
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 ``CMAKE_FLAGS <flags>...``
gives you the output from the compile and run step combined. 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 When cross compiling, the executable compiled in the first step
usually cannot be run on the build host. try_run() checks the usually cannot be run on the build host. The ``try_run`` command checks
CMAKE_CROSSCOMPILING variable to detect whether CMake is in the :variable:`CMAKE_CROSSCOMPILING` variable to detect whether CMake is in
crosscompiling mode. If that's the case, it will still try to compile 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 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 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 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. would have produced if it had been run on its actual target platform.
These variables are RUN_RESULT_VAR (explanation see above) and if These cache entries are:
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 ``<RUN_RESULT_VAR>``
if really required. If you use try_run, use RUN_OUTPUT_VARIABLE (or Exit code if the executable were to be run on the target platform.
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 ``<RUN_RESULT_VAR>__TRYRUN_OUTPUT``
configuration. 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.