Help: Modernize BUILD_SHARED_LIBS documentation

Previously the documentation used long-outdated terminology from
CMake's early days.

Issue: #25699

1 files changed, 30 insertions, 6 deletions

diff --git a/Help/variable/BUILD_SHARED_LIBS.rst b/Help/variable/BUILD_SHARED_LIBS.rst
index 53087b2..dbb08f7 100644
--- a/Help/variable/BUILD_SHARED_LIBS.rst
+++ b/Help/variable/BUILD_SHARED_LIBS.rst
@@ -1,10 +1,34 @@
 BUILD_SHARED_LIBS
 -----------------
 
-Global flag to cause :command:`add_library` to create shared libraries if on.
+Tell :command:`add_library` to default to ``SHARED`` libraries,
+instead of ``STATIC`` libraries, when called with no explicit library type.
 
-If present and true, this will cause all libraries to be built shared
-unless the library was explicitly added as a static library.  This
-variable is often added to projects as an :command:`option` so that each user
-of a project can decide if they want to build the project using shared or
-static libraries.
+Calls to :command:`add_library` without any explicit library type check
+the current ``BUILD_SHARED_LIBS`` variable value.  If it is true, then the
+default library type is ``SHARED``.  Otherwise, the default is ``STATIC``.
+
+For example, the code:
+
+.. code-block:: cmake
+
+  add_library(example ${sources})
+
+behaves as if written
+
+.. code-block:: cmake
+
+  if(BUILD_SHARED_LIBS)
+    add_library(example SHARED ${sources})
+  else()
+    add_library(example STATIC ${sources})
+  endif()
+
+CMake does not define ``BUILD_SHARED_LIBS`` by default, but projects
+often create a cache entry for it using the :command:`option` command:
+
+.. code-block:: cmake
+
+  option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
+
+This provides a switch that users can control, e.g., with :option:`cmake -D`.