diff options
Diffstat (limited to 'Help')
23 files changed, 161 insertions, 49 deletions
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index ae5e58e..c8525c2 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -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 ------------------------- diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 865e1ef..cbc8a07 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -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 diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst index df57dba..4221069 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst @@ -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. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst index 3c0c4fd..29991eb 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst @@ -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. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst index a137bb8..6150193 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst @@ -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. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst index 314fa58..4f62eb9 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst @@ -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. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst index e1d3a82..785a57b 100644 --- a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst @@ -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. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst index 2a38373..6fc0142 100644 --- a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -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. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst b/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst index 9e9d401..6027f7f 100644 --- a/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst +++ b/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst @@ -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. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst b/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst index 785d1b2..1994c7b 100644 --- a/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst +++ b/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst @@ -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. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst index af5ef44..12390f5 100644 --- a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst @@ -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. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst index 10be6cf..c100346 100644 --- a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -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. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst b/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst index dc7dba4..11729c3 100644 --- a/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst +++ b/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst @@ -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. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst b/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst index f9029e5..b6a31bf 100644 --- a/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst +++ b/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst @@ -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. diff --git a/Help/prop_tgt/TARGET_FILE_TYPES.txt b/Help/prop_tgt/TARGET_FILE_TYPES.txt deleted file mode 100644 index 18489c7..0000000 --- a/Help/prop_tgt/TARGET_FILE_TYPES.txt +++ /dev/null @@ -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. diff --git a/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt b/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt index 65abbce..0b3d31c 100644 --- a/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt +++ b/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt @@ -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. diff --git a/Help/prop_tgt/XXX_OUTPUT_NAME.txt b/Help/prop_tgt/XXX_OUTPUT_NAME.txt index 9c4fc7c..126f391 100644 --- a/Help/prop_tgt/XXX_OUTPUT_NAME.txt +++ b/Help/prop_tgt/XXX_OUTPUT_NAME.txt @@ -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. diff --git a/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst index 6a22f73..c889321 100644 --- a/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst +++ b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst @@ -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. diff --git a/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..94c2b6e --- /dev/null +++ b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst @@ -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. diff --git a/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst index 3bdd348..e97296d 100644 --- a/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst +++ b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst @@ -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. diff --git a/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..e069cdd --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -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. diff --git a/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst index 366ca66..6253d4a 100644 --- a/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst +++ b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst @@ -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. diff --git a/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..080dea6 --- /dev/null +++ b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -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. |