Handles library configuration. More...

Version Info
Identifies the versions of various components of lucenaBAL lucenaBAL uses semantic versioning to keep track of API-level revisions. Additionally, there is an ABI version number which changes very infrequently and is tracked using a monotonically increasing integer value.
#define	LBAL_version_major
	Corresponds to the MAJOR version number in the semantic versioning scheme.

#define	LBAL_version_minor
	Corresponds to the MINOR version number in the semantic versioning scheme.

#define	LBAL_version_patch
	Corresponds to the PATCH version number in the semantic versioning scheme.

#define	LBAL_version
	Packed 32-bit unsigned integer representation of the full semantic version number. More...

#define	LBAL_abi_version
	Monotonically increasing integer value identifying the current ABI revision. More...

Utilities
Miscellaneous tools used in the headers These are internal utilities that are publicly documented as they may be generally useful to library clients.
#define	LBAL_Concat_(LBAL_base_, LBAL_suffix_)
	Concatenate any two preprocessor macro arguments to create a new token. More...

#define	LBAL_Stringify_(LBAL_param_)
	Turn the literal value param_ into a string literal. More...

Environment
Identify characteristics of the build evironment These provide data identifying top-level characteristics of the build environment that are used elsewhere in the library, but that may also have value to clients. More specialized information is collected and exposed elsewhere.
#define	LBAL_cpp_version
	Identify the Standard C++ dialect being used. More...

Settings
Configure the library itself These can be set by simply passing macro definitions on the command-line to the compiler or build system. Remarks Due to certain limitations of CMake, when using that build system, it is necessary to use proxies specific to CMake in the form of `options` in order to pass macro definitions on to the compiler. See `CMakeLists.txt` for details, in the “option setup” section.
#define	LBAL_CONFIG_enable_pedantic_warnings
	Client setting to control certain compile-time warnings. More...

#define	LBAL_CONFIG_treat_uncertainty_as_failure
	Client setting to force conservative guesses when detecting features. More...

Namespaces
Sets up the namespaces used by lucenaBAL lucenaBAL uses both versioned and unversioned namespaces, depending on context. The versioned namespaces live within the unversioned namespace, with the current versioned namespace being inline. All symbols are contained somewhere within our top-level namespace. Anything contained in the current versioned namespace can be qualified with just the regular namespace name, but its fully-qualified name will include a version identifier. This provides a mechanism by which we can have non-disruptive ABI changes, should the need arise. Remarks In the absence of modules—or at least certain features of certain module-related Standard proposals—preprocessor tokens cannot be namespace-qualified, so they all exist in a global soup. lucenaBAL uses the `LBAL_` prefix to qualify all of its preprocessor tokens for this reason, but there is no guarantee that these names are unique. APIME Note that there doesn’t appear to be a way to ensure that the namespace scope macros are invoked correctly, e.g., guard values to keep from accidentally exiting the incorrect namespace.
#define	LBAL_begin_namespace
	Enter the regular namespace. More...

#define	LBAL_end_namespace
	Exit the regular namespace and return to the global namespace. More...

#define	LBAL_enter_v_namespace
	Enter the versioned namespace from the unversioned namespace. More...

#define	LBAL_exit_v_namespace
	Exit the versioned namespace and return to the unversioned namespace. More...

#define	LBAL_begin_v_namespace
	Enter the versioned namespace from the global namespace. More...

#define	LBAL_end_v_namespace
	Exit the versioned namespace and return to the global namespace. More...

#define	LBAL_
	Unversioned namespace qualifier. More...

#define	LBAL_v_
	Versioned namespace qualifier. More...

Detailed Description

Handles library configuration.

The library is controlled via preprocessor macros which define certain parameters it must operate under, both globally and locally.

Macro Definition Documentation

◆ LBAL_

#define LBAL_

Unversioned namespace qualifier.

This is used to refer to a symbol if it is within the unversioned lucenaBAL namespace, including if it is within the versioned inline namespace.

◆ LBAL_abi_version

#define LBAL_abi_version

Monotonically increasing integer value identifying the current ABI revision.

This changes very infrequently. Additionally, it is currently unused, as there is no binary component in the current rendition of lucenaBAL.

◆ LBAL_begin_namespace

#define LBAL_begin_namespace

Enter the regular namespace.

This introduces a new namespace scope. It should only be invoked at global namespace scope.

Remarks: SEEME Because of how C++ namespaces work, it may not be immediately obvious if this has been used incorrectly. Generally, this should be a non-issue since this token should not appear in client code.

Examples: namespace_example.cpp.

◆ LBAL_begin_v_namespace

#define LBAL_begin_v_namespace

Enter the versioned namespace from the global namespace.

This introduces a new versioned namespace scope. It should only be invoked from the global namespace scope.

Examples: namespace_example.cpp.

◆ LBAL_Concat_

#define LBAL_Concat_	(	LBAL_base_,
		LBAL_suffix_
	)

Concatenate any two preprocessor macro arguments to create a new token.

Remarks: This macro contains an additional indirection which is necessary to ensure that the values of the arguments—not the argument identifiers—are used.

Parameters

[in]	LBAL_base_	The base token to be appended to. Must be a valid preprocessor token in its own right.
[in]	LBAL_suffix_	The suffix to be appended to LBAL_base_. Must be composed only of characters allowed in a preprocessor token.

