Build-time Environment

Describes aspects of the build-time environment relevant to library clients. More...

LBAL_NAME
These macros resolve to human-readable strings that identify the specified entities. If the entity has a version value associated with it, such as a compiler does, the string -may- include that version, but it is not required to do so. It is important to understand that since these values are generated in a header at compile time, and so they will change; if it is desired to cache the value, e.g., to report the compiler a library was built with in an executable that links to it, it will be necessary to cache it yourself, e.g., by storing the character array in a string with external storage in a source file in the library and providing an accessor to it. Note that it is not safe to use these for comparisons, either directly or in parsed form, as their format is not guaranteed. While these are intended strictly for reporting, there are other macros more appropriate for testing.
#define	LBAL_NAME_TARGET_CPU
#define	LBAL_NAME_TARGET_OS
#define	LBAL_NAME_COMPILER
#define	LBAL_NAME_STANDARD_LIBRARY

LBAL_TARGET_COMPILER
Report 1 or 0 depending on which macros match the compiler used to build the code. These identifers take the place of direct querying, as some compilers are in the habit of self-identifying as something else, and it can be challenging to suss out their actual identities. These are not generally useful, as there’s typically another, better mechanism for addressing whatever issue these can resolve, but they’re here for when nothing else will do. Note that if you also need version information, you’ll have to resort to direct querying, though it may still sensible to filter first on these for the aforementioned reason. Generally, a given compiler will match at least two tokens: one identifying the rough compiler “family” to which it belongs, and one that identifies it more uniquely. SEEME These are blunt instruments. In particular, there may be no differentiation between frontened (e.g., c1xx or clang) and backend (e.g., c2 or llvm). In practice, this mattered more when c2/clang was a thing, but seems less important now. We’ll consider revisiting if the extra granularity turns out to be useful.
#define	LBAL_TARGET_COMPILER_CLANG
	The compiler being used is an llvm/clang derivative. More...
#define	LBAL_TARGET_COMPILER_VANILLA_CLANG
	The compiler being used is pure llvm/clang. More...
#define	LBAL_TARGET_COMPILER_APPLE_CLANG
	The compiler being used is the llvm/clang variant shipped with Apple’s Xcode. More...
#define	LBAL_TARGET_COMPILER_GCC
	The compiler being used is a gcc derivative. More...
#define	LBAL_TARGET_COMPILER_VANILLA_GCC
	The compiler being used is pure gcc. More...
#define	LBAL_TARGET_COMPILER_MSVC
	The compiler being used is an MSVC derivative. More...
#define	LBAL_TARGET_COMPILER_VANILLA_MSVC
	The compiler being used is pure MSVC. More...

LBAL_TARGET_STANDARD_LIBRARY
Report 1 or 0 depending on which mutually exclusive macro matches the C++ Standard Library used to build the code. This takes the place of direct querying, as this may not even be an option in some cases. These are not generally useful, as there’s typically another, better mechanism for solving whatever this is meant to solve, but they’re here for when nothing else will do. Note that if you also need version information, you’ll have to resort to direct querying.
#define	LBAL_TARGET_STANDARD_LIBRARY_APPLE_LIBCPP
	C++ Standard Library implementation is Apple’s libc++. More...
#define	LBAL_TARGET_STANDARD_LIBRARY_LIBCPP
	C++ Standard Library implementation is libc++. More...
#define	LBAL_TARGET_STANDARD_LIBRARY_MSVC
	C++ Standard Library implementation is Microsoft’s. More...
#define	LBAL_TARGET_STANDARD_LIBRARY_LIBSTDCPP
	C++ Standard Library implementation is libstdc++. More...

LBAL_TARGET_CPU_FAMILY
Specify roughly which microprocessor family code is being generated for. At most one of these is 1, the rest are 0. Remarks SEEME One additional candidate for inclusion is LBAL_TARGET_CPU_FAMILY_AMD, but there has been no pragmatic reason to add it.
#define	LBAL_TARGET_CPU_FAMILY_ARM
#define	LBAL_TARGET_CPU_FAMILY_X86

LBAL_TARGET_CPU
Specify for which microprocessor instruction set code is being generated. At most one of these is 1, the rest are 0. Remarks SEEME There used to be more of these, but they’ve been largely mooted. Candidates for additions include console-specific processors and explicit differentiation for AMD processors. SEEME More granular responses are possible, though it’s been viewed as more useful to differentiate on feature sets, instead (e.g., AVX2 availability). FIXME Testing for specific non-SIMD instruction availability, and additionally providing instrinsics, would be very helpful. Specifically, generic ways to invoke POPCNT and LZCNT would be helpful.
#define	LBAL_TARGET_CPU_ARM
#define	LBAL_TARGET_CPU_ARM_64
#define	LBAL_TARGET_CPU_X86
#define	LBAL_TARGET_CPU_X86_64
#define	LBAL_TARGET_CPU_IA64

