Help: Add new section for CPack generators

The documentation for CPack generators previously lived in their
respective internal CMake modules. This setup was misleading,
because it implied that you should include the modules in your own
code, which is not the case. Moving the documentation into a
separate section does a better job of hiding the internal modules,
which are just an implementation detail. The generator documentation
has also been modified to remove any references to the module name.

The CPackIFW module is a special exception: since it has user-facing
macros, the documentation for these macros has been kept in the module
page, while all other documentation related to the IFW generator has
been moved into the new section.

To make it easier to find the new documentation, the old help pages
for the CPack*.cmake modules have not been deleted, but have been
replaced with a link to their respective help page in the new
documentation section.

1 files changed, 138 insertions, 0 deletions

diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst
new file mode 100644
index 0000000..2419057
--- /dev/null
+++ b/Help/cpack_gen/freebsd.rst
@@ -0,0 +1,138 @@
+CPack FreeBSD Generator
+-----------------------
+
+The built in (binary) CPack FreeBSD (pkg) generator (Unix only)
+
+Variables specific to CPack FreeBSD (pkg) generator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The CPack FreeBSD generator may be used to create pkg(8) packages -- these may
+be used on FreeBSD, DragonflyBSD, NetBSD, OpenBSD, but also on Linux or OSX,
+depending on the installed package-management tools -- using :module:`CPack`.
+
+The CPack FreeBSD generator is a :module:`CPack` generator and uses the
+``CPACK_XXX`` variables used by :module:`CPack`. It tries to re-use packaging
+information that may already be specified for Debian packages for the
+:cpack_gen:`CPack Deb Generator`. It also tries to re-use RPM packaging
+information when Debian does not specify.
+
+The CPack FreeBSD generator should work on any host with libpkg installed. The
+packages it produces are specific to the host architecture and ABI.
+
+The CPack FreeBSD generator sets package-metadata through
+:code:`CPACK_FREEBSD_XXX` variables. The CPack FreeBSD generator, unlike the
+CPack Deb generator, does not specially support componentized packages; a
+single package is created from all the software artifacts created through
+CMake.
+
+All of the variables can be set specifically for FreeBSD packaging in
+the CPackConfig file or in CMakeLists.txt, but most of them have defaults
+that use general settings (e.g. CMAKE_PROJECT_NAME) or Debian-specific
+variables when those make sense (e.g. the homepage of an upstream project
+is usually unchanged by the flavor of packaging). When there is no Debian
+information to fall back on, but the RPM packaging has it, fall back to
+the RPM information (e.g. package license).
+
+.. variable:: CPACK_FREEBSD_PACKAGE_NAME
+
+  Sets the package name (in the package manifest, but also affects the
+  output filename).
+
+  * Mandatory: YES
+  * Default:
+
+    - :variable:`CPACK_PACKAGE_NAME` (this is always set by CPack itself,
+      based on CMAKE_PROJECT_NAME).
+
+.. variable:: CPACK_FREEBSD_PACKAGE_COMMENT
+
+  Sets the package comment. This is the short description displayed by
+  pkg(8) in standard "pkg info" output.
+
+  * Mandatory: YES
+  * Default:
+
+    - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set
+      by CPack itself, if nothing else sets it explicitly).
+    - :variable:`PROJECT_DESCRIPTION` (this can be set with the DESCRIPTION
+      parameter for :command:`project`).
+
+.. variable:: CPACK_FREEBSD_PACKAGE_DESCRIPTION
+
+  Sets the package description. This is the long description of the package,
+  given by "pkg info" with a specific package as argument.
+
+  * Mandatory: YES
+  * Default:
+
+    - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` (this may be set already
+      for Debian packaging, so we may as well re-use it).
+
+.. variable:: CPACK_FREEBSD_PACKAGE_WWW
+
+  The URL of the web site for this package, preferably (when applicable) the
+  site from which the original source can be obtained and any additional
+  upstream documentation or information may be found.
+
+  * Mandatory: YES
+  * Default:
+
+   - :variable:`CMAKE_PROJECT_HOMEPAGE_URL`, or if that is not set,
+     :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already
+     for Debian packaging, so we may as well re-use it).
+
+.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE
+
+  The license, or licenses, which apply to this software package. This must
+  be one or more license-identifiers that pkg recognizes as acceptable license
+  identifiers (e.g. "GPLv2").
+
+  * Mandatory: YES
+  * Default:
+
+    - :variable:`CPACK_RPM_PACKAGE_LICENSE`
+
+.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE_LOGIC
+
+  This variable is only of importance if there is more than one license.
+  The default is "single", which is only applicable to a single license.
+  Other acceptable values are determined by pkg -- those are "dual" or "multi" --
+  meaning choice (OR) or simultaneous (AND) application of the licenses.
+
+  * Mandatory: NO
+  * Default: single
+
+.. variable:: CPACK_FREEBSD_PACKAGE_MAINTAINER
+
+  The FreeBSD maintainer (e.g. kde@freebsd.org) of this package.
+
+  * Mandatory: YES
+  * Default: none
+
+.. variable:: CPACK_FREEBSD_PACKAGE_ORIGIN
+
+  The origin (ports label) of this package; for packages built by CPack
+  outside of the ports system this is of less importance. The default
+  puts the package somewhere under misc/, as a stopgap.
+
+  * Mandatory: YES
+  * Default: misc/<package name>
+
+.. variable:: CPACK_FREEBSD_PACKAGE_CATEGORIES
+
+  The ports categories where this package lives (if it were to be built
+  from ports). If none is set a single category is determined based on
+  the package origin.
+
+  * Mandatory: YES
+  * Default: derived from ORIGIN
+
+.. variable:: CPACK_FREEBSD_PACKAGE_DEPS
+
+  A list of package origins that should be added as package dependencies.
+  These are in the form <category>/<packagename>, e.g. x11/libkonq.
+  No version information needs to be provided (this is not included
+  in the manifest).
+
+  * Mandatory: NO
+  * Default: empty