From 01e33df83fcd4b7ee1385086612cba4199b19f1f Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 21 Feb 2024 09:19:35 -0500 Subject: Help: Modernize BUILD_SHARED_LIBS documentation Previously the documentation used long-outdated terminology from CMake's early days. Issue: #25699 --- Help/variable/BUILD_SHARED_LIBS.rst | 36 ++++++++++++++++++++++++++++++------ 1 file 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`. -- cgit v0.12