Changes between Version 1 and Version 2 of CMakeModularizeLibrary

Timestamp:

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

Author:

Douglas Gregor

Comment:

Partially describe how to restructure the include directory for a modular library.

CMakeModularizeLibrary

@@ -1 +1 @@
 = Modularizing a Library with CMake =
 
-Boost's CMake-based build system supports the notion of "modular" libraries, which are libraries that are contained entirely within a single directory structure. 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. 
+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. 
 
+== Layout of a modular library ==
 
+A modular library has a similar layout to non-modular libraries. The main difference is in the handling of include files, which are stored within the library's directory in ```libs/libname/include``` rather than in the main "boost" include directory. A modular library  will typically have the following subdirectories:
 
+{{{
+libs/libname - Main library directory
+  include/   - Library headers. Since most Boost headers go into boost/, the actual library headers will be in the subdirectory include/boost (or its subdirectoiries)
+  src/       - Source files for compiled library binaries (if any)
+  test/      - Regression tests
+  example/   - Example programs, libraries, and applications
+  doc/       - Documentation
+}}}
+
+Throughout this document, we will use the Filesystem library as an example of a modular library. Please refer to the contents of ```libs/filesystem``` to see a fully-working modular library's description.
+
+== Restructuring the include directory ==
+
+For most Boost libraries, the only changes needed to the directory structure is to introduce the include directory. To do so, create an empty directories ```include``` and then ```include/boost``` in ```libs/libname```. Then, add these two new directories to Subversion. If you're using the command-line Subversion, you can do this with the following command run from ```libs/libname```:
+
+{{{
+svn add include
+}}}
+
+Next, we need to identify each of the include files that are part of this library (but *not* part of libraries that it depends on) and move each of these libraries from the main Boost include directory into our library-specific include directory. We handle library-specific subdirectories of the Boost include directories (e.g., ```boost/filesystem```) slightly differently from individual files (e.g., ```boost/shared_ptr.hpp```):
+
+  * *Library-specific include directories* are handled by [http://svnbook.red-bean.com/en/1.1/ch07s04.html Subversion externals]. To move the directory ```boost/filesystem```, for example, one should first delete ```boost/filesystem``` entirely from the main Boost include directory. With the command-line Subversion, this can be done by changing into the top-level ```boost``` include directory (e.g., ```$BOOST/boost```) and running
+{{{
+svn rm filesystem
+}}}
+Next, change into the appropriate include directory within the library-specific directory, e.g., ```libs/filesystem/include/boost```. Add a new Subversion ```svn:external``` property to this directory that references the corresponding include directory from the main Boost directory tree. For example, we want our ```filesystem``` directory to point at ```branches/release/boost/filesystem```. This way, our modularized version of the library automatically picks up fixes from the main release branch.
+