Provide compile-time support for platform/attribute identification.
More...
- Outline
-
-
- Purpose:
- Provide compile-time support for platform/attribute identification.
-
- Classes:
| bsls::Platform | namespace for platform traits |
-
- Macros:
| BSLS_PLATFORM_OS_* | operating system type, sub-type, and version |
| BSLS_PLATFORM_CPU_* | instruction set, instruction width, and version |
| BSLS_PLATFORM_CMP_* | compiler vendor, and version |
| BSLS_PLATFORM_COMPILER_ERROR | trigger a compiler error |
| BSLS_PLATFORM_AGGRESSIVE_INLINE | inline code for speed over text size |
- See also:
- Component bsls_compilerfeatures, Component bsls_libraryfeatures
-
- Description:
- This component implements a suite of preprocessor macros and traits that identify and define platform-specific compile-time attributes. These attributes consist of the types and versions of (1) the operating system, (2) the processor(s), and (3) the compiler that together make up the platform. Many of the macros defined in this component are configured automatically at compile-time; compile-time switches are used to configure the rest. Note that compiler capabilities are better determined through the
bsls_compilerfeatures and bsls_libraryfeatures components; this component focuses on just identifying the tool chain.
- Note that, for brevity, the
@ character in the following (alphabetically organized) tables is used to represent the characters BSLS_PLATFORM -- e.g., @_OS_UNIX represents BSLS_PLATFORM_OS_UNIX: =============================================================
OPERATING SYSTEM
-------------------------------------------------------------
Type Subtype Version
----------------- ------------------- -----------------
@_OS_UNIX @_OS_AIX @_OS_VER_MAJOR
@_OS_LINUX @_OS_VER_MINOR
@_OS_FREEBSD
@_OS_SOLARIS
@_OS_SUNOS
@_OS_CYGWIN
@_OS_DARWIN
@_OS_WINDOWS @_OS_WINNT
@_OS_WIN9X
@_OS_WIN2K
@_OS_WINXP
@_OS_WINS03
@_OS_WINS08 -- alias to Vista
@_OS_WINVISTA
@_OS_WIN7
@_OS_WIN8
@_OS_WINBLUE
@_OS_WIN10
Please see also {Windows Subtypes Explained}.
============================================================
PROCESSOR
------------------------------------------------------------
Instruction Set Width Version
----------------- ------------------ ----------------
@_CPU_88000 @_CPU_32_BIT @_CPU_VER_MAJOR
@_CPU_ALPHA @_CPU_64_BIT
@_CPU_HPPA
@_CPU_X86
@_CPU_IA64
@_CPU_X86_64
@_CPU_MIPS
@_CPU_POWERPC
@_CPU_SPARC
@_CPU_ARM
=============================================================
COMPILER
-------------------------------------------------------------
Vendor Version
----------------- ------------------
@_CMP_CLANG @_CMP_VERSION
@_CMP_EDG @_CMP_VER_MAJOR (deprecated)
@_CMP_GNU
@_CMP_HP
@_CMP_IBM
@_CMP_MSVC
@_CMP_SUN
=============================================================
=============================================================
ENSURE A COMPILER ERROR FOR UNSUPPORTED PLATFORMS
--------------------------------------------------------------
Macro
---------------
@_COMPILER_ERROR
=============================================================
=============================================================
INLINING
-------------------------------------------------------------
Macro
-----------------
@_AGGRESSIVE_INLINE
=============================================================
BSLS_PLATFORM_OS_UNIX or BSLS_PLATFORM_OS_WINDOWS) is defined along with exactly one processor macro (e.g., BSLS_PLATFORM_CPU_SPARC) and exactly one compiler macro (e.g., BSLS_PLATFORM_CMP_SUN). Clients may need to supply additional macros (controlled via the -D option of a compiler) if further discrimination is required (e.g., based on sub-type or version of a specific operating system, processor, or compiler). Note that supplying a minor version number implies that the major version is also defined.
-
- Aggressive Inlining:
- The aggressive inlining macro
BSLS_PLATFORM_AGGRESSIVE_INLINE is defined as the inline keyword on all compilers except BSLS_PLATFORM_CMP_IBM and BSLS_PLATFORM_CMP_SUN, where it is left empty. This is required for some of our legacy applications where substantially growing the text size is not possible. Even on those platforms, the symbol will be defined as inline if BDE_BUILD_TARGET_AGGRESSIVE_INLINE is passed in via the -D option of the compiler.
-
- Forcing a Compiler Error:
- The compiler-error triggering macro
BSLS_PLATFORM_COMPILER_ERROR is defined to a sequence of tokens that guarantees a compilation error on every supported compiler. This is necessary because not all compilers will respect the fairly obvious goal of the #error preprocessor directive even though they support it, and just issue a warning (claiming that the C++ standard does not make a difference between a warning and an error, it knows only about diagnostic messages). Code using bsls_platform macros will often want to prevent compilation for unsupported platforms, hence this component provides a macro that can be used to ensure that.
-
- Windows Subtypes Explained:
- --------------------------- Windows Subtypes describe what API variation the code is built to target, not the actual operating system it will run on, with the following mapping between the macro names and Windows API versions:
MACRO Targeted API Version & Notes Officially supported?
------------- ---------------------------- ---------------------
@_OS_WINNT NT 4.0 NO
@_OS_WIN9X 95, 98, ME NO
@_OS_WIN2K 2000 NO
@_OS_WINXP XP NO
@_OS_WINS03 Server 2003 NO
@_OS_WINS08 Server 2008, same as Vista yes
@_OS_WINVISTA Vista yes
@_OS_WIN7 7 yes
@_OS_WIN8 8 yes
@_OS_WINBLUE 8.1 yes
@_OS_WIN10 10 yes
-
- Usage:
- Writing portable software sometimes involves specializing implementations to work with platform-specific interfaces. For example, a socket-level communications framework would need to operate differently on a platform having a Windows operating system than on one having a Unix one (but it is probably unnecessary to distinguish between their respective versions):
#include <bsls_platform.h>
#ifdef BSLS_PLATFORM_OS_WINDOWS
#ifndef INCLUDED_WINSOCK2
#include <winsock2.h>
#define INCLUDED_WINSOCK2
#endif
#endif
class my_Socket {
#ifdef BSLS_PLATFORM_OS_WINDOWS
SOCKET d_socketObject;
#else
int d_socketObject;
#endif
};
BSLS_PLATFORM_IS_BIG_ENDIAN
BSLS_PLATFORM_IS_LITTLE_ENDIAN
short to network byte order (which is consistent with big-endian): short convertToNetworkByteOrder(short input)
{
#ifdef BSLS_PLATFORM_IS_BIG_ENDIAN
return input;
#else
return ((input >> 8) & 0xFF) | ((input & 0xFF) << 8);
#endif
}
