|
| 1 | += Organization Requirements |
| 2 | + |
| 3 | +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 must adhere to this directory and file structure: |
| 4 | + |
| 5 | +== Boost Standard Library Organization |
| 6 | + |
| 7 | +[cols="1,5,2",options="header"] |
| 8 | +|=== |
| 9 | +|Sub-directory or file |Contents |Required |
| 10 | +|*build* |Library build files such as a Jamfile, IDE projects, Makefiles, Cmake files, etc. |Required if the library has sources to build. |
| 11 | +|*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. |
| 12 | +|*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. |
| 13 | +|*doc/html* |Documentation (HTML) files. |Required for all libraries with pregenerated documentation. And generated documentation must be generated here. |
| 14 | +|*example* |Sample program files. |Required if library has sample files. Which is highly recommended. |
| 15 | +|*index.html* |Redirection to HTML documentation. See "Redirection" for a template for this file. |Required for all libraries. |
| 16 | +|*include/boost/library* |Header files for the library. |Required for all libraries. |
| 17 | +|*meta* |Meta-data about the library. |Required for all libraries. |
| 18 | +|*meta/libraries.json* |A JSON file containing information about the library used to generate website and documentation for the Boost C++ Libraries collection. |Required for all libraries. |
| 19 | +|*meta/explicit-failures-markup.xml* |XML file describing expected test failures, used to generate the test report. |Optional |
| 20 | +|*src* |Source files which must be compiled to build the library. |Required if the library has source files to build. |
| 21 | +|*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. |
| 22 | +|*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. |
| 23 | +|=== |
| 24 | + |
| 25 | +== Integration |
| 26 | + |
| 27 | +Once 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: |
| 28 | + |
| 29 | +=== Building Sources |
| 30 | + |
| 31 | +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 target(s), and register the target(s) for installation. For example: |
| 32 | + |
| 33 | +[source,bash] |
| 34 | +---- |
| 35 | +project boost/my_lib ; |
| 36 | +
|
| 37 | +lib boost_my_lib : a.cpp ; |
| 38 | +
|
| 39 | +boost-install boost_my_lib ; |
| 40 | +---- |
| 41 | + |
| 42 | +=== Testing |
| 43 | + |
| 44 | +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.) |
| 45 | + |
| 46 | +An example test/Jamfile is given below: |
| 47 | +[source,bash] |
| 48 | +---- |
| 49 | +import testing ; |
| 50 | +
|
| 51 | +run default_constructor.cpp ; |
| 52 | +run copy_constructor.cpp ; |
| 53 | +compile nested_value_type.cpp ; |
| 54 | +compile-fail invalid_conversion_1.cpp ; |
| 55 | +---- |
| 56 | + |
| 57 | +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. |
| 58 | + |
| 59 | +If the library requires a level of C++ conformance that precludes certain compilers or configurations from working, it's possible (and recommended) to declare these requirements in the test Jamfile so that the tests aren't run, to conserve test resources, as given in the example below: |
| 60 | + |
| 61 | +[source,bash] |
| 62 | +---- |
| 63 | +import testing ; |
| 64 | +import ../../config/checks/config : requires ; |
| 65 | +
|
| 66 | +project : requirements [ requires cxx11_variadic_templates cxx11_template_aliases ] ; |
| 67 | +
|
| 68 | +run cpp11_test.cpp ; |
| 69 | +---- |
| 70 | + |
| 71 | +For more information, see the documentation of Boost.Config. |
| 72 | + |
| 73 | +=== Building Documentation |
| 74 | + |
| 75 | +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: |
| 76 | + |
| 77 | +Define a boostdoc target. This target should likely be an alias that looks roughly like: |
| 78 | + |
| 79 | +[source,bash] |
| 80 | +---- |
| 81 | +alias boostdoc : my_boostbook_target |
| 82 | + : : : <implicit-dependency>my_boostbook_target ; |
| 83 | +---- |
| 84 | + |
| 85 | +But if your project doesn't integrate into the global documentation book you can use an empty alias like: |
| 86 | + |
| 87 | +[source,bash] |
| 88 | +---- |
| 89 | +alias boostdoc ; |
| 90 | +---- |
| 91 | + |
| 92 | +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. |
0 commit comments