Re: [boost] Submodules of Boost libraries

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: 
https://github.com/boostorg). There is also a "main" module containing 
all other submodules (https://github.com/boostorg/boost). 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 
page: http://www.boost.org/development/tests/develop/developer/summary.html

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_ROOT/libs
+-library_name
   +-include
   | +-boost
   | +-library_name
   |     +-...
+-sublib_name1
   |+-test
   | | +-Jamfile.v2
   |+-example
+-sublib_name2
   | +-test
   | | +-Jamfile.v2
   | +-example
+-(file)sublibs

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 
library.

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.

Regards,
Adam