Changes between Version 4 and Version 5 of CMakeModularizeLibrary

Timestamp:

May 23, 2008, 3:35:33 PM (14 years ago)

Author:

Douglas Gregor

Comment:

Finished first draft of library-modularization HOWTO

CMakeModularizeLibrary

@@ -2 +2 @@
 
 Boost's CMake-based build system supports the notion of "modular" libraries, which are libraries that are contained entirely within a single directory structure. Since modular libraries are self-contained, it is easier to bring in libraries of different versions and select specific subsets of libraries. Additionally, modular libraries explicitly declare their dependencies on other libraries (or "modules"), making it possible to build and install coherent subsets of Boost. For example, the [wiki:CMakeBinaryInstaller binary installer] for Windows allows one to turn on or off installation of each modular library. 
+
+Eventually, we hope that most of Boost's libraries will be modular, to make it easier for users to install the subset of Boost that they are interested in. Many "core" libraries, on which most users and many other libraries depend, may remain in the core Boost distribution and will not be modularized. Even then, modularizing Boost is an evolutionary process, and it is best to work on modularizing libraries on which no other libraries depend (first) and then libraries on which other modularized libraries depend, moving from the more peripheral libraries (that no other libraries depend on) toward the core libraries.
 
 == Layout of a modular library ==
@@ -66 +68 @@
 If the library you're modularizing does not have `DESCRIPTION`, `AUTHORS`, or `MAINTAINERS` arguments, please add them! Short library descriptions are available at http://www.boost.org/doc/ along with author information; additional maintainer information can be found in http://svn.boost.org/svn/boost/trunk/libs/maintainers.txt.
 
+= Library dependencies =
 
+Each modular library must declare the libraries on which it depends. This declaration is provided by the file `module.cmake` within the library's directory, and uses the `boost_modular` command to explicitly declare dependencies via its `DEPENDS` argument. The contents on the Filesystem library's `libs/filesystem/module.cmake` follow:
+
+{{{
+boost_module(Filesystem DEPENDS system)
+}}}
+
+The first argument to `boost_module` is the name of the library we're description. The arguments following `DEPENDS` (there may be more than one!) are the names of the libraries on which this library depends. Those libraries may or may not be modular yet: it does not matter. Thus, the Filesystem library depends on the System library. If the System library were not available for some reason (say, the user forgot to include it in the subset of Boost she downloaded), the Filesystem library would not attempt to build.
+
+= Testing the modular library =
+
+Once a library has been modularized, it is important to build the library and all of the regression tests, including the regression tests for other libraries (that might depend on the modularized library). Follow the instructors for [wiki:CMakeTesting building and running the regression tests]. Most of the failures that will crop up from this exercise will come in the form of "include file not found" messages due to missing dependency information. When this happens, add the appropriate dependencies to `module.cmake` and try again. The result is well worth it!