|
ALib C++ Framework
|
by |  |
|
Loading...
Searching...
No Matches
|
ALib C++ Framework
|
by | |
|
The ALib C++ Framework comes with a large number of preprocessor define statements (around 350 at the time of writing ). To keep this manageable, some rules have been adopted in respect to naming and grouping of the macros.
Almost all configuration macros are written in "CAPITAL_SNAKE_CASE" and are prefixed by "ALIB_". Most macros then continue with the name of the ALib Module that uses/defines them.
One important exception to this naming scheme is the macros defined by module ALox, which are prefixed "ALOX_". Furthermore, the module ALox defines macros for logging that even use "CamelCase" names.
ALib separates two different kinds of macros:
Those are macro-constants that are mainly used to select different versions of code, dependent on
This documentation sometimes refers to such macros as "code selection macros". Many of the configuration macros can be passed to the compiler to overwrite their default value. This is usually done with the -D-option of a compiler's invocation command.
Besides the internal use to select ALib library code, the macros can be used with custom code for the same purpose. This is especially necessary if custom software is designed to work with different ALib Builds and different optional feature sets of ALib.
All configuration macros are documented in paragraph 2 of this manual page.
Preprocessor macros, which are not passable with the compiler's command line and which usually are not just static constants but "real" macros that expand to code, are simply called "macros".
The documentation of all macros is given in in paragraph 3 of this manual page.
The following sections list configuration macros that are not related to a specific ALib Module. This is the reference documentation for configuration macros that evaluate to true or false (precisely 1 or 0). Unless explicitly mentioned, the macros may be passed to the compiler to overwrite their documented default value.
The following macros are very fundamental to ALib:
The following general configuration macros (aka macros not related to distinct ALib Modules) are deduced by ALib headers and thus usually are not to be passed to the compiler.
This group of configuration macros determine the availability of different ALib Modules of the ALib Build used. The macros are defined in the internal header alib/alib.inl, which always is and has to be the first ALib header-file included (directly or indirectly). If none of the macros is passed to the compiler, this header-file will define all to 1, hence will include all modules an ALib Build.
If a macro is given as 1, all corresponding macros of dependent modules are also defined to 1, even if one had explicitly given as 0, which is considered a contradicting input.
The following sections list configuration macros that are related to specific ALib Module.
This group of code selection macros is defined with the use of module ALox and used to select the inclusion of log code. The macros are seldom to be used by end-user code. Instead, the macros used for the log statements themselves (see debug logging macros and release logging macros.) are variably defined based on these macros.
This section lists all preprocessor Macros of ALib used to generate code or prune code pieces. Often, the definition of macros depends on Configuration Macros, which have been documented in the previous section 2. Configuration Macros.
The following sections list macros that are not related to a specific ALib Modules:
Macros used to verify that the ALib binary used has the right version is compiled with the same feature set as the current compilation unit. For this, version and feature flags are compiled statically into the library. The macros are used internally, respectively 'automatically'. Hence, they need not be used directly by clients of the library.
The following macros are fundamental and building blocks for other macros.
The macros listed here are supporting C++ compilation and linking control and language specific utilities.
ALib sources are designed to be compiled on different compilers using the highest possible compiler warning levels available. In some situations, some warnings need to be temporarily disabled. The following macros do this in a compiler agnostic way.
These macros are used with debug-builds of ALib, respectively when macro ALIB_DEBUG is given. They provide shortcuts into functions of the small foundational module ALib Module Assert - Programmer's Manual.
If also module ALox is compiled into the library, then a plug-in that uses ALox for the message output is used. See class ALoxAssertionPlugin for more information.
Macros for handling template types.
The macros listed here have a direct relationship with classes defined in ALib and with their use.
The macros listed here include or prune code, dependent on different configuration macros. They are mainly given to avoid #if/#else/#endif statements for small code pieces.
The following sections list macros that specific to ALib Modules.
The macros listed here, are provided to place debug Log Statements within source code using module ALox. Besides that, macros controlling and setting preferences for ALox exists.
The exclusive use of these macros should be sufficient to support most of common debug logging statements with ALox. Should some functionality be not available easily with using the macros, of course, the normal C++ API of ALox can be used in parallel to using the macros. For proper pruning of code that is using the C++ API, such code has to be enclosed by
#if ALOX_DBG_LOG ... ... #endif
lines, or embedded in macro Log_Prune.
All macro names are prefixed "Log_". This implies that they are macros to implement debug logging. In contrast to this, a set of similar macros exists for release logging (see release logging macros). Those are prefixed "Lox_". (The choice of the prefixes Log_ and Lox provide maximum source code compatibility of ALox for C++ log lines in comparison to ALox for C# and ALox for Java.
Most macros make use of the macro LOG_LOX, which references a singleton object of the class Lox that is used for all debug logging. This singleton concept covers most use cases for debug logging. If more flexibility is wanted, then either macro LOG_LOX might be changed for different compilation units or the ALox for C++ API might be used instead of the macros listed here.
The macros listed here are provided to place release Log Statements within source code using module ALox. Besides that, macros controlling and setting preferences for ALox exists.
The exclusive use of these macros should be sufficient to support most of common release logging statements with ALox. Should some functionality be not available easily using the macros, of course, the normal C++ API of ALox can be used in parallel to using the macros. Code that is using the C++ API might be enclosed by preprocessor directives
#if ALOX_REL_LOG ... ... #endif
to remove them when compiling a release version of the software unit with pruned release log macros. Alternatively, such code might be embedded in macro Lox_Prune. (Pruning of release logging can be enabled by defining the configuration macro ALOX_REL_LOG to 0 and could be useful in certain situations.)
Before using the macros, each code entity has to set the preprocessor macro LOX_LOX This can be done in a general header-file of the software, (e.g., the same that exposes the release-Lox object to that source), or, in more complex scenarios with more than one release-Lox object, at any other appropriate source location.
All macro names are prefixed with the term Lox_. This implies that they are macros to implement release logging. In contrast to this, a set of similar macros exists for debug logging (see debug logging macros). Those are prefixed Log_.
Most macros make use of the macro LOX_LOX, which references a singleton object of class Lox that is used for all release logging. This singleton concept covers most use cases for release logging. If more flexibility is wanted, then either the macro LOX_LOX might be changed for different compilation units or the ALox C++ API might be used instead of the macros listed here.
The preprocessor macros listed here are the foundation for debug logging- and release logging macros introduced below.
Developers that use ALox in standard use cases do not need to know and use the macros listed here.
The macros in this section are introduced by module ALib Boxing.
The macros in this section are introduced by module ALib Characters.
The macros in this section are introduced by ALib Camp ALib Variables.
The macros in this section are introduced by modules ALib EnumOps and ALib EnumRecords. They allow specializing the following type traits for scoped or non-scoped enum types: RecordsTraits, ArithmeticalTraits, BitwiseTraits and IterableTraits
private or protected inner types of structs or classes.The macros in this section are introduced by module ALib Expressions.
The macros in this section are introduced by module ALib Strings.
While macros in this section logically belong to module ALib Threads, they are available (but empty) also when this module is not included in the ALib Build. An explanation to this is given with chapter 1.2 Threading-Agnostic Software of this module's Programmer's Manual.
Their definition depends on the setting of ALIB_DEBUG_CRITICAL_SECTIONS, which defaults to 1, in case module ALib Threads is included in the ALib Build.
If the macro is not set, all the macros in this section are empty.
The macros in this section are introduced by module ALib Resources.