Organization Requirements

The quality of the Boost libraries is not just about the APIs and code design, but also about presenting a consistent view to users of the libraries as a whole. Upon acceptance libraries should adhere to this directory and file structure.

Boost Repository Library Organization

Referring to accepted libraries is a great way to educate yourself on the library directory structure. In the examples given below, Boost.Atomic, Boost.Json, and Boost.Serialization are examples of libraries that requires building, and Boost.Asio, Boost.Geometry, and Boost.Hana are examples of libraries that are header-only.

Sub-Directory

The following directories should appear, along with others specific to the library, as top-level sub-directories for the library.

Sub-Directory Contents Required Examples

build

Library build files such as a Jamfile, IDE projects, Makefiles, Cmake files, etc.

Required if the library has sources to build.

config

Files used for build-time configuration checks. This directory may contain source files and build system scripts to be used when building the library, tests or examples to check if the target system satisfies certain conditions. For example, a check may test if the compiler implements a certain feature, or if the target system supports a certain API.

Optional.

doc

Sources to build with and built documentation for the library. If the library needs to build documentation from non-HTML files this location must be build-able with Boost Build.

Required for all libraries.

doc/html

Documentation (HTML) files.

Required for all libraries with pregenerated documentation. And generated documentation must be generated here.

example

Sample program files.

Required if library has sample files. Which is highly recommended.

include/boost/<library-name>

Header files for the library.

Required for all libraries.

meta

Meta-data about the library.

Required for all libraries.

src

Source files which must be compiled to build the library.

Required if the library has source files to build.

test

Regression or other test programs or scripts. This is the only location considered for automated testing. If you have additional locations that need to be part of automated testing it is required that this location refer to the additional test locations.

Required for all libraries.

test/cmake_test

CMake sub-folders can be named for the type of Continuous Integration tests they contain (cmake_install_test for example). The structure of your tests should match that in boostorg/boost-ci, and refer to the Boost.CI Readme for process details.

Not required, though most new libraries include these tests.

tools

Tools used, or offered, by the library. The structure within this is up to the library, but it’s recommended to use similar structure as a regular Boost library or tool.

Required for libraries that have run-able tools.

To reference the existing master repo, refer to boost/libs/.

For a list of libraries that require building, refer to Required Compiled Binaries.

Files

There are some individual files that are also required, or are optional and recognized by the build system.

File Contents Required Examples

build.jam

Top level jamfile.

Required if the library has sources to build.

CMakeLists.txt

Refer to CMake for Boost Developers.

Required for all libraries.

index.html

Redirection to HTML documentation. Refer to Design Guide/Redirection for a template for this file.

Required for all libraries.

meta/libraries.json

A JSON file containing information about the library, which is used to generate website and documentation for the Boost Libraries collection. Refer to Library Metadata.

Required for all libraries.

meta/explicit-failures-markup.xml

XML file describing expected test failures, used to generate the test report.

Optional

Integration

After a library is accepted as part of the Boost Libraries it is required that it integrate properly into the development, testing, documentation, and release processes. This integration increases the eventual quality of all the libraries and is integral to the expected quality of the whole of the Boost C++ Libraries from users. In addition to the organization requirements above the following integration is required:

Building Sources

The library needs to provide a Boost Build project that the user, and the top level Boost project, can use to build the library if it has sources to build. The Jamfile for the source build needs to minimally declare the project, the library targets, and register the targets for installation. For example:

project boost/my_lib ;

lib boost_my_lib : a.cpp ;

boost-install boost_my_lib ;

Testing

The library needs to provide a Boost Build project that the user, and the root Boost test script, can use to build and run the tests for the library. The testing build project must reside in the project-root/test directory and must be build-able from this or another directory, for example, b2 libs/library/test from the Boost root must work.

An example test/Jamfile is given below:

import testing ;

run default_constructor.cpp ;
run copy_constructor.cpp ;
compile nested_value_type.cpp ;
compile-fail invalid_conversion_1.cpp ;
WARNING

This is the only location considered for testing by the top level testing script. If you want to test additional locations you must declare such that they are built as dependencies or by using build-project.

If the library requires a level of C++ conformance that precludes certain compilers or configurations from working, it’s recommended to declare these requirements in the test Jamfile. This ensures that unnecessary tests aren’t run, to conserve test resources, as given in the example below:

import testing ;
import ../../config/checks/config : requires ;

project : requirements [ requires cxx11_variadic_templates cxx11_template_aliases ] ;

run cpp11_test.cpp ;

For more information, see the documentation for Boost.Config.

Building Documentation

The library needs to provide a Boost Build project for building the documentation for the library. The project-root/doc project is the only location referred to by the top level documentation build scripts and the release building scripts. The documentation build project must have the following two features:

Define a boostrelease target. This target should likely be an alias that looks roughly like:

alias boostrelease  : my_boostbook_target
    : : : <implicit-dependency>my_boostbook_target ;

But if your project doesn’t integrate into the global documentation book you can use an empty alias like:

alias boostrelease  ;

The project must default to building standalone documentation if it has any. The release scripts build this default so as to guarantee all projects have up to date documentation.

Note

Integrated documentation, using the boostdoc target (instead of the boostrelease target) is now considered legacy, and should be avoided for new library documentation.

See Also

Edit this Page