export: Disable PACKAGE mode user package registry by default

The user package registry populated by the `export()` command causes
side effects outside the build and source directories.  Such effects
should be opt-in rather than op-out.  Introduce a policy to change
default behavior of `export(PACKAGE)` to do nothing.

8 files changed, 76 insertions, 10 deletions

diff --git a/Help/command/export.rst b/Help/command/export.rst
index b255ee8..ffd60e1 100644
--- a/Help/command/export.rst
+++ b/Help/command/export.rst
@@ -62,8 +62,13 @@ registry that this command creates works only in conjunction with a
 package configuration file (``<PackageName>Config.cmake``) that works with the
 build tree. In some cases, for example for packaging and for system
 wide installations, it is not desirable to write the user package
-registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable
-is enabled, the ``export(PACKAGE)`` command will do nothing.
+registry.
+
+By default the ``export(PACKAGE)`` command does nothing (see policy
+:policy:`CMP0090`) because populating the user package registry has effects
+outside the source and build trees.  Set the
+:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories to
+the CMake user package registry.
 
 .. code-block:: cmake
 
diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst
index 876ca84..bbe742e 100644
--- a/Help/manual/cmake-packages.7.rst
+++ b/Help/manual/cmake-packages.7.rst
@@ -647,12 +647,17 @@ Disabling the Package Registry
 In some cases using the Package Registries is not desirable. CMake
 allows one to disable them using the following variables:
 
- * :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` disables the
-   :command:`export(PACKAGE)` command.
- * :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the
-   User Package Registry in all the :command:`find_package` calls.
- * :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables
-   the System Package Registry in all the :command:`find_package` calls.
+* The :command:`export(PACKAGE)` command does not populate the user
+  package registry when :policy:`CMP0090` is set to ``NEW`` unless the
+  :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable explicitly enables it.
+  When :policy:`CMP0090` is *not* set to ``NEW`` then
+  :command:`export(PACKAGE)` populates the user package registry unless
+  the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable explicitly
+  disables it.
+* :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the
+  User Package Registry in all the :command:`find_package` calls.
+* :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables
+  the System Package Registry in all the :command:`find_package` calls.
 
 Package Registry Example
 ------------------------
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 9470d6c..e89ea3da 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.15
 .. toctree::
    :maxdepth: 1
 
+   CMP0090: export(PACKAGE) does not populate package registry by default. </policy/CMP0090>
    CMP0089: Compiler id for IBM Clang-based XL compilers is now XLClang. </policy/CMP0089>
 
 Policies Introduced by CMake 3.14
@@ -73,6 +74,7 @@ Policies Introduced by CMake 3.14
    CMP0083: Add PIE options when linking executable. </policy/CMP0083>
    CMP0082: Install rules from add_subdirectory() are interleaved with those in caller. </policy/CMP0082>
 
+
 Policies Introduced by CMake 3.13
 =================================
 
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 83c88a5..4c73933 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -159,6 +159,7 @@ Variables that Change Behavior
    /variable/CMAKE_ERROR_DEPRECATED
    /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
    /variable/CMAKE_EXPORT_COMPILE_COMMANDS
+   /variable/CMAKE_EXPORT_PACKAGE_REGISTRY
    /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY
    /variable/CMAKE_FIND_APPBUNDLE
    /variable/CMAKE_FIND_FRAMEWORK
diff --git a/Help/policy/CMP0090.rst b/Help/policy/CMP0090.rst
new file mode 100644
index 0000000..720c17c
--- /dev/null
+++ b/Help/policy/CMP0090.rst
@@ -0,0 +1,27 @@
+CMP0090
+-------
+
+:command:`export(PACKAGE)` does not populate package registry by default.
+
+In CMake 3.14 and below the :command:`export(PACKAGE)` command populated the
+user package registry by default and users needed to set the
+:variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` to disable it, e.g. in automated
+build and packaging environments.  Since the user package registry is stored
+outside the build tree, this side effect should not be enabled by default.
+Therefore CMake 3.15 and above prefer that :command:`export(PACKAGE)` does
+nothing unless an explicit :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable
+is set to enable it.  This policy provides compatibility with projects that
+have not been updated.
+
+The ``OLD`` behavior for this policy is for :command:`export(PACKAGE)` command
+to populate the user package registry unless
+:variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` is enabled.
+The ``NEW`` behavior is for :command:`export(PACKAGE)` command to do nothing
+unless the :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` is enabled.
+
+This policy was introduced in CMake version 3.15.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike most policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/export-package-default-off.rst b/Help/release/dev/export-package-default-off.rst
new file mode 100644
index 0000000..0868c82
--- /dev/null
+++ b/Help/release/dev/export-package-default-off.rst
@@ -0,0 +1,6 @@
+export-package-default-off
+--------------------------
+
+* The :command:`export(PACKAGE)` command now does nothing unless
+  enabled via :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY`.
+  See policy :policy:`CMP0090`.
diff --git a/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst
index ee109ba..768ed64 100644
--- a/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst
+++ b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst
@@ -1,11 +1,16 @@
 CMAKE_EXPORT_NO_PACKAGE_REGISTRY
 --------------------------------
 
-Disable the :command:`export(PACKAGE)` command.
+Disable the :command:`export(PACKAGE)` command when :policy:`CMP0090`
+is not set to ``NEW``.
 
 In some cases, for example for packaging and for system wide
 installations, it is not desirable to write the user package registry.
-If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable is enabled,
+If the ``CMAKE_EXPORT_NO_PACKAGE_REGISTRY`` variable is enabled,
 the :command:`export(PACKAGE)` command will do nothing.
 
+If :policy:`CMP0090` is set to ``NEW`` this variable does nothing, and the
+:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable controls the behavior
+instead.
+
 See also :ref:`Disabling the Package Registry`.
diff --git a/Help/variable/CMAKE_EXPORT_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_EXPORT_PACKAGE_REGISTRY.rst
new file mode 100644
index 0000000..3476a19
--- /dev/null
+++ b/Help/variable/CMAKE_EXPORT_PACKAGE_REGISTRY.rst
@@ -0,0 +1,15 @@
+CMAKE_EXPORT_PACKAGE_REGISTRY
+-----------------------------
+
+Enables the :command:`export(PACKAGE)` command when :policy:`CMP0090`
+is set to ``NEW``.
+
+The :command:`export(PACKAGE)` command does nothing by default.  In some cases
+it is desirable to write to the user package registry, so the
+``CMAKE_EXPORT_PACKAGE_REGISTRY`` variable may be set to enable it.
+
+If :policy:`CMP0090` is *not* set to ``NEW`` this variable does nothing, and
+the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable controls the behavior
+instead.
+
+See also :ref:`Disabling the Package Registry`.