Skip to content

usage.md

Latest commit

 

History

History
165 lines (129 loc) · 7.19 KB

usage.md

File metadata and controls

165 lines (129 loc) · 7.19 KB
Raw

boost-module User Guide

1. Dependency Declaration

The package is published on the mcpp package index (namespace ZheFeng7110):

# Default: 49-library closure
[dependencies.ZheFeng7110]
boost = { version = "1.92.0.0.0.0" }

# Pick a few libraries only (default-features = false disables the default set)
[dependencies.ZheFeng7110]
boost = { version = "1.92.0.0.0.0", default-features = false, features = ["optional", "type_traits", "json", "version"] }

# Everything
[dependencies.ZheFeng7110]
boost = { version = "1.92.0.0.0.0", features = ["all"] }

Alternatively, depend on the git repository directly:

[dependencies.ZheFeng7110.boost]
# Mainland China mirror: https://gitcode.com/ZheFeng7/boost-module
git = "https://github.com/ZheFeng7110/boost-module"
tag = "v1.92.0.0.0.0"

Both channels carry the same package; the mcpp package index is the recommended one.

Do not use features = ["all"] with clang: all CMIs total about 2.98GB, exceeding clang's 2^31 source-location limit, which fails with "ran out of source locations"; there is no flag to raise it. If you need everything, import libraries one by one; the same limit has not been verified on the gcc side.

2. Three Consumption Modes

2.1 Module import (116 libraries)

import boost.filesystem;   // single library
import boost;              // umbrella: re-exports exactly the currently active libraries (a legal empty shell when nothing is active)

The API spelling is identical to upstream; free operators are explicitly exported and friend operators work through ADL.

2.2 Pure include-only (20 libraries)

No feature, no module — just #include the upstream headers. This can be mixed with module imports in the same TU (the standard allows it). Macro APIs (BOOST_PP_/BOOST_FOREACH/ BOOST_DESCRIBE_/BOOST_OPENMETHOD/BOOST_SCOPE_EXIT_* etc.) can only ever come from includes — macros are preprocessor-level API and never cross module boundaries.

#include <boost/preprocessor/cat.hpp>   // macro API: include only
#include <boost/foreach.hpp>
import boost.core;                      // modularized libraries import as usual; both coexist

static_assert(BOOST_PP_CAT(1, 2) == 12);
BOOST_FOREACH (int x, vec) { /* ... */ }

List: preprocessor / mpl / fusion / proto / spirit / xpressive / typeof / vmd / phoenix / parameter / metaparse / function_types / tti / local_function / msm / foreach (macro-driven, 16) + exception, describe, openmethod, scope_exit (downgraded, 4).

2.3 Compiled libraries consumed include-only (2 libraries: log, test)

The feature keeps compiling and linking the library TUs, but there is no module interface.

log: --features log + #include <boost/log/...> + link the library TUs.

test (unit_test_framework feature): two consumption forms, which must not be linked together (the framework TUs and the included aggregated implementation have conflicting symbols — pick one):

Form feature include linking
Compiled framework (officially recommended) --features unit_test_framework <boost/test/unit_test.hpp> (+ BOOST_TEST_NO_MAIN + <boost/test/impl/unit_test_main.ipp> to pull in the runner, or supply your own main) framework TUs from the package
Header-only (officially optional) not enabled <boost/test/included/unit_test.hpp> (aggregate header, includes main) none 
// Compiled form (features = ["unit_test_framework"]):
#define BOOST_TEST_MODULE my_suite
#define BOOST_TEST_NO_MAIN
#include <boost/test/unit_test.hpp>
#include <boost/test/impl/unit_test_main.ipp>

BOOST_AUTO_TEST_CASE(t) { BOOST_TEST(1 + 1 == 2); }

int main(int argc, char* argv[]) {
    return boost::unit_test::unit_test_main(&init_unit_test_suite, argc, argv);
}
// Header-only form (feature not enabled):
#define BOOST_TEST_MODULE my_suite
#include <boost/test/included/unit_test.hpp>   // includes main
BOOST_AUTO_TEST_CASE(t) { BOOST_TEST(1 + 1 == 2); }

3. Feature Selection Semantics

  • Each library maps to one feature (generated by scripts/gen_features.py; do not edit by hand), 118 in total = 116 module features + log + unit_test_framework.
  • The default set is the 49-library closure, covering the core surface (19 former core libraries + infrastructure libraries such as config/assert/utility/move + boost.version); everything else is opt-in.
  • Features may declare implies (transitive closure); e.g. --features log pulls in the link dependencies.

4. Version Constants (boost.version)

import boost.version;    // in the default set; import boost; re-exports it automatically
static_assert(boost::BOOST_VERSION == 109200);
static_assert(boost::BOOST_LIB_VERSION[0] == '1');
  • The values come from upstream <boost/version.hpp>, exported in the boost:: namespace as inline constexpr (spelling preserved).
  • The macro form (#if BOOST_VERSION >= 109200) requires the consumer to #include <boost/version.hpp> themselves; within the same TU, the macro definitions and the module spelling are mutually exclusive (the macro expands boost::BOOST_VERSION → boost::109200) — pick one.

5. Consumer Notes

  • You must provide your own std surface (import std; or includes) — operators on boost entity signatures that reference std types are not visible in a pure-import TU (by design).

  • gcc 16.1 has a family of module defects; consumption falls into three modes: ① plain import; ② import + supplemental standard headers (<new>/<typeinfo>); ③ pure include. Per-library verification: see architecture.md §4.

  • Feature-macro profiles (supported customization): BOOST_* feature macros are fixed at build time by default, but a supported subset is exposed as profile features the consumer selects in the dependency declaration with mcpp's generic sugar backend = "<axis>-<impl>" (desugars 1:1 to features = ["backend-<axis>-<impl>"]); activating a feature recompiles the package. Currently supported: backend-log-ssse3 / backend-log-avx2 (x86_64, Boost.Log dump implementations). Combine axes with features = [...]. Conflicting profiles or a wrong architecture are reported by build.mcpp.

    [dependencies.ZheFeng7110.boost]
git = "...", tag = "..."
backend = "log-avx2"     # == features = ["backend-log-avx2"]

    Macros not listed as profiles (including BOOST_FILESYSTEM_VERSION, BOOST_THREAD_VERSION and others that change the exported entity set) still require the include-only escape: #define them yourself and #include <boost/...>, giving up that library's module surface. See architecture.md §3.1.

  • For the trim list (filesystem locked to the v3 API, thread locked to the v2 API (unique_future), stacktrace basic, etc.), see architecture.md §4.1.

  • The M13 external-dependency libraries (context / fiber / coroutine / locale / mpi / python / parameter_python / graph_parallel / compute / mysql / redis) are not supported.

  • See architecture.md §5 for platform support (mingw and real MSVC are not guaranteed).