Boost logo

Boost :

Subject: Re: [boost] Submodules of Boost libraries
From: Adam Wulkiewicz (adam.wulkiewicz_at_[hidden])
Date: 2014-10-06 09:48:26

Mathias Gaunard wrote:
> On 29/09/14 20:48, Robert Ramey wrote:
>> Mathias Gaunard-2 wrote
>>> Hi folks,
>>> I'd like to ready my library for inclusion into Boost.
>>> My library is made of several modules, and I'd like to keep that into
>>> Boost.
>>> How does Boost handles multiple submodules within a library submodule?
>> I'm getting a little confused as to what we mean by module, library,
>> sub module, repository etc.
> Boost is a set of libraries, which are managed by git submodules.
> My own library is split in several functional modules, primarily
> because some of them have special dependencies and are optional.
> How should this be presented for inclusion into Boost?

GIT submodule/module
A GIT sub-repository, all Boost libraries are maintained as submodules,
AFAIU for simplicity they're called "modules" (here's the list: There is also a "main" module containing
all other submodules ( It should be
cloned with --recursive option to clone all of the submodules, etc.
In previously used SVN repository all libraries were just stored as
separate directories in one global repository, GIT allows to handle them
more or less separatelyas submodules.

Boost sublibrary/sublib
Correct me if I'm wrong. To allow dividing libraries into smaller
functional parts (SVN) "sublibs" system was introduced. With it it's
possible to keep the tests and examples separated for each part. In the
library there must be a correct directories structure and there must
exist a file called "sublibs", see (geometry, numeric, functional,
etc.). Then you can see separated sublibs e.g. on the regression summary

As for your question, it depends how much splitting your library
requires, but I'm assuming that splitting it on a "sublibs"level would
be enough. Therefore the directories structure of your library should
look like this:

   | +-boost
   | +-library_name
   | +-...
   | | +-Jamfile.v2
   | +-test
   | | +-Jamfile.v2
   | +-example

Each sublibtest dir should be added to the BOOST_ROOT/status/Jamfile.v2
to run the tests for all submodules.

It's on your own how to structure the sourcecode in
BOOST_ROOT/libs/library_name/include/boost/library_name. Each sublibrary
should probably have separate directory and it could be possible to
include the whole library or separate sublibs. But that depends on the

There must also be one "doc" directory with a documentation of a library
but I think it should be possible to split it into parts as well and
just include them from the library docs. If not it could be divided the
same way like headers.


Boost list run by bdawes at, gregod at, cpdaniel at, john at