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.

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
 -------------------------
 

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

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.

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
+property is initialized by the value of the
-CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is
+:variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` variable if
-created.
+it is set when a target is created.

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.

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.

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.

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
+property is initialized by the value of the
-CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is
+:variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` variable if
-created.
+it is set when a target is created.

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.

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.

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.

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
+property is initialized by the value of the
-CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is
+:variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` variable if
-created.
+it is set when a target is created.

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.

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.

Help/prop_tgt/TARGET_FILE_TYPES.txt

@@ -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.

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.

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.
+overrides :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`OUTPUT_NAME_<CONFIG>`
-
+properties.
-.. include:: TARGET_FILE_TYPES.txt

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.

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.

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.

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.

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.

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.