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

On Monday 06 October 2014 16:29:07 Mathias Gaunard wrote:

On 06/10/14 15:48, Adam Wulkiewicz wrote:

...

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

This is what I was looking for.

Unfortunately, it seems it's only usable to divide tests, examples and documentation, and not headers, sources or usage requirements.

[snip]

What I would want, however, is

BOOST_ROOT/libs +-library_name +-sublib_name1

| +-include | | | +-boost | | | | | +-sublib_name1 | | | | | | | +-... | | +-test | | | +-Jamfile.v2 | | +-example | +-build | | | +-Jamfile.v2 | | +-src

+-sublib_name2

| +-include | | | +-boost | | | | | +-sublib_name2 | | | | | | | +-... | | +-test | | | +-Jamfile.v2 | | +-example | +-build | | | +-Jamfile.v2 | | +-src

+-(file)sublibs

AFAIK, a sublib can contain everything - headers, sources, docs and tests (see libs/numeric for example). I didn't try the sources and build/Jamfile.v2 in a sublib though.

...

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

That's a bit tedious. Shouldn't this be automatically computed?

It'd be great if it did but currently it's not.

On Monday 06 October 2014 14:39:14 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?

Currently, Boost is distributed as a monolithic source archive. Testers also check out all libraries before running tests. So with the current state of things it basically doesn't matter - you can do it in whatever way is more convenient for you. You may consider the following points though: - If the library consists of multiple git submodules, it takes longer to checkout. I've also seen GitHub timeouts when checking out some libraries (I think, GitHub will sometimes timeout ssh authentication, which is done for each submodule). - Multiple git sumbodules means separate git repositories for different parts of your library. This implies separate histories and inability of making synchronized changes to different repositories. Synchronized library releases can also be problematic. - AFAIK, there are no nested git submodules (i.e. submodules within submodules) in Boost. It's quite probable that they are not supported, and personally I'd prefer if we didn't nest git submodules. - A single git repository means that all your library sources will always be checked out together. This may be ok or not depending on how heavy your library is. However, it doesn't mean that all its components must be built together or that it should be considered as a single indivisible library. There is a notion of Boost sublibraries (which basically means multiple Boost libraries in the same git repo) which you could use. I'll add that some people in this list are generating dependency reports between different libraries from time to time, and these reports are taking into account Boost sublibraries (i.e. you would see sublibs in the report and not git submodules). I've also started working on a prototype of a package management tool for Boost that will also take into account sublibs. There's no guarantee that sublibs will be the ultimate unit of distribution of the modular Boost though - it's all at a rather early stage.

Mathias Gaunard wrote:

...

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?

libs/library/ module1/ include/ src/ test/ module2/ include/ src/ test/ ... sublibs

See libs/numeric as an example of this structure.