LBAL_TARGET_VEC
Specify which vector instruction set is being generated, if any. Multiple conditionals may be true, but some are mutually exclusive. Remarks APIME There is no corresponding test for AVX-512, as it’s not a monolithic instruction set, and we don’t have the operational experience needed to evaluate a meaningful breakdown beyond just mirroring any predfined macros the compiler may happen to have. SEEME We don’t currently independently check for SSE-Math and similar instruction splits; this may be a defect. SEEME There used to be more of these, but they’ve been largely mooted. Candidates for additions include console-specific vector instruction sets, and explicit differentiation for AMD instruction sets.
#define	LBAL_TARGET_VEC_SSE
#define	LBAL_TARGET_VEC_SSE2
#define	LBAL_TARGET_VEC_SSE3
#define	LBAL_TARGET_VEC_SSE41
#define	LBAL_TARGET_VEC_SSE42
#define	LBAL_TARGET_VEC_AVX
#define	LBAL_TARGET_VEC_AVX2

LBAL_TARGET_OS
Specify which Operating System code is being generated for. At most one of the these is 1, the rest are 0 (except for LBAL_TARGET_OS_IOS, which is set whenever LBAL_TARGET_OS_IOS_SIM is set, but can also be set alone). Remarks SEEME Candidates for additions include console-specific operating systems, Android, tvOS, and watchOS. BSD could conceivably have its own flag, but we currently roll it in under LBAL_TARGET_OS_X11. SEEME These focus primarily on UI characteristics, as opposed to system internals, which is why we have LBAL_TARGET_OS_X11 and not LBAL_TARGET_OS_POSIX. A case could be made that we realistically need to track both, but in practice - during the implementation of lucenaPAL - no practical need was found. It’s possible that once additional platform support is added to that library, we’ll find we need to revisit this design decision. FIXME Wayland needs to be accounted for; currently, it’s rolled into LBAL_TARGET_OS_X11.
#define	LBAL_TARGET_OS_IOS
#define	LBAL_TARGET_OS_IOS_SIM
#define	LBAL_TARGET_OS_X11
#define	LBAL_TARGET_OS_MACOS
#define	LBAL_TARGET_OS_WINAPI

LBAL_TARGET_RT_[EXECUTABLE_FORMAT]
Identiy the executable format which the compiled code is being linked in. These are most needed when the OS and/or CPU supports more than one format (e.g. Mac OS X on PPC supports CFM and Mach-O). Note that values are descriptive; if the condition is met, the value will be 1, otherwise 0. Remarks APIME Inclusion of specific formats is somewhat arbitrary, as we’ve only bothered to define them for cases we’ve encountered in practice. Additional operational experience—and supported platforms—will probably lead to some additions.
#define	LBAL_TARGET_RT_COFF
#define	LBAL_TARGET_RT_ELF
#define	LBAL_TARGET_RT_MACHO
#define	LBAL_TARGET_RT_WASM

LBAL_TARGET_RT_[ENDIANESS]
Identify the byte-ordering of the code being generated. Note that this is only used to determine the “native” format. We don’t call out processors that can do either; all the processors we support operate in one mode or the other for the duration of execution, which is all we care about.
#define	LBAL_TARGET_RT_LITTLE_ENDIAN
#define	LBAL_TARGET_RT_BIG_ENDIAN

LBAL_TARGET_RT_[ADDRESSING]
Identify the address table size of the runtime environment which the code is being generated for. This identifies whether the binary is being generated for 32-bit or 64-bit execution.
#define	LBAL_TARGET_RT_32_BIT
#define	LBAL_TARGET_RT_64_BIT

LBAL_TARGET_API
Differentiate between sets of core System API’s on the same processor under the same OS. Unlike LBAL_TARGET_OS and LBAL_TARGET_CPU, these tokens are not mutally exclusive. lucenaBAL attempts to auto-configure all LBAL_TARGET_API values, but will often need a LBAL_TARGET_API value predefined—e.g., in a build file—in order to disambiguate. Note that values are descriptive; if the condition is met, the value will be 1, otherwise 0. Remarks SEEME This is not intended to be an exhaustive list of APIs. Originally, it was useful for differentiating between possible supported and available Apple APIs (e.g., QuickDraw, Carbon, Cocoa, and whatever other toolbox flavor of the week floats in), but it’s academic on platforms that don’t deprecate their APIs with abandon. Further operational experience might find us wanting to differentiate between other available OS-level APIs.
#define	LBAL_TARGET_API_COCOA
#define	LBAL_TARGET_API_COCOA_TOUCH
#define	LBAL_TARGET_API_POSIX
#define	LBAL_TARGET_API_WIN32
#define	LBAL_TARGET_API_WIN64
#define	LBAL_TARGET_API_X11

