mirror of
https://github.com/Kitware/CMake.git
synced 2026-04-24 07:08:38 -05:00
try_compile: Add keyword-dispatched signature
Introduce a new signature for try_compile (and try_run) which removes the `bindir` argument and requires the SOURCES tag. This will eventually allow us to add other ways of providing sources, but also allows us to change the behavior without breaking compatibility. The old signature uses a special, but non-unique temporary location inside the specified `bindir`, which conventionally is just the project's build directory. The new signature unconditionally uses the a unique temporary directory which is unconditionally within the project's build directory (which is no longer separately specified). This ensures that successive runs do not overwrite previous runs, will simplify debugging, and should also, eventually, allow us to execute multiple trials in parallel.
This commit is contained in:
Matthew Woehlke
@@ -41,7 +41,7 @@ Try Compiling Source Files
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
|
||||
try_compile(<resultVar> SOURCES <srcfile...>
|
||||
[CMAKE_FLAGS <flags>...]
|
||||
[COMPILE_DEFINITIONS <defs>...]
|
||||
[LINK_OPTIONS <options>...]
|
||||
@@ -53,6 +53,8 @@ Try Compiling Source Files
|
||||
[<LANG>_EXTENSIONS <bool>]
|
||||
)
|
||||
|
||||
.. versionadded:: 3.25
|
||||
|
||||
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
|
||||
@@ -76,6 +78,39 @@ contain something like the following:
|
||||
target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
|
||||
target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
|
||||
|
||||
CMake will automatically generate a unique directory for each ``try_compile``
|
||||
operation in an unspecified location within the project's binary directory.
|
||||
These directories will be cleaned automatically unless
|
||||
:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to ``cmake``.
|
||||
Such directories from previous runs are also unconditionally cleaned at the
|
||||
beginning of any ``cmake`` execution.
|
||||
|
||||
This command also supports an alternate signature
|
||||
which was present in older versions of CMake:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
|
||||
[CMAKE_FLAGS <flags>...]
|
||||
[COMPILE_DEFINITIONS <defs>...]
|
||||
[LINK_OPTIONS <options>...]
|
||||
[LINK_LIBRARIES <libs>...]
|
||||
[OUTPUT_VARIABLE <var>]
|
||||
[COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
|
||||
[<LANG>_STANDARD <std>]
|
||||
[<LANG>_STANDARD_REQUIRED <bool>]
|
||||
[<LANG>_EXTENSIONS <bool>]
|
||||
)
|
||||
|
||||
In this version, ``try_compile`` will use ``<bindir>/CMakeFiles/CMakeTmp`` for
|
||||
its operation, and all such files will be cleaned automatically.
|
||||
For debugging, :option:`--debug-trycompile <cmake --debug-trycompile>` can be
|
||||
passed to ``cmake`` to avoid this clean. However, multiple sequential
|
||||
``try_compile`` operations, if given the same ``<bindir>``, will reuse this
|
||||
single output directory, such that you can only debug one such ``try_compile``
|
||||
call at a time. Use of the newer signature is recommended to simplify
|
||||
debugging of multiple ``try_compile`` operations.
|
||||
|
||||
The options are:
|
||||
|
||||
``CMAKE_FLAGS <flags>...``
|
||||
@@ -136,18 +171,6 @@ The options are:
|
||||
:prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`,
|
||||
or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project.
|
||||
|
||||
In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be
|
||||
cleaned automatically. For debugging,
|
||||
:option:`--debug-trycompile <cmake --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
|
||||
:option:`--debug-trycompile <cmake --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 <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 :option:`--debug-trycompile <cmake --debug-trycompile>`.
|
||||
|
||||
Other Behavior Settings
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
+43
-33
@@ -12,62 +12,68 @@ Try Compiling and Running Source Files
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
try_run(<runResultVar> <compileResultVar>
|
||||
<bindir> <srcfile> [CMAKE_FLAGS <flags>...]
|
||||
try_run(<runResultVar> <compileResultVar> SOURCES <srcfile...>
|
||||
[CMAKE_FLAGS <flags>...]
|
||||
[COMPILE_DEFINITIONS <defs>...]
|
||||
[LINK_OPTIONS <options>...]
|
||||
[LINK_LIBRARIES <libs>...]
|
||||
[COMPILE_OUTPUT_VARIABLE <var>]
|
||||
[COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
|
||||
[<LANG>_STANDARD <std>]
|
||||
[<LANG>_STANDARD_REQUIRED <bool>]
|
||||
[<LANG>_EXTENSIONS <bool>]
|
||||
[RUN_OUTPUT_VARIABLE <var>]
|
||||
[RUN_OUTPUT_STDOUT_VARIABLE <var>]
|
||||
[RUN_OUTPUT_STDERR_VARIABLE <var>]
|
||||
[OUTPUT_VARIABLE <var>]
|
||||
[WORKING_DIRECTORY <var>]
|
||||
[ARGS <args>...])
|
||||
[ARGS <args>...]
|
||||
)
|
||||
|
||||
.. versionadded:: 3.25
|
||||
|
||||
Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success
|
||||
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.
|
||||
documentation of options common to both commands, and for information on how
|
||||
the test project is constructed to build the source file.
|
||||
|
||||
The options are:
|
||||
This command also supports an alternate signature
|
||||
which was present in older versions of CMake:
|
||||
|
||||
``CMAKE_FLAGS <flags>...``
|
||||
Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed
|
||||
to the :manual:`cmake(1)` 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.
|
||||
.. code-block:: cmake
|
||||
|
||||
``COMPILE_DEFINITIONS <defs>...``
|
||||
Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions`
|
||||
in the generated test project.
|
||||
try_run(<runResultVar> <compileResultVar>
|
||||
<bindir> <srcfile|SOURCES srcfile...>
|
||||
[CMAKE_FLAGS <flags>...]
|
||||
[COMPILE_DEFINITIONS <defs>...]
|
||||
[LINK_OPTIONS <options>...]
|
||||
[LINK_LIBRARIES <libs>...]
|
||||
[COMPILE_OUTPUT_VARIABLE <var>]
|
||||
[COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
|
||||
[<LANG>_STANDARD <std>]
|
||||
[<LANG>_STANDARD_REQUIRED <bool>]
|
||||
[<LANG>_EXTENSIONS <bool>]
|
||||
[RUN_OUTPUT_VARIABLE <var>]
|
||||
[RUN_OUTPUT_STDOUT_VARIABLE <var>]
|
||||
[RUN_OUTPUT_STDERR_VARIABLE <var>]
|
||||
[OUTPUT_VARIABLE <var>]
|
||||
[WORKING_DIRECTORY <var>]
|
||||
[ARGS <args>...]
|
||||
)
|
||||
|
||||
The options specific to ``try_run`` are:
|
||||
|
||||
``COMPILE_OUTPUT_VARIABLE <var>``
|
||||
Report the compile step build output in a given variable.
|
||||
|
||||
``LINK_LIBRARIES <libs>...``
|
||||
.. versionadded:: 3.2
|
||||
|
||||
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.
|
||||
|
||||
``LINK_OPTIONS <options>...``
|
||||
.. versionadded:: 3.14
|
||||
|
||||
Specify link step options to pass to :command:`target_link_options` in the
|
||||
generated project.
|
||||
|
||||
``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.
|
||||
in the given variable. This option exists for legacy reasons and is only
|
||||
supported by the old ``try_run`` signature.
|
||||
Prefer ``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead.
|
||||
|
||||
``RUN_OUTPUT_VARIABLE <var>``
|
||||
Report the output from running the executable in a given variable.
|
||||
@@ -86,7 +92,11 @@ The options are:
|
||||
.. versionadded:: 3.20
|
||||
|
||||
Run the executable in the given directory. If no ``WORKING_DIRECTORY`` is
|
||||
specified, the executable will run in ``<bindir>``.
|
||||
specified, the executable will run in ``<bindir>`` or the current build
|
||||
directory.
|
||||
|
||||
``ARGS <args>...``
|
||||
Additional arguments to pass to the executable when running it.
|
||||
|
||||
Other Behavior Settings
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Reference in New Issue
Block a user