How woven-by-toyota/arene-base works
1. arene-base is a Bazel-managed C++14 library stack, not an application. The repository is organized as many small Bazel targets under arene/base/... plus a separate stdlib/... implementation layer, with tests, docs, and build tooling around them.
2. The core product boundary is arene/base: a collection of low-level reusable facilities for safety-critical C++ code. Most subpackages are header-centric libraries, with a few .cpp files where runtime behavior or platform integration is needed. Each feature area has its own BUILD.bazel and dedicated tests.
3. The arene/base subsystems are layered from foundational primitives upward. Lower-level building blocks such as type_traits, utility, memory, iterator, compiler_support, and functional are used by higher-level facilities like containers (inline_container, array, optional, variant, result), strings, math, span/mdspan, units, filesystem, and synchronization primitives.
4. Several packages represent “safe alternatives” to standard C++ facilities: pointer (non_null, non_owning_ptr), result, scope_guard, monostate, semantic_version, source_location, byte, bit, endian, and contracts. These are designed as reusable policy-bearing primitives rather than domain services.
5. Concurrency and OS-facing functionality is isolated into a smaller set of runtime-heavy components: mutex, synchronization (barrier, latch, manual_reset_event), and filesystem (file_handle, directory_handle, temporary-directory helpers, scoped directory changes). These have explicit .cpp implementations and platform-specific branches, unlike the mostly header-only utility layers.
6. The repository includes a separate stdlib subtree that acts as a cut-down standard library implementation or shim. It exposes standard-looking headers and stdlib_detail internals, and it is intentionally decoupled so arene/base can be built either against the toolchain’s standard library or against this repo’s //stdlib target.
7. Build-time configuration is a major architectural boundary. configs/, rules/, bazel_lib/, and extensions/ provide Bazel macros, transitions, and platform/compiler selection logic. The repo’s variants include exception-enabled/disabled code paths, sanitizer/coverage hooks, and stdlib selection; this is how the same API surface can map to different implementations.
8. Platform-specific implementations are handled as alternate source files or internal headers rather than scattered conditionals. Examples include exception-aware vs exception-free code in array, optional, variant, contracts, and platform-specific filesystem helpers. This keeps policy decisions at the build/config layer and implementation details inside each package.
9. Testing is first-class and mirrors the library structure. Each package has its own test target set, including normal unit tests, death tests, compile-error tests, and some property-based or self-checking scripts. The repo also has testlibs/ for reusable test support: minitest, dummy gtest/gmock, and assorted utilities used to validate the library’s behavior across configurations.
10. docs/ is a generated/packaged consumer-facing layer, with user guides, API docs, examples, and architecture diagrams. The examples are build targets too, so documentation is tied to compilable code. GitHub Actions are used to run public tests and publish docs to GitHub Pages, making the documentation and CI part of the delivery pipeline rather than a separate product.
Main entry points: base arene/base · inline_container containers · stdlib stdlib · rules rules
Components 23
Build & Config
Bazel rules, variants, and platform selection.
- rules · Custom Bazel rules for libraries, tests, redirects, and transitions.
rules - configs · Compiler and platform selection, plus config tests.
configs - extensions · Auxiliary Bazel extension/bootstrap logic.
extensions
Foundation
Lowest-level reusable primitives in arene/base.
- compiler support · Compiler/platform queries, annotations, and configuration probes.
arene/base/compiler_support - type traits · Trait utilities that underpin most template-heavy code.
arene/base/type_traits - type manipulation · Type transformation helpers and compile-time utilities.
arene/base/type_manipulation - utility · General-purpose helpers such as swap, in_place, and alignment.
arene/base/utility - functional · Invocation adapters, binders, and function-ref style utilities.
arene/base/functional - iterator · Iterator operations and reverse-iterator support.
arene/base/iterator - memory · Construction and destruction primitives for raw storage.
arene/base/memory
Core Facilities
Higher-level reusable libraries built from the foundation.
- arene/base · Primary reusable C++14 library boundary for safety-critical code.
arene/base - core types · Byte, bit, compare, constraints, contracts, source location, and versioning.
arene/base - safe pointers · Non-null and non-owning pointer abstractions.
arene/base/pointer - result & optional · Error/value and maybe-value abstractions with exception-aware variants.
arene/base/result - containers · Inline/container-like types such as array, vector, map, set, and function.
arene/base/inline_container - strings · String views, inline strings, algorithms, and UTF validation.
arene/base/strings - math & units · Math helpers, linear algebra traits, and units/quantity types.
arene/base/math - span & mdspan · Non-owning contiguous and multidimensional views.
arene/base/span
Runtime & OS
Stateful, platform-facing components with .cpp implementations.
- sync & OS · Mutexes, synchronization primitives, filesystem handles, and temp-directory helpers.
arene/base/filesystem
Testing & Docs
Repository-wide test support, documentation, and examples.
Stdlib Layer
Alternative standard library implementation/shim.
- stdlib · Cut-down standard library implementation used as an alternative backend.
stdlib
Connections 30
- arene/base → compiler support: depends on · Build and implementation feature detection.
- arene/base → type traits: depends on · Template meta-programming foundation.
- arene/base → type manipulation: depends on · Compile-time type transformations.
- arene/base → utility: depends on · General-purpose low-level helpers.
- arene/base → functional: depends on · Callable composition and wrappers.
- arene/base → iterator: depends on · Iterator algorithms and traversal helpers.
- arene/base → memory: depends on · Object lifetime and storage management.
- arene/base → core types: contains · Core safe primitives and boundary types.
- core types → safe pointers: includes · Pointer safety wrappers are part of the core boundary.
- core types → result & optional: includes · Maybe-value and error-value abstractions.
- core types → containers: supports · Container types are built on foundational primitives.
- core types → strings: supports · String facilities layer on core helpers.
- core types → math & units: supports · Numeric and units abstractions.
- core types → span & mdspan: supports · View types and extent handling.
- core types → sync & OS: supports · OS-facing primitives share the same base library boundary.
- containers → result & optional: uses · Variant/optional/result-style containers compose shared primitives.
- containers → safe pointers: uses · Container APIs rely on non-null/non-owning pointer types.
- strings → utility: uses · String algorithms reuse generic helpers.
- math & units → type traits: uses · Traits drive unit and numeric type reasoning.
- span & mdspan → iterator: uses · Traversal and access semantics build on iterators.
- sync & OS → compiler support: uses · Platform branching and runtime configuration.
- testing → testlibs: uses · Shared test harnesses and dummy test frameworks.
- docs → arene/base: documents · Docs and examples describe the library surface.
- docs → stdlib: documents · User docs cover stdlib selection and backend choice.
- rules → arene/base: builds · Bazel macros assemble the library targets.
- configs → rules: configures · Compiler/platform transitions shape target variants.
- extensions → rules: extends · Bootstrap and extension logic supports Bazel integration.
- stdlib → arene/base: backend for · Alternative implementation layer selected at build time.
- stdlib → compiler support: mirrors · Provides stdlib-side support headers and details.
- testing → arene/base: tests · Repository tests validate the library stack.