Help: Add documentation for CPack External generator

2 files changed, 250 insertions, 0 deletions

diff --git a/Help/cpack_gen/external.rst b/Help/cpack_gen/external.rst
new file mode 100644
index 0000000..a69866d
--- /dev/null
+++ b/Help/cpack_gen/external.rst
@@ -0,0 +1,249 @@
+CPack External Generator
+------------------------
+
+CPack provides many generators to create packages for a variety of platforms
+and packaging systems. The intention is for CMake/CPack to be a complete
+end-to-end solution for building and packaging a software project. However, it
+may not always be possible to use CPack for the entire packaging process, due
+to either technical limitations or policies that require the use of certain
+tools. For this reason, CPack provides the "External" generator, which allows
+external packaging software to take advantage of some of the functionality
+provided by CPack, such as component installation and the dependency graph.
+
+The CPack External generator doesn't actually package any files. Instead, it
+generates a .json file containing the CPack internal metadata, which gives
+external software information on how to package the software. This metadata
+file contains a list of CPack components and component groups, the various
+options passed to :command:`cpack_add_component` and
+:command:`cpack_add_component_group`, the dependencies between the components
+and component groups, and various other options passed to CPack.
+
+Format
+^^^^^^
+
+The file produced by the CPack External generator is a .json file with an
+object as its root. This root object will always provide two fields:
+``formatVersionMajor`` and ``formatVersionMinor``, which are always integers
+that describe the output format of the generator. Backwards-compatible changes
+to the output format (for example, adding a new field that didn't exist before)
+cause the minor version to be incremented, and backwards-incompatible changes
+(for example, deleting a field or changing its meaning) cause the major version
+to be incremented and the minor version reset to 0. The format version is
+always of the format ``major.minor``. In other words, it always has exactly two
+parts, separated by a period.
+
+You can request one or more specific versions of the output format as described
+below with :variable:`CPACK_EXT_REQUESTED_VERSIONS`. The output format will
+have a major version that exactly matches the requested major version, and a
+minor version that is greater than or equal to the requested minor version. If
+no version is requested with :variable:`CPACK_EXT_REQUESTED_VERSIONS`, the
+latest known major version is used by default. Currently, the only supported
+format is 1.0, which is described below.
+
+Version 1.0
+***********
+
+In addition to the standard format fields, format version 1.0 provides the
+following fields in the root:
+
+``components``
+  The ``components`` field is an object with component names as the keys and
+  objects describing the components as the values. The component objects have
+  the following fields:
+
+  ``name``
+    The name of the component. This is always the same as the key in the
+    ``components`` object.
+
+  ``displayName``
+    The value of the ``DISPLAY_NAME`` field passed to
+    :command:`cpack_add_component`.
+
+  ``description``
+    The value of the ``DESCRIPTION`` field passed to
+    :command:`cpack_add_component`.
+
+  ``isHidden``
+    True if ``HIDDEN`` was passed to :command:`cpack_add_component`, false if
+    it was not.
+
+  ``isRequired``
+    True if ``REQUIRED`` was passed to :command:`cpack_add_component`, false if
+    it was not.
+
+  ``isDisabledByDefault``
+    True if ``DISABLED`` was passed to :command:`cpack_add_component`, false if
+    it was not.
+
+  ``group``
+    Only present if ``GROUP`` was passed to :command:`cpack_add_component`. If
+    so, this field is a string value containing the component's group.
+
+  ``dependencies``
+    An array of components the component depends on. This contains the values
+    in the ``DEPENDS`` argument passed to :command:`cpack_add_component`. If no
+    ``DEPENDS`` argument was passed, this is an empty list.
+
+  ``installationTypes``
+    An array of installation types the component is part of. This contains the
+    values in the ``INSTALL_TYPES`` argument passed to
+    :command:`cpack_add_component`. If no ``INSTALL_TYPES`` argument was
+    passed, this is an empty list.
+
+  ``isDownloaded``
+    True if ``DOWNLOADED`` was passed to :command:`cpack_add_component`, false
+    if it was not.
+
+  ``archiveFile``
+    The name of the archive file passed with the ``ARCHIVE_FILE`` argument to
+    :command:`cpack_add_component`. If no ``ARCHIVE_FILE`` argument was passed,
+    this is an empty string.
+
+``componentGroups``
+  The ``componentGroups`` field is an object with component group names as the
+  keys and objects describing the component groups as the values. The component
+  group objects have the following fields:
+
+  ``name``
+    The name of the component group. This is always the same as the key in the
+    ``componentGroups`` object.
+
+  ``displayName``
+    The value of the ``DISPLAY_NAME`` field passed to
+    :command:`cpack_add_component_group`.
+
+  ``description``
+    The value of the ``DESCRIPTION`` field passed to
+    :command:`cpack_add_component_group`.
+
+  ``parentGroup``
+    Only present if ``PARENT_GROUP`` was passed to
+    :command:`cpack_add_component_group`. If so, this field is a string value
+    containing the component group's parent group.
+
+  ``isExpandedByDefault``
+    True if ``EXPANDED`` was passed to :command:`cpack_add_component_group`,
+    false if it was not.
+
+  ``isBold``
+    True if ``BOLD_TITLE`` was passed to :command:`cpack_add_component_group`,
+    false if it was not.
+
+  ``components``
+    An array of names of components that are direct members of the group
+    (components that have this group as their ``GROUP``). Components of
+    subgroups are not included.
+
+  ``subgroups``
+    An array of names of component groups that are subgroups of the group
+    (groups that have this group as their ``PARENT_GROUP``).
+
+``installationTypes``
+  The ``installationTypes`` field is an object with installation type names as
+  the keys and objects describing the installation types as the values. The
+  installation type objects have the following fields:
+
+  ``name``
+    The name of the installation type. This is always the same as the key in
+    the ``installationTypes`` object.
+
+  ``displayName``
+    The value of the ``DISPLAY_NAME`` field passed to
+    :command:`cpack_add_install_type`.
+
+  ``index``
+    The integer index of the installation type in the list.
+
+``projects``
+  The ``projects`` field is an array of objects describing CMake projects which
+  comprise the CPack project. The values in this field are derived from
+  :variable:`CPACK_INSTALL_CMAKE_PROJECTS`. In most cases, this will be only a
+  single project. The project objects have the following fields:
+
+  ``projectName``
+    The project name passed to :variable:`CPACK_INSTALL_CMAKE_PROJECTS`.
+
+  ``component``
+    The name of the component or component set which comprises the project.
+
+  ``directory``
+    The build directory of the CMake project. This is the directory which
+    contains the ``cmake_install.cmake`` script.
+
+  ``subDirectory``
+    The subdirectory to install the project into inside the CPack package.
+
+``packageName``
+  The package name given in :variable:`CPACK_PACKAGE_NAME`. Only present if
+  this option is set.
+
+``packageVersion``
+  The package version given in :variable:`CPACK_PACKAGE_VERSION`. Only present
+  if this option is set.
+
+``packageDescriptionFile``
+  The package description file given in
+  :variable:`CPACK_PACKAGE_DESCRIPTION_FILE`. Only present if this option is
+  set.
+
+``packageDescriptionSummary``
+  The package description summary given in
+  :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. Only present if this option is
+  set.
+
+``buildConfig``
+  The build configuration given to CPack with the ``-C`` option. Only present
+  if this option is set.
+
+``defaultDirectoryPermissions``
+  The default directory permissions given in
+  :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. Only present if this
+  option is set.
+
+``setDestdir``
+  True if :variable:`CPACK_SET_DESTDIR` is true, false if it is not.
+
+``packagingInstallPrefix``
+  The install prefix given in :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. Only
+  present if :variable:`CPACK_SET_DESTDIR` is true.
+
+``stripFiles``
+  True if :variable:`CPACK_STRIP_FILES` is true, false if it is not.
+
+``warnOnAbsoluteInstallDestination``
+  True if :variable:`CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION` is true, false
+  if it is not.
+
+``errorOnAbsoluteInstallDestination``
+  True if :variable:`CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` is true,
+  false if it is not.
+
+Variables specific to CPack External generator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. variable:: CPACK_EXT_REQUESTED_VERSIONS
+
+  This variable is used to request a specific version of the CPack External
+  generator. It is a list of ``major.minor`` values, separated by semicolons.
+
+  If this variable is set to a non-empty value, the CPack External generator
+  will iterate through each item in the list to search for a version that it
+  knows how to generate. Requested versions should be listed in order of
+  descending preference by the client software, as the first matching version
+  in the list will be generated.
+
+  The generator knows how to generate the version if it has a versioned
+  generator whose major version exactly matches the requested major version,
+  and whose minor version is greater than or equal to the requested minor
+  version. For example, if ``CPACK_EXT_REQUESTED_VERSIONS`` contains 1.0, and
+  the CPack External generator knows how to generate 1.1, it will generate 1.1.
+  If the generator doesn't know how to generate a version in the list, it skips
+  the version and looks at the next one. If it doesn't know how to generate any
+  of the requested versions, an error is thrown.
+
+  If this variable is not set, or is empty, the CPack External generator will
+  generate the highest major and minor version that it knows how to generate.
+
+  If an invalid version is encountered in ``CPACK_EXT_REQUESTED_VERSIONS`` (one
+  that doesn't match ``major.minor``, where ``major`` and ``minor`` are
+  integers), it is ignored.
diff --git a/Help/manual/cpack-generators.7.rst b/Help/manual/cpack-generators.7.rst
index 4614b1c..ade9149 100644
--- a/Help/manual/cpack-generators.7.rst
+++ b/Help/manual/cpack-generators.7.rst
@@ -18,6 +18,7 @@ Generators
    /cpack_gen/cygwin
    /cpack_gen/deb
    /cpack_gen/dmg
+   /cpack_gen/external
    /cpack_gen/freebsd
    /cpack_gen/ifw
    /cpack_gen/nsis