Detailed Description

Describes aspects of the build-time environment relevant to library clients.

These are mostly descriptors of various kinds.

Macro Definition Documentation

LBAL_NAME_COMPILER

#define LBAL_NAME_COMPILER

This names the compiler used to build the code.

LBAL_NAME_STANDARD_LIBRARY

#define LBAL_NAME_STANDARD_LIBRARY

This names the implementation of the C++ Standard Library used to build the code.

LBAL_NAME_TARGET_CPU

#define LBAL_NAME_TARGET_CPU

At a minimum, this will name the CPU family that the code was compiled for, but it may contain much more detailed information.

LBAL_NAME_TARGET_OS

#define LBAL_NAME_TARGET_OS

This names the target OS, and may identify the minimum supported version of the target OS, as well, though is not required to do so.

LBAL_TARGET_API_COCOA

#define LBAL_TARGET_API_COCOA

Apple’s object-oriented API for macOS.

LBAL_TARGET_API_COCOA_TOUCH

#define LBAL_TARGET_API_COCOA_TOUCH

Apple’s object-oriented API for iOS, watchOS, and tvOS.

LBAL_TARGET_API_POSIX

#define LBAL_TARGET_API_POSIX

The standard C API used by all flavors of UNIX.

LBAL_TARGET_API_WIN32

#define LBAL_TARGET_API_WIN32

A Microsoft’s C API for Windows.

LBAL_TARGET_API_WIN64

#define LBAL_TARGET_API_WIN64

A Microsoft’s C API for Windows, specific to 64-bit implementations.

LBAL_TARGET_API_X11

#define LBAL_TARGET_API_X11

The standard C Graphics API used by most flavors of UNIX.

LBAL_TARGET_COMPILER_APPLE_CLANG

#define LBAL_TARGET_COMPILER_APPLE_CLANG

The compiler being used is the llvm/clang variant shipped with Apple’s Xcode.

More information is available from the llvm project.

LBAL_TARGET_COMPILER_CLANG

#define LBAL_TARGET_COMPILER_CLANG

The compiler being used is an llvm/clang derivative.

This probably won’t match c2/clang, but no testing has been done to see what that setup may be emulating. More information is available from the llvm project.

Remarks

SEEME It would be trivial to split this identifier into one for clang and one for llvm, but it’s unclear how useful this would be.

LBAL_TARGET_COMPILER_GCC

#define LBAL_TARGET_COMPILER_GCC

The compiler being used is a gcc derivative.

More information is available from the gcc project.

LBAL_TARGET_COMPILER_MSVC

#define LBAL_TARGET_COMPILER_MSVC

The compiler being used is an MSVC derivative.

More information is available from Microsoft.

LBAL_TARGET_COMPILER_VANILLA_CLANG

#define LBAL_TARGET_COMPILER_VANILLA_CLANG

The compiler being used is pure llvm/clang.

More information is available from the llvm project.

Remarks

SEEME This is a more loose definition than it sounds like, as we’ll classify any clang as “vanilla clang” if some other check hasn’t previously claimed it, so order of evaluation matters, as does how thorough the previous checks were.

LBAL_TARGET_COMPILER_VANILLA_GCC

#define LBAL_TARGET_COMPILER_VANILLA_GCC

The compiler being used is pure gcc.

More information is available from the llvm project.

Remarks

SEEME This is a more loose definition than it sounds like, as we’ll classify any gcc as “vanilla gcc” if some other check hasn’t previously claimed it, so order of evaluation matters, as does how thorough the previous checks were.

LBAL_TARGET_COMPILER_VANILLA_MSVC

#define LBAL_TARGET_COMPILER_VANILLA_MSVC

The compiler being used is pure MSVC.

More information is available from Microsoft.

Remarks

SEEME This is a more loose definition than it sounds like, as we’ll classify any MSVC as “vanilla MSVC” if some other check hasn’t previously claimed it, so order of evaluation matters, as does how thorough the previous checks were.

LBAL_TARGET_CPU_ARM

#define LBAL_TARGET_CPU_ARM

Generic 32-bit ARM

LBAL_TARGET_CPU_ARM_64

#define LBAL_TARGET_CPU_ARM_64

Generic 64-bit ARM

LBAL_TARGET_CPU_FAMILY_ARM

#define LBAL_TARGET_CPU_FAMILY_ARM

The CPU is in the ARM chip family.

LBAL_TARGET_CPU_FAMILY_X86

#define LBAL_TARGET_CPU_FAMILY_X86

The CPU is x86 instruction set-compatible, including Intel and AMD processors.

LBAL_TARGET_CPU_IA64

#define LBAL_TARGET_CPU_IA64

Generic 64-bit Itanium

LBAL_TARGET_CPU_X86

#define LBAL_TARGET_CPU_X86

Generic 32-bit x86

LBAL_TARGET_CPU_X86_64

#define LBAL_TARGET_CPU_X86_64

Generic 64-bit x86

LBAL_TARGET_OS_IOS

#define LBAL_TARGET_OS_IOS

Apple’s iOS

LBAL_TARGET_OS_IOS_SIM

#define LBAL_TARGET_OS_IOS_SIM

Apple‘s iOS running under a Simulator

LBAL_TARGET_OS_MACOS

#define LBAL_TARGET_OS_MACOS

Apple’s macOS

LBAL_TARGET_OS_WINAPI

#define LBAL_TARGET_OS_WINAPI

Microsoft’s Windows

LBAL_TARGET_OS_X11

#define LBAL_TARGET_OS_X11

X.org‘s X11

LBAL_TARGET_RT_32_BIT

#define LBAL_TARGET_RT_32_BIT

32-bit addressing is being used.

LBAL_TARGET_RT_64_BIT

#define LBAL_TARGET_RT_64_BIT

64-bit addressing is being used.

LBAL_TARGET_RT_BIG_ENDIAN

#define LBAL_TARGET_RT_BIG_ENDIAN

The PowerPC-standard Big Endian byte-ordering is being used.

LBAL_TARGET_RT_COFF

#define LBAL_TARGET_RT_COFF

A COFF derivative is being used, including COFF and PE/COFF.

LBAL_TARGET_RT_ELF

#define LBAL_TARGET_RT_ELF

The ELF executable format, currently the default for Linux and BSD, is being used.

LBAL_TARGET_RT_LITTLE_ENDIAN

#define LBAL_TARGET_RT_LITTLE_ENDIAN

The Intel-standard Little Endian byte-ordering is being used.

LBAL_TARGET_RT_MACHO

#define LBAL_TARGET_RT_MACHO

The Mach-O executable format, currently the default for macOS and iOS, is being used.

LBAL_TARGET_RT_WASM

#define LBAL_TARGET_RT_WASM

The Wasm byte code executable format is being used.

LBAL_TARGET_STANDARD_LIBRARY_APPLE_LIBCPP

#define LBAL_TARGET_STANDARD_LIBRARY_APPLE_LIBCPP

C++ Standard Library implementation is Apple’s libc++.

Information available from the llvm project.

LBAL_TARGET_STANDARD_LIBRARY_LIBCPP

#define LBAL_TARGET_STANDARD_LIBRARY_LIBCPP

C++ Standard Library implementation is libc++.

Information available from the llvm project.

LBAL_TARGET_STANDARD_LIBRARY_LIBSTDCPP

#define LBAL_TARGET_STANDARD_LIBRARY_LIBSTDCPP

C++ Standard Library implementation is libstdc++.

Information available from the gcc project.

LBAL_TARGET_STANDARD_LIBRARY_MSVC

#define LBAL_TARGET_STANDARD_LIBRARY_MSVC

C++ Standard Library implementation is Microsoft’s.

Information available from Microsoft.

LBAL_TARGET_VEC_AVX

#define LBAL_TARGET_VEC_AVX

Intel AVX SIMD instruction set.

LBAL_TARGET_VEC_AVX2

#define LBAL_TARGET_VEC_AVX2

Intel AVX2 SIMD instruction set.

LBAL_TARGET_VEC_SSE

#define LBAL_TARGET_VEC_SSE

Intel SSE SIMD instruction set.

LBAL_TARGET_VEC_SSE2

#define LBAL_TARGET_VEC_SSE2

Intel SSE2 SIMD instruction set.

LBAL_TARGET_VEC_SSE3

#define LBAL_TARGET_VEC_SSE3

Intel SSE3 SIMD instruction set.

LBAL_TARGET_VEC_SSE41

#define LBAL_TARGET_VEC_SSE41

Intel SSE4.1 SIMD instruction set.

LBAL_TARGET_VEC_SSE42

#define LBAL_TARGET_VEC_SSE42

Intel SSE4.2 SIMD instruction set.