Merge pull request bemanproject#190 from bretbrownjr/fix-install-option

Polish beman_install_library

Author: bretbrownjr

README.md

@@ -9,5 +9,49 @@ so it does not respect the usual structure of a Beman library repository nor The
 
 ## Description
 
+* `cmake/`: CMake modules and toolchain files used by Beman libraries.
 * `containers/`: Containers used for CI builds and tests in the Beman org.
 * `tools/`: Tools used to manage the infrastructure and the codebase (e.g., linting, formatting, etc.).
+
+## Usage
+
+This repository is intended to be used as a beman-submodule in other Beman repositories. See
+[the Beman Submodule documentation](./tools/beman-submodule/README.md) for details.
+
+
+### CMake Modules
+
+
+#### `beman_install_library`
+
+The CMake modules in this repository are intended to be used by Beman libraries. Use the
+`beman_add_install_library_config()` function to install your library, along with header
+files, any metadata files, and a CMake config file for `find_package()` support.
+
+```cmake
+add_library(beman.something)
+add_library(beman::something ALIAS beman.something)
+
+# ... configure your target as needed ...
+
+find_package(beman-install-library REQUIRED)
+beman_install_library(beman.something)
+```
+
+Note that the target must be created before calling `beman_install_library()`. The module
+also assumes that the target is named using the `beman.something` convention, and it
+uses that assumption to derive the names to match other Beman standards and conventions.
+If your target does not follow that convention, raise an issue or pull request to add
+more configurability to the module.
+
+The module will configure the target to install:
+
+* The library target itself
+* Any public headers associated with the target
+* CMake files for `find_package(beman.something)` support
+
+Some options for the project and target will also be supported:
+
+* `BEMAN_INSTALL_CONFIG_FILE_PACKAGES` - a list of package names (e.g., `beman.something`) for which to install the config file
+  (default: all packages)
+* `<BEMAN_NAME>_INSTALL_CONFIG_FILE_PACKAGE` - a per-project option to enable/disable config file installation (default: `ON` if the project is top-level, `OFF` otherwise). For instance for `beman.something`, the option would be `BEMAN_SOMETHING_INSTALL_CONFIG_FILE_PACKAGE`.

cmake/beman-install-library-config.cmake

@@ -81,11 +81,32 @@ function(beman_install_library name)
     string(TOUPPER "${name}" project_prefix)
     string(REPLACE "." "_" project_prefix "${project_prefix}")
 
-    if(
-        "${name}" IN_LIST BEMAN_INSTALL_CONFIG_FILE_PACKAGES
-        OR "${project_prefix}_INSTALL_CONFIG_FILE_PACKAGE"
+    option(
+        ${project_prefix}_INSTALL_CONFIG_FILE_PACKAGE
+        "Enable building examples. Default: ${PROJECT_IS_TOP_LEVEL}. Values: { ON, OFF }."
+        ${PROJECT_IS_TOP_LEVEL}
     )
-        set(install_config_package ON)
+
+    # By default, install the config package
+    set(install_config_package ON)
+
+    # Turn OFF installation of config package by default if,
+    # in order of precedence:
+    # 1. The specific package variable is set to OFF
+    # 2. The package name is not in the list of packages to install config files
+    if(DEFINED BEMAN_INSTALL_CONFIG_FILE_PACKAGES)
+        if(
+            NOT "${install_component_name}"
+                IN_LIST
+                BEMAN_INSTALL_CONFIG_FILE_PACKAGES
+        )
+            set(install_config_package OFF)
+        endif()
+    endif()
+    if(DEFINED ${project_prefix}_INSTALL_CONFIG_FILE_PACKAGE)
+        set(install_config_package
+            ${${project_prefix}_INSTALL_CONFIG_FILE_PACKAGE}
+        )
     endif()
 
     if(install_config_package)