9 files changed, 58 insertions, 1 deletions

diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst
index 31e6ec0..1eb50f7 100644
--- a/Help/command/find_library.rst
+++ b/Help/command/find_library.rst
@@ -49,6 +49,13 @@ path to the framework ``<fullPath>/A.framework``.  When a full path to a
 framework is used as a library, CMake will use a ``-framework A``, and a
 ``-F<fullPath>`` to link the framework to the target.
 
+If the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global property is set
+all search paths will be tested as normal, with ``32/`` appended, and
+with all matches of ``lib/`` replaced with ``lib32/``.  This property is
+automatically set for the platforms that are known to need it if at
+least one of the languages supported by the :command:`project` command
+is enabled.
+
 If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set
 all search paths will be tested as normal, with ``64/`` appended, and
 with all matches of ``lib/`` replaced with ``lib64/``.  This property is
diff --git a/Help/command/set.rst b/Help/command/set.rst
index d04b880..b24ebef 100644
--- a/Help/command/set.rst
+++ b/Help/command/set.rst
@@ -25,7 +25,9 @@ If the ``PARENT_SCOPE`` option is given the variable will be set in
 the scope above the current scope.  Each new directory or function
 creates a new scope.  This command will set the value of a variable
 into the parent directory or calling function (whichever is applicable
-to the case at hand).
+to the case at hand). The previous state of the variable's value stays the
+same in the current scope (e.g., if it was undefined before, it is still
+undefined and if it had a value, it is still that value).
 
 Set Cache Entry
 ^^^^^^^^^^^^^^^
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 1c64d63..f082518 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -24,6 +24,7 @@ Properties of Global Scope
    /prop_gbl/DISABLED_FEATURES
    /prop_gbl/ENABLED_FEATURES
    /prop_gbl/ENABLED_LANGUAGES
+   /prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS
    /prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS
    /prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING
    /prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE
@@ -217,6 +218,7 @@ Properties on Targets
    /prop_tgt/LINK_LIBRARIES
    /prop_tgt/LINK_SEARCH_END_STATIC
    /prop_tgt/LINK_SEARCH_START_STATIC
+   /prop_tgt/LINK_WHAT_YOU_USE
    /prop_tgt/LOCATION_CONFIG
    /prop_tgt/LOCATION
    /prop_tgt/MACOSX_BUNDLE_INFO_PLIST
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 85b8eae..36d00dc 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -275,6 +275,7 @@ Variables that Control the Build
    /variable/CMAKE_LINK_INTERFACE_LIBRARIES
    /variable/CMAKE_LINK_LIBRARY_FILE_FLAG
    /variable/CMAKE_LINK_LIBRARY_FLAG
+   /variable/CMAKE_LINK_WHAT_YOU_USE
    /variable/CMAKE_MACOSX_BUNDLE
    /variable/CMAKE_MACOSX_RPATH
    /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG
diff --git a/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst
new file mode 100644
index 0000000..ce18b65
--- /dev/null
+++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst
@@ -0,0 +1,10 @@
+FIND_LIBRARY_USE_LIB32_PATHS
+----------------------------
+
+Whether the :command:`find_library` command should automatically search
+``lib32`` directories.
+
+``FIND_LIBRARY_USE_LIB32_PATHS`` is a boolean specifying whether the
+:command:`find_library` command should automatically search the ``lib32``
+variant of directories called ``lib`` in the search path when building 32-bit
+binaries.
diff --git a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst
new file mode 100644
index 0000000..32d6edb
--- /dev/null
+++ b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst
@@ -0,0 +1,15 @@
+LINK_WHAT_YOU_USE
+---------------------------
+
+This is a boolean option that when set to ``TRUE`` will automatically run
+``ldd -r -u`` on the target after it is linked. In addition, the linker flag
+``-Wl,--no-as-needed`` will be passed to the target with the link command so
+that all libraries specified on the command line will be linked into the
+target. This will result in the link producing a list of libraries that
+provide no symbols used by this target but are being linked to it.
+This is only applicable to executable and shared library targets and
+will only work when ld and ldd accept the flags used.
+
+This property is initialized by the value of
+the :variable:`CMAKE_LINK_WHAT_YOU_USE` variable if it is set
+when a target is created.
diff --git a/Help/release/dev/find-lib32.rst b/Help/release/dev/find-lib32.rst
new file mode 100644
index 0000000..00818dc
--- /dev/null
+++ b/Help/release/dev/find-lib32.rst
@@ -0,0 +1,7 @@
+find-lib32
+----------
+
+* The :command:`find_library` and :command:`find_package` commands learned
+  to search in ``lib32/`` directories when the build targets a 32-bit
+  architecture.  See the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global
+  property.
diff --git a/Help/release/dev/link_what_you_use.rst b/Help/release/dev/link_what_you_use.rst
new file mode 100644
index 0000000..8d1e598
--- /dev/null
+++ b/Help/release/dev/link_what_you_use.rst
@@ -0,0 +1,7 @@
+link_what_you_use
+-----------------
+
+* A :prop_tgt:`LINK_WHAT_YOU_USE` target property and supporting
+  :variable:`CMAKE_LINK_WHAT_YOU_USE` variable were introduced
+  to detect (on UNIX) shared libraries that are linked but not
+  needed by running ``ldd -r -u``.
diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst
new file mode 100644
index 0000000..90c4d3f
--- /dev/null
+++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst
@@ -0,0 +1,6 @@
+CMAKE_LINK_WHAT_YOU_USE
+---------------------------------
+
+Default value for :prop_tgt:`LINK_WHAT_YOU_USE` target property.
+This variable is used to initialize the property on each target as it is
+created.