Merge topic 'doc-BUILD_SHARED_LIBS' into release-3.29

01e33df83f Help: Modernize BUILD_SHARED_LIBS documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !9278

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`.