Introduction

The Lucena Build Abstraction Library (lucenaBAL) is a tool for identifying the characteristics of the environment used to build your code and for describing the capabilities of the C++ compiler and Standard Library implementation being used. Additionally, it provides uniform abstractions for certain compiler- and linker-dependent decorators used for things like branch prediction and symbol visibility that would otherwise require testing and knowledge of the toolchain to expose, and even then would require proprietary constructs to use.

The primary objective of this library is to facilitate cross-platform interoperability between triples of mostly-conforming modern compilers, Standard Libraries implementations, and build environments. In particular, rather than being forced to use a least-common denominator set of features, lucenaBAL provides the tools to determine maximally-available feature sets. Glue code libraries may then be provided on top of this to make certain otherwise-limited-availability features generally available, or the decision could be made to provide multiple paths of execution.

Usage Instructions

All that’s needed to make use of lucenaBAL is to issue #include <lucenaBAL/lucenaBAL.hpp> in each participating file. As a header-only library with no dependencies beyond including <ciso646>—and <version>, if available—from the C++ Standard Library, there’s nothing else to link or install. Additionally, there’s not much to configure, though you can see Configuration for options.

The library itself comprises a large collection of preprocessor macros, grouped loosely into build-time descriptors, feature identifiers, and linker decorators. Names are generally modeled on their equivalent SD-6 macrosm if any, with the addition of a short C++ Standard version tag e.g., LBAL_LIBCPP17_OPTIONAL vs __cpp_lib_optional. the LBAL tags should be used preferentially as they capture more information than the SD-6 tags. See the relevant sections for more information.

Header Notes

Labels can appear in the source comments to indicate areas that require special attention; we document those here:

FIXME: something that is a known bug, incomplete, or a likely trouble area targeted for a future rewrite. These tags typically decorate in-development code, but may persist across multiple releases depending on triage outcomes.
APIME: a likely API problem. These tags make note of surprising behavior that may pose a future maintenance problem, and are typically the result of poor design in the library or its dependencies.
OPTME: something that could be made more efficient with a high probable performance return. This notation is generally reserved for speed-critical sections that would benefit from further attention.
VERME: a place where an assumption has been made about performance, stability, usefulness, etc. These tags document areas that would benefit from future testing.
SEEME: something noteworthy that requires care to use correctly. These tags demarcate a counterintuitive flow or algorithmic approach that can be tricky to understand or that involves non-obvious tradeoffs.