Returns: A new token that is the exact concatentation of LBAL_suffix_ onto LBAL_base_

◆ LBAL_CONFIG_enable_pedantic_warnings

#define LBAL_CONFIG_enable_pedantic_warnings

Client setting to control certain compile-time warnings.

Generally, this should be set to 1, as the associated warnings trigger whenever anything unusual happens, and “anything unusual” is almost definitely going to be something undesirable. If the client is in the rare situation of tripping these warnings and finding them spurious, however, this setting offers a blunt instrument to silence them.

Remarks: This can be set per-tranlation unit, globally, or any combination in-between.

◆ LBAL_CONFIG_treat_uncertainty_as_failure

#define LBAL_CONFIG_treat_uncertainty_as_failure

Client setting to force conservative guesses when detecting features.

Sometimes when a feature detection is done, we won’t have enough information to make a definitive determination regarding availability. When this happens, we assume, by default, that the feature is available. To change this behavior, set this macro to 1 instead of 0. Note that this may have an effect on generated binaries, and so changing this should be accompanied by equivalent changes to any dependencies or clients.

Keep in mind that we perform a battery of tests to determine feature availability, so situations where this setting becomes relevant typically arise either when attempting tobuild in an untested environment, i.e., one we haven’t established special-case rules for, or when building in a known environment with low-quality reporting, e.g., attempting to detect headers when the compiler doesn’t provide __has_include. We assume building will mostly happen in known, tested environments, so trust that our special- casing will have issued a definitive failure if a given feature is genuinely unavailable. The corollary to this is that new environments should have implementation files created for them as needed in order to minimize repercussions and keep things simple.

Remarks: SEEME Because alterations to this are effectively viral, it is strongly recommended to only change this globally, and to be very through about it. It is even better to not change it at all, and instead provide new implementation file with appropriate special cases to avoid nasty surprises if some tool in the chain has a different value for this setting.

◆ LBAL_cpp_version

#define LBAL_cpp_version

Identify the Standard C++ dialect being used.

In a Standard-conforming world, __cplusplus would be all you need to do this. Unfortunately, we are not in a Standard-conforming world.

It is strongly recommended to not rely on this value for feature testing, but rather use the appropriate feature token.

Remarks: SEEME Microsoft Visual Studio stopped setting __cplusplus in the expected manner, but replaced the utility of it with a proprietary macro, _MSVC_LANG. We use it as an analog. Note that _MSVC_LANG is not available prior to MSVS 2015 Update 3.

◆ LBAL_end_namespace

#define LBAL_end_namespace

Exit the regular namespace and return to the global namespace.

This ends the regular namespace scope. It should only be invoked from within the regular lucenaBAL namespace.

Remarks: SEEME Because of how C++ namespaces work, it may not be immediately obvious if this has been used incorrectly. Generally, this should be a non-issue since this token should not appear in client code.

Examples: namespace_example.cpp.

◆ LBAL_end_v_namespace

#define LBAL_end_v_namespace

Exit the versioned namespace and return to the global namespace.

This ends the versioned namespace scope, returning to the global namespace scope. It should only be invoked from within the versioned lucenaBAL namespace.

Remarks: SEEME Because of how C++ namespaces work, it may not be immediately obvious if this has been used incorrectly. Generally, this should be a non-issue since this token should not appear in client code.

Examples: namespace_example.cpp.

◆ LBAL_enter_v_namespace

#define LBAL_enter_v_namespace

Enter the versioned namespace from the unversioned namespace.

This introduces a new versioned namespace scope. It should only be invoked from within the regular lucenaBAL namespace.

Remarks: SEEME Because of how C++ namespaces work, it may not be immediately obvious if this has been used incorrectly. Generally, this should be a non-issue since this token should not appear in client code.

Examples: namespace_example.cpp.

◆ LBAL_exit_v_namespace

#define LBAL_exit_v_namespace

Exit the versioned namespace and return to the unversioned namespace.

This exits the versioned namespace scope, returning to the unversioned namespace scope. It should only be invoked from within the versioned lucenaBAL namespace.

Remarks: SEEME Because of how C++ namespaces work, it may not be immediately obvious if this has been used incorrectly. Generally, this should be a non-issue since this token should not appear in client code.

Examples: namespace_example.cpp.

◆ LBAL_Stringify_

#define LBAL_Stringify_ ( LBAL_param_ )

Turn the literal value param_ into a string literal.

Remarks: Due to limitations of the preprocessor, literal commas (“,”) will not be stringified. This macro contains an additional indirection which is necessary to ensure that the values of the arguments—not the argument identifiers—are used.

Parameters

LBAL_param_ An arbitrary term or expression, up to the limit of what the preprocessor will allow as a macro argument

Returns: A string literal, effectively a quoted C-style string

◆ LBAL_v_

#define LBAL_v_

Versioned namespace qualifier.

This is used to refer to a symbol using its fully qualified namespace if it is within the versioned lucenaBAL namespace.

◆ LBAL_version

#define LBAL_version

Packed 32-bit unsigned integer representation of the full semantic version number.

The high 8 bits encode MAJOR, followed by 8 bits for MINOR, and the 16 low bits represent PATCH.

Version Info

Utilities

Environment

Settings

Namespaces