Help: Revise buildsystem artifact file type documentation (#15539)
Add sections to the cmake-buildsystem(7) manual and cross-reference them with relevant variables and target properties. This avoids duplicating the information and allows it to be more detailed.
This commit is contained in:
Brad King
parent
f0673c1022
commit
d401aa21c9
|
|
@ -695,8 +695,10 @@ edge of linking ``exe1`` is determined by the same
|
|||
:prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above
|
||||
contains a cycle. :manual:`cmake(1)` issues a diagnostic in this case.
|
||||
|
||||
Output Files
|
||||
------------
|
||||
.. _`Output Artifacts`:
|
||||
|
||||
Output Artifacts
|
||||
----------------
|
||||
|
||||
The buildsystem targets created by the :command:`add_library` and
|
||||
:command:`add_executable` commands create rules to create binary outputs.
|
||||
|
|
@ -708,6 +710,71 @@ name and location of generated binaries. These expressions do not work
|
|||
for ``OBJECT`` libraries however, as there is no single file generated
|
||||
by such libraries which is relevant to the expressions.
|
||||
|
||||
There are three kinds of output artifacts that may be build by targets
|
||||
as detailed in the following sections. Their classification differs
|
||||
between DLL platforms and non-DLL platforms. All Windows-based
|
||||
systems including Cygwin are DLL platforms.
|
||||
|
||||
.. _`Runtime Output Artifacts`:
|
||||
|
||||
Runtime Output Artifacts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A *runtime* output artifact of a buildsystem target may be:
|
||||
|
||||
* The executable file (e.g. ``.exe``) of an executable target
|
||||
created by the :command:`add_executable` command.
|
||||
|
||||
* On DLL platforms: the executable file (e.g. ``.dll``) of a shared
|
||||
library target created by the :command:`add_library` command
|
||||
with the ``SHARED`` option.
|
||||
|
||||
The :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`RUNTIME_OUTPUT_NAME`
|
||||
target properties may be used to control runtime output artifact locations
|
||||
and names in the build tree.
|
||||
|
||||
.. _`Library Output Artifacts`:
|
||||
|
||||
Library Output Artifacts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A *library* output artifact of a buildsystem target may be:
|
||||
|
||||
* The loadable module file (e.g. ``.dll`` or ``.so``) of a module
|
||||
library target created by the :command:`add_library` command
|
||||
with the ``MODULE`` option.
|
||||
|
||||
* On non-DLL platforms: the shared library file (e.g. ``.so`` or ``.dylib``)
|
||||
of a shared shared library target created by the :command:`add_library`
|
||||
command with the ``SHARED`` option.
|
||||
|
||||
The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME`
|
||||
target properties may be used to control library output artifact locations
|
||||
and names in the build tree.
|
||||
|
||||
.. _`Archive Output Artifacts`:
|
||||
|
||||
Archive Output Artifacts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
An *archive* output artifact of a buildsystem target may be:
|
||||
|
||||
* The static library file (e.g. ``.lib`` or ``.a``) of a static
|
||||
library target created by the :command:`add_library` command
|
||||
with the ``STATIC`` option.
|
||||
|
||||
* On DLL platforms: the import library file (e.g. ``.lib``) of a shared
|
||||
library target created by the :command:`add_library` command
|
||||
with the ``SHARED`` option.
|
||||
|
||||
* On DLL platforms: the import library file (e.g. ``.lib``) of an
|
||||
executable target created by the :command:`add_executable` command
|
||||
when its :prop_tgt:`ENABLE_EXPORTS` target property is set.
|
||||
|
||||
The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`
|
||||
target properties may be used to control archive output artifact locations
|
||||
and names in the build tree.
|
||||
|
||||
Directory-Scoped Commands
|
||||
-------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -213,6 +213,7 @@ Variables that Control the Build
|
|||
/variable/CMAKE_ANDROID_API_MIN
|
||||
/variable/CMAKE_ANDROID_GUI
|
||||
/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY
|
||||
/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG
|
||||
/variable/CMAKE_AUTOMOC_MOC_OPTIONS
|
||||
/variable/CMAKE_AUTOMOC
|
||||
/variable/CMAKE_AUTORCC
|
||||
|
|
@ -236,6 +237,7 @@ Variables that Control the Build
|
|||
/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH
|
||||
/variable/CMAKE_LANG_VISIBILITY_PRESET
|
||||
/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY
|
||||
/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG
|
||||
/variable/CMAKE_LIBRARY_PATH_FLAG
|
||||
/variable/CMAKE_LINK_DEF_FILE_FLAG
|
||||
/variable/CMAKE_LINK_DEPENDS_NO_SHARED
|
||||
|
|
@ -256,6 +258,7 @@ Variables that Control the Build
|
|||
/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG
|
||||
/variable/CMAKE_POSITION_INDEPENDENT_CODE
|
||||
/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY
|
||||
/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG
|
||||
/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG
|
||||
/variable/CMAKE_SHARED_LINKER_FLAGS
|
||||
/variable/CMAKE_SKIP_BUILD_RPATH
|
||||
|
|
|
|||
|
|
@ -1,7 +1,9 @@
|
|||
ARCHIVE_OUTPUT_DIRECTORY
|
||||
------------------------
|
||||
|
||||
.. |XXX| replace:: ARCHIVE
|
||||
.. |XXX| replace:: :ref:`ARCHIVE <Archive Output Artifacts>`
|
||||
.. |xxx| replace:: archive
|
||||
.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_ARCHIVE_OUTPUT_DIRECTORY
|
||||
.. include:: XXX_OUTPUT_DIRECTORY.txt
|
||||
|
||||
See also the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` target property.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
|
||||
---------------------------------
|
||||
|
||||
Per-configuration output directory for ARCHIVE target files.
|
||||
Per-configuration output directory for
|
||||
:ref:`ARCHIVE <Archive Output Artifacts>` target files.
|
||||
|
||||
This is a per-configuration version of ARCHIVE_OUTPUT_DIRECTORY, but
|
||||
This is a per-configuration version of the
|
||||
:prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` target property, but
|
||||
multi-configuration generators (VS, Xcode) do NOT append a
|
||||
per-configuration subdirectory to the specified directory. This
|
||||
property is initialized by the value of the variable
|
||||
CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is
|
||||
created.
|
||||
property is initialized by the value of the
|
||||
:variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` variable if
|
||||
it is set when a target is created.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
ARCHIVE_OUTPUT_NAME
|
||||
-------------------
|
||||
|
||||
.. |XXX| replace:: ARCHIVE
|
||||
.. |XXX| replace:: :ref:`ARCHIVE <Archive Output Artifacts>`
|
||||
.. |xxx| replace:: archive
|
||||
.. include:: XXX_OUTPUT_NAME.txt
|
||||
|
||||
See also the :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` target property.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
ARCHIVE_OUTPUT_NAME_<CONFIG>
|
||||
----------------------------
|
||||
|
||||
Per-configuration output name for ARCHIVE target files.
|
||||
Per-configuration output name for
|
||||
:ref:`ARCHIVE <Archive Output Artifacts>` target files.
|
||||
|
||||
This is the configuration-specific version of ARCHIVE_OUTPUT_NAME.
|
||||
This is the configuration-specific version of the
|
||||
:prop_tgt:`ARCHIVE_OUTPUT_NAME` target property.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,9 @@
|
|||
LIBRARY_OUTPUT_DIRECTORY
|
||||
------------------------
|
||||
|
||||
.. |XXX| replace:: LIBRARY
|
||||
.. |XXX| replace:: :ref:`LIBRARY <Library Output Artifacts>`
|
||||
.. |xxx| replace:: library
|
||||
.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_LIBRARY_OUTPUT_DIRECTORY
|
||||
.. include:: XXX_OUTPUT_DIRECTORY.txt
|
||||
|
||||
See also the :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` target property.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
|
||||
---------------------------------
|
||||
|
||||
Per-configuration output directory for LIBRARY target files.
|
||||
Per-configuration output directory for
|
||||
:ref:`LIBRARY <Library Output Artifacts>` target files.
|
||||
|
||||
This is a per-configuration version of LIBRARY_OUTPUT_DIRECTORY, but
|
||||
This is a per-configuration version of the
|
||||
:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` target property, but
|
||||
multi-configuration generators (VS, Xcode) do NOT append a
|
||||
per-configuration subdirectory to the specified directory. This
|
||||
property is initialized by the value of the variable
|
||||
CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is
|
||||
created.
|
||||
property is initialized by the value of the
|
||||
:variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` variable if
|
||||
it is set when a target is created.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
LIBRARY_OUTPUT_NAME
|
||||
-------------------
|
||||
|
||||
.. |XXX| replace:: LIBRARY
|
||||
.. |XXX| replace:: :ref:`LIBRARY <Library Output Artifacts>`
|
||||
.. |xxx| replace:: library
|
||||
.. include:: XXX_OUTPUT_NAME.txt
|
||||
|
||||
See also the :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` target property.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
LIBRARY_OUTPUT_NAME_<CONFIG>
|
||||
----------------------------
|
||||
|
||||
Per-configuration output name for LIBRARY target files.
|
||||
Per-configuration output name for
|
||||
:ref:`LIBRARY <Library Output Artifacts>` target files.
|
||||
|
||||
This is the configuration-specific version of LIBRARY_OUTPUT_NAME.
|
||||
This is the configuration-specific version of the
|
||||
:prop_tgt:`LIBRARY_OUTPUT_NAME` target property.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,9 @@
|
|||
RUNTIME_OUTPUT_DIRECTORY
|
||||
------------------------
|
||||
|
||||
.. |XXX| replace:: RUNTIME
|
||||
.. |XXX| replace:: :ref:`RUNTIME <Runtime Output Artifacts>`
|
||||
.. |xxx| replace:: runtime
|
||||
.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_RUNTIME_OUTPUT_DIRECTORY
|
||||
.. include:: XXX_OUTPUT_DIRECTORY.txt
|
||||
|
||||
See also the :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` target property.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
|
||||
---------------------------------
|
||||
|
||||
Per-configuration output directory for RUNTIME target files.
|
||||
Per-configuration output directory for
|
||||
:ref:`RUNTIME <Runtime Output Artifacts>` target files.
|
||||
|
||||
This is a per-configuration version of RUNTIME_OUTPUT_DIRECTORY, but
|
||||
This is a per-configuration version of the
|
||||
:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target property, but
|
||||
multi-configuration generators (VS, Xcode) do NOT append a
|
||||
per-configuration subdirectory to the specified directory. This
|
||||
property is initialized by the value of the variable
|
||||
CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is
|
||||
created.
|
||||
property is initialized by the value of the
|
||||
:variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` variable if
|
||||
it is set when a target is created.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
RUNTIME_OUTPUT_NAME
|
||||
-------------------
|
||||
|
||||
.. |XXX| replace:: RUNTIME
|
||||
.. |XXX| replace:: :ref:`RUNTIME <Runtime Output Artifacts>`
|
||||
.. |xxx| replace:: runtime
|
||||
.. include:: XXX_OUTPUT_NAME.txt
|
||||
|
||||
See also the :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>` target property.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
RUNTIME_OUTPUT_NAME_<CONFIG>
|
||||
----------------------------
|
||||
|
||||
Per-configuration output name for RUNTIME target files.
|
||||
Per-configuration output name for
|
||||
:ref:`RUNTIME <Runtime Output Artifacts>` target files.
|
||||
|
||||
This is the configuration-specific version of RUNTIME_OUTPUT_NAME.
|
||||
This is the configuration-specific version of the
|
||||
:prop_tgt:`RUNTIME_OUTPUT_NAME` target property.
|
||||
|
|
|
|||
|
|
@ -1,9 +0,0 @@
|
|||
There are three kinds of target files that may be built: archive,
|
||||
library, and runtime. Executables are always treated as runtime
|
||||
targets. Static libraries are always treated as archive targets.
|
||||
Module libraries are always treated as library targets. For
|
||||
non-DLL platforms shared libraries are treated as library
|
||||
targets. For DLL platforms the DLL part of a shared library is
|
||||
treated as a runtime target and the corresponding import library
|
||||
is treated as an archive target. All Windows-based systems
|
||||
including Cygwin are DLL platforms.
|
||||
|
|
@ -4,7 +4,5 @@ This property specifies the directory into which |xxx| target files
|
|||
should be built. Multi-configuration generators (VS, Xcode) append a
|
||||
per-configuration subdirectory to the specified directory.
|
||||
|
||||
.. include:: TARGET_FILE_TYPES.txt
|
||||
|
||||
This property is initialized by the value of the variable
|
||||
|CMAKE_XXX_OUTPUT_DIRECTORY| if it is set when a target is created.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
Output name for |XXX| target files.
|
||||
|
||||
This property specifies the base name for |xxx| target files. It
|
||||
overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
|
||||
|
||||
.. include:: TARGET_FILE_TYPES.txt
|
||||
overrides :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`OUTPUT_NAME_<CONFIG>`
|
||||
properties.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,9 @@
|
|||
CMAKE_ARCHIVE_OUTPUT_DIRECTORY
|
||||
------------------------------
|
||||
|
||||
Where to put all the ARCHIVE targets when built.
|
||||
Where to put all the :ref:`ARCHIVE <Archive Output Artifacts>`
|
||||
target files when built.
|
||||
|
||||
This variable is used to initialize the ARCHIVE_OUTPUT_DIRECTORY
|
||||
This variable is used to initialize the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`
|
||||
property on all the targets. See that target property for additional
|
||||
information.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
|
||||
---------------------------------------
|
||||
|
||||
Where to put all the :ref:`ARCHIVE <Archive Output Artifacts>`
|
||||
target files when built for a specific configuration.
|
||||
|
||||
This variable is used to initialize the
|
||||
:prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets.
|
||||
See that target property for additional information.
|
||||
|
|
@ -1,8 +1,9 @@
|
|||
CMAKE_LIBRARY_OUTPUT_DIRECTORY
|
||||
------------------------------
|
||||
|
||||
Where to put all the LIBRARY targets when built.
|
||||
Where to put all the :ref:`LIBRARY <Library Output Artifacts>`
|
||||
target files when built.
|
||||
|
||||
This variable is used to initialize the LIBRARY_OUTPUT_DIRECTORY
|
||||
This variable is used to initialize the :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`
|
||||
property on all the targets. See that target property for additional
|
||||
information.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
|
||||
---------------------------------------
|
||||
|
||||
Where to put all the :ref:`LIBRARY <Library Output Artifacts>`
|
||||
target files when built for a specific configuration.
|
||||
|
||||
This variable is used to initialize the
|
||||
:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets.
|
||||
See that target property for additional information.
|
||||
|
|
@ -1,8 +1,9 @@
|
|||
CMAKE_RUNTIME_OUTPUT_DIRECTORY
|
||||
------------------------------
|
||||
|
||||
Where to put all the RUNTIME targets when built.
|
||||
Where to put all the :ref:`RUNTIME <Runtime Output Artifacts>`
|
||||
target files when built.
|
||||
|
||||
This variable is used to initialize the RUNTIME_OUTPUT_DIRECTORY
|
||||
This variable is used to initialize the :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY`
|
||||
property on all the targets. See that target property for additional
|
||||
information.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
|
||||
---------------------------------------
|
||||
|
||||
Where to put all the :ref:`RUNTIME <Runtime Output Artifacts>`
|
||||
target files when built for a specific configuration.
|
||||
|
||||
This variable is used to initialize the
|
||||
:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets.
|
||||
See that target property for additional information.
|
||||
Loading…
Reference in New Issue