4 [authors [Rivera, Rene]]
5 [copyright 2005, 2008-2016 Rene Rivera]
6 [copyright 2015 Charly Chevalier]
7 [copyright 2015 Joel Falcou]
8 [purpose Identification and specification of predefined macros.]
10 Distributed under the Boost Software License, Version 1.0.
11 (See accompanying file LICENSE_1_0.txt or copy at
12 [@http://www.boost.org/LICENSE_1_0.txt])
15 [category miscellaneous]
20 [section Introduction]
22 This library defines a set of compiler, architecture, operating system,
23 library, and other version numbers from the information it can gather of
24 C, C++, Objective C, and Objective C++ predefined macros or those defined
25 in generally available headers. The idea for this library grew out of a
26 proposal to extend the Boost Config library to provide more, and consistent,
27 information than the feature definitions it supports. What follows is
28 an edited version of that brief proposal.
32 The idea is to define a set of macros to identify compilers and
33 consistently represent their version. This includes:
35 * A unique BOOST_VERSION_NUMBER(major,minor,patch) macro to specify version
36 numbers (unfortunately, the name BOOST_VERSION is already taken to designate
37 the version number of boost itself).
38 * A compiler identification macro, suitable for use in `#if`/`#elif` directives,
39 for each of the supported compilers. All macros would be defined, regardless
40 of the compiler. The one macro corresponding to the compiler being used would
41 be defined, in terms of BOOST_VERSION_NUMBER, to carry the exact compiler
42 version. All other macros would expand to an expression evaluating to false
43 (for instance, the token 0) to indicate that the corresponding compiler is not
45 * "Null values" could be set, for all macros, in
46 boost/config/select_compiler.hpp; then, for each compiler the corresponding
47 identification macro would be #undef and re-#defined in the corresponding
48 boost/compiler/(cc).hpp; however in the context of the Boost.Config
49 infrastructure using a "prefix" header (to be introduced) or
50 boost/config/suffix.hpp is a better solution.
52 [heading Current Library]
54 The current Predef library is now, both an independent library, and expanded
55 in scope. It includes detection and definition of architectures, compilers,
56 languages, libraries, operating systems, and endianness. The key benefits are:
58 * Version numbers that are always defined so that one doesn't have to guard
60 * Guard macros that can be used for `#ifdef` checks.
61 * All possible definitions are included with the single `#include <boost/predef.h>`
62 so that it's friendly to precompiled header usage.
63 * Specific definitions can be included, ex. `#include <boost/predef/os/windows.h>`
65 * Predefs can be directly used in both preprocessor and compiler expressions
66 for comparison to other similarly defined values.
67 * The headers are usable from multiple languages, that support the C preprocessor.
68 In particular C++, C, Objective C, and Objective C++.
70 [heading Design choices]
72 An important design choice concerns how to represent compiler versions by means
73 of a single integer number suitable for use in preprocessing directives. Let's
74 do some calculation. The "basic" signed type for preprocessing
75 constant-expressions is long in C90 (and C++, as of 2006) and intmax_t in C99.
76 The type long shall at least be able to represent the number [^+2 147 483 647].
77 This means the most significant digit can only be 0, 1 or 2; and if we want all
78 decimal digits to be able to vary between 0 and 9, the largest range we can
79 consider is [^\[0, 999 999 999\]]. Distributing evenly, this means 3 decimal
80 digits for each version number part.
84 # use an uneven distribution or
85 # use more bits (a larger type) or
86 # use 3/3/3 and have the particular compiler/platform/stdlib deal with setting
87 the numbers within the 3-digit range.
89 It appears relatively safe to go for the first option and set it at 2/2/5. That
90 covers CodeWarrior and others, which are up to and past 10 for the major number.
91 Some compilers use the build number in lieu of the patch one; five digits
92 (which is already reached by VC++ 8) seems a reasonable limit even in this case.
94 [note A 2/2/6 scheme would allow for bigger patch/build numbers at the cost,
95 for instance, of limiting the major version number to 20 (or, with further
98 It might reassure the reader that this decision is actually encoded in one place
99 in the code; the definition of `BOOST_VERSION_NUMBER`.
101 [heading Future work]
103 Even though the basics of this library are done, there is much work that can be
106 * Right now we limit the detection of libraries to known built-in predefined
107 macros, and to guaranteed to exist system and library headers. It might be
108 interesting to add something like auto-configuration predefs. This way we can
109 add definitions for user specific libraries and features.
110 * Along with the above, it might be good to add some user control as to which
111 headers are included with the top-level header. Although in the current
112 form of the library this is less of an issue as one can include the
113 specific headers one needs.
114 * Additionally, even if there is no auto-configure style option.. It would be
115 good to add optionally included headers so that user can get consistent
116 version number definitions for libraries they use.
117 * Having a consistent set of version number definitions opens the door to
118 improving the user level syntax of libraries that do checks against version
119 numbers. Specifically Boost Config's `BOOST_WORKAROUND` macro would benefit
120 from a more readable syntax. As would the `BOOST_TESTED_AT` detail macro.
121 * And obviously there's lots of work to do in reformulating the existing
122 Boost libraries to use the Predef library once it's accepted.
123 * And there's the continuing work of adding definitions for present and
124 future compilers, platforms, architectures, languages, and libraries.
126 [endsect] [/Introduction]
128 [section Using the predefs]
130 To use the automatically defined predefs one needs to only include the
131 single top-level header:
134 #include <boost/predef.h>
137 This defines [*all] the version macros known to the library. For each
138 macro it will be defined to either a /zero/ valued expression for when
139 the particular item is not detected, and to a /positive/ value if it
140 is detected. The predef macros fall onto five categories each with
141 macros of a particular prefix:
143 * `BOOST_ARCH_`for system/CPU architecture one is compiling for.
144 * `BOOST_COMP_` for the compiler one is using.
145 * `BOOST_LANG_` for language standards one is compiling against.
146 * `BOOST_LIB_C_` and `BOOST_LIB_STD_` for the C and C++ standard library
148 * `BOOST_OS_` for the operating system we are compiling to.
149 * `BOOST_PLAT_` for platforms on top of operating system or compilers.
150 * `BOOST_ENDIAN_` for endianness of the os and architecture combination.
151 * `BOOST_HW_` for hardware specific features.
152 * `BOOST_HW_SIMD` for SIMD (Single Instruction Multiple Data) detection.
154 [note The detected definitions are for the configuration one is targeting
155 during the compile. In particular in a cross-compile this means the target
156 system, and not the host system.]
158 One uses the individual definitions to compare against specific versions
159 by comparing against the `BOOST_VERSION_NUMBER` macro. For example, to make
160 a choice based on the version of the GCC C++ compiler one would:
163 #include <boost/predef.h>
168 if (BOOST_COMP_GNUC >= BOOST_VERSION_NUMBER(4,0,0))
169 std::cout << "GCC compiler is at least version 4.0.0" << std::endl;
171 std::cout << "GCC compiler is at older than version 4.0.0, or not a GCC compiler" << std::endl;
176 As you might notice above the `else` clause also covers the case where
177 the particular compiler is not detected. But one can make the test
178 also test for the detection. All predef definitions are defined
179 as a zero (0) expression when not detected. Hence one could use the
180 detection with a natural single condition. For example:
183 #include <boost/predef.h>
189 std::cout << "This is GNU GCC!" << std::endl;
191 std::cout << "Not GNU GCC." << std::endl;
196 And since the predef's are preprocessor definitions the same is possible
197 from the preprocessor:
200 #include <boost/predef.h>
204 #if BOOST_COMP_GNUC >= BOOST_VERSION_NUMBER(4,0,0)
205 const char * the_compiler = "GNU GCC, of at least version 4."
207 const char * the_compiler = "GNU GCC, less than version 4."
210 const char * the_compiler = "Not GNU GCC."
215 std::cout << the_compiler << std::endl;
220 In addition, for each version macro defined there is an
221 `*_AVAILABLE` macro defined only when the particular aspect is
222 detected. I.e. a definition equivalent to:
226 #define BOOST_PREDEF_ABC_AVAILABLE
230 Also for each aspect there is a macro defined with a descriptive
231 name of what the detection is.
233 [heading The `*_EMULATED` macros]
235 Predef definitions are guaranteed to be uniquely detected within one category.
236 But there are contexts under which multiple underlying detections are possible.
237 The well known example of this is detection of GCC and MSVC compilers which are
238 commonly emulated by other compilers by defining the same base macros. To
239 account for this detection headers are allowed to define `*_EMULATED` predefs
240 when this situation is detected. The emulated predefs will be set to the
241 version number of the detection instead of the regular predef macro for that
242 detection. For example MSVC will set `BOOST_COMP_MSVC_EMULATED` but not set `BOOST_COM_MSVC`, and it will also set `BOOST_COMP_MSVC_AVAILABLE`.
244 [heading Using the `BOOST_VERSION_NUMBER` macro]
246 All the predefs are defined to be a use of the `BOOST_VERSION_NUMBER` macro.
247 The macro takes individual major, minor, and patch value expressions:
250 #define BOOST_VERSION_NUMBER( major, minor, patch ) ...
255 # Major version number, as a constant value expression in the range [0,99].
256 # Minor version number, as a constant value expression in the range [0,99].
257 # Patch-level version number, as a constant value expression in the
260 The ranges for each are "enforced" by the use of a modulo ("%"), i.e. truncation,
261 as opposed to a clamp. And hence this means that the limits are enforced only
262 enough to keep from having out-of-range problems. But not enough to prevent
263 other kinds of problems. Like exceeding the range and getting false detections,
264 or non-detections. It is up to the individual predefs to ensure correct
265 usage beyond the range guarantee.
267 The values for the arguments can be any preprocessor valid constant value expression.
268 Only constant value arithmetic is used in the definition of the `BOOST_VERSION_NUMBER`
269 macro and in any of the other predef macros. This means that any allowed base is
270 possible, i.e. binary, octal, decimal, and hexadecimal. For example:
273 #define MY_APPLICATION_VERSION_NUMBER BOOST_VERSION_NUMBER(2,0xA,015)
279 #define MY_APPLICATION_VERSION_NUMBER BOOST_VERSION_NUMBER(2,10,13)
284 [section Adding new predefs]
286 We know that a library like this one will be an eternal work-in-progress. And
287 as such we expect, and look forward to, others contributing corrections and
288 additions to the predefs. With that in mind we need to keep a consistent way
289 of defining the new predefs. Hence all current, and future, predefs follow
290 the same structure and requirements.
292 [heading Requirements of the header]
294 All predefs need to follow a set of requirements:
296 * The headers must use the Boost Software License.
297 * The predef must, by default, be defined as `BOOST_VERSION_NUMBER_NOT_AVAILABLE`.
298 * The predef must be redefined to a non-zero value once detected.
299 * The predef must, by default, be defined to `BOOST_VERSION_NUMBER_AVAILABLE`
300 when the predef is detected.
301 * If possible, the predef will be defined as the version number detected.
302 * The predef must define `*_AVAILABLE` macros as needed.
303 * The predef must define a symbolic constant string name macro.
304 * The predef must declare itself, after being defined, for the testing
306 * The predef must guarantee that it is the only one defined as detected
308 * But a predef can define `*_EMULATED` macros to indicate that it was
309 previously detected by another header and is being "emulated" by the
310 system. Note that the `*_AVAILABLE` macros must still be defined in this
313 And there are some extra guidelines that predef headers should follow:
315 * The detection should avoid including extra headers that might otherwise
316 not be included by default.
317 * If the detection must include a header, prefer guarding it within the
318 detection if possible.
319 * If the detection must include headers unconditionally, and has a choice
320 of headers to include, prefer the ones with the least impact. I.e.
321 include the one with the minimal set of definitions and other
324 [heading Structure of the header]
326 For general consistency it's suggested that new predef headers follow the
327 structure below, as current predef headers do. First we have the copyright
328 and license statement, followed by the include guard:
332 Copyright Jane Doe YYYY
333 Distributed under the Boost Software License, Version 1.0.
334 (See accompanying file LICENSE_1_0.txt or copy at
335 http://www.boost.org/LICENSE_1_0.txt)
338 #ifndef BOOST_PREDEF_category_tag_H
339 #define BOOST_PREDEF_category_tag_H
342 If the detection depends on the detection of another predef you should
343 include those headers here.
346 #include <boost/predef/CATEGORY_TAG/DEPENDENCY.h>
349 Depending on how you are defining the predef you will at minimum have
350 to include the `version_number.h` header. But you might also want to
351 include the `make.h` header for the version number decomposing utility
355 #include <boost/predef/version_number.h>
356 #include <boost/predef/make.h>
359 The Predef library uses Quickbook for documentation and for the
360 individual predefs to appear in the reference section we add in-code
361 documentation followed by the zero-value default definition of the
362 predef macro. We strongly recommend this particular placement of the
363 documentation and default definition because some development
364 environments automatically interpret this and provide in-line help
365 for the macro. In particular this works for the popular Eclipse IDE:
369 [heading `BOOST_category_tag`]
371 Documentation about what is detected.
374 #define BOOST_category_tag BOOST_VERSION_NUMBER_NOT_AVAILABLE
377 Next is the detection and definition of the particular predef. The
378 structure for this is to do a single overall check (`condition_a`) and
379 place further version detection inside this. The first action inside
380 the overall check is to "`#undef BOOST_category_tag`" which undefines
381 the zero-value default. The rest is up to the you how to do the checks
382 for defining the version. But at minimum it must
383 "`#define BOOST_category_tag BOOST_VERSION_NUMBER_AVAILABLE`" as the fallback
384 to minimally indicate that the predef was detected:
388 # undef BOOST_category_tag
390 # define BOOST_category_tag BOOST_VERSION_NUMBER(major,minor,patch)
392 # define BOOST_category_tag BOOST_VERSION_NUMBER_AVAILABLE
397 We also need to provide the `*_AVAILABLE` versions of the predef.
400 #if BOOST_category_tag
401 # define BOOST_category_tag_AVAILABLE
405 And for convenience we also want to provide a `*_NAME` macro:
408 #define BOOST_catagory_tag_NAME "Name"
411 The testing of the predef macros is automated to generate checks for all
412 the defined predefs, whether detected or not. To do this we need to
413 declare the predef to the test system. This declaration is empty for
414 regular use. And during the test programs they expand out specially
415 to create informational output:
418 #include <boost/predef/detail/test.h>
419 BOOST_PREDEF_DECLARE_TEST(BOOST_category_tag,BOOST_category_tag_NAME)
422 And, of course, we last need to close out the include guard:
428 [heading Adding exclusive predefs]
430 For headers of predefs that need to be mutually exclusive in the detection
431 we need to add checks and definitions to detect when the predef is
432 detected by multiple headers.
434 Internally compiler, operating system, and platforms define
435 `BOOST_PREDEF_DETAIL_COMP_DETECTED`, `BOOST_PREDEF_DEFAIL_OS_DETECTED`, and
436 `BOOST_PREDEF_DETAIL_PLAT_DETECTED` respectively when the predef is first
437 detected. This is used to guard against multiple definition of the detection
438 in later included headers. In those cases the detection would instead be
442 #if !BOOST_PREDEF_DETAIL_category_DETECTED && (condition_a)
443 # undef BOOST_category_tag
445 # define BOOST_category_tag BOOST_VERSION_NUMBER(major,minor,patch)
447 # define BOOST_category_tag BOOST_VERSION_NUMBER(0,0,1)
452 And we also include a header that defines the `*_DETECTED` macro when we have
456 #if BOOST_category_tag
457 # define BOOST_category_tag_AVAILABLE
458 # include <boost/predef/detail/CATEGORY_detected.h>
462 Everything else about the header is the same as the basic detection header.
464 [heading Adding an exclusive but emulated predef]
466 Because compilers are frequently emulated by other compilers we both want
467 to have exclusive detection of the compiler and also provide information
468 that we detected the emulation of the compiler. To accomplish this we define
469 a local `*_DETECTION` macro for the compiler detection. And conditionally
470 define either the base compiler predef `BOOST_COMP_compiler` or the alternate
471 `BOOST_COMP_compiler_EMULATED` predef.
473 The initial detection would look like:
478 # define BOOST_COMP_tag_DETECTION BOOST_VERSION_NUMBER(major,minor,patch)
480 # define BOOST_COMP_tag_DETECTION BOOST_VERSION_NUMBER_AVAILABLE
485 And then we can conditionally define the base or emulated predefs:
488 #ifdef BOOST_COMP_tag_DETECTION
489 # if defined(BOOST_PREDEF_DETAIL_COMP_DETECTED)
490 # define BOOST_COMP_tag_EMULATED BOOST_COMP_tag_DETECTION
492 # undef BOOST_COMP_tag
493 # define BOOST_COMP_tag BOOST_COMP_tag_DETECTION
495 # define BOOST_category_tag_AVAILABLE
496 # include <boost/predef/detail/comp_detected.h>
500 [heading Using utility pattern macros]
505 #include <boost/predef/make.h>
508 One will get a set of utility macros to decompose common version
509 macros as defined by compilers. For example the EDG compiler
510 uses a simple 3-digit version macro (M,N,P). It can be decomposed
514 #define BOOST_CCOMP_EDG BOOST_PREDEF_MAKE_N_N_N(__EDG_VERSION__)
517 The decomposition macros are split into three types: decimal
518 decomposition, hexadecimal decomposition, and date decomposition.
519 They follow the format of using "N" for decimal, "F" for hexadecimal,
520 and "Y", "M", "D" for dates.
524 [def __predef_symbol__ Symbol]
525 [def __predef_version__ Version]
526 [def __predef_detection__ *detection*]
530 [section `BOOST_ARCH` architecture macros]
531 [include ../include/boost/predef/architecture/*.h]
532 [include ../include/boost/predef/architecture/x86/*.h]
535 [section `BOOST_COMP` compiler macros]
536 [include ../include/boost/predef/compiler/*.h]
539 [section `BOOST_LANG` language standards macros]
540 [include ../include/boost/predef/language/*.h]
543 [section `BOOST_LIB` library macros]
544 [include ../include/boost/predef/library/c/*.h]
545 [include ../include/boost/predef/library/std/*.h]
548 [section `BOOST_OS` operating system macros]
549 [include ../include/boost/predef/os/*.h]
550 [include ../include/boost/predef/os/bsd/*.h]
553 [section `BOOST_PLAT` platform macros]
554 [include ../include/boost/predef/platform/*.h]
557 [section `BOOST_HW` hardware macros]
558 [include ../include/boost/predef/hardware/*.h]
561 [section Other macros]
562 [include ../include/boost/predef/other/*.h]
565 [section Version definition macros]
566 [include ../include/boost/predef/version_number.h]
567 [include ../include/boost/predef/make.h]
572 [section Check Utilities]
574 The `predef_check` utility provides a facility for building a
575 program that will check a given set of expressions against
576 the definitions it detected when it was built.
578 [heading [^predef_check] programs]
580 Even though there is only one `predef_check` program, there
581 are variations for each of the languages that are detected
582 by Predef to match the convention for sources files. For all
583 of them one invokes with a list of expression arguments. The
584 expressions are evaluated within the context of the particular
585 [^predef_check] program and if they all are true zero (0) is returned.
586 Otherwise the index of the first false expression is returned.
588 The expression syntax is simple:
592 predef-definition [ relational-operator version-value ]
596 [~predef-definition] can be any of the Predef definitions. For
597 example `BOOST_COMP_GCC`.
599 [~relational-operator] can be any of: [^>], [^<], [^>=], [^<=],
602 [~version-number] can be a full or partial version triplet value.
603 If it's a partial version triple it is completed with zeros. That
604 is [^x.y] is equivalent to [^x.y.0] and [^x] is equivalent to
607 The [~relations-operator] and [~version-number] can be ommited. In
608 which case it is equivalent to:
612 predef-definition > 0.0.0
616 [heading Using with Boost.Build]
618 You can use the [^predef_check] programs directly from Boost Build
619 to configure target requirements. This is useful for controlling
620 what gets built as part of your project based on the detailed
621 version information available in Predef. The basic use is simple:
625 import path-to-predef-src/tools/check/predef
627 : predef-check predef-require ;
629 exe my_windows_program : windows_source.cpp
630 : [ predef-require "BOOST_OS_WINDOWS" ] ;
634 That simple use case will skip building the [^my_windows_program]
635 unless one is building for Windows. Like the direct [^predef_check]
636 you can pass mutiple expressions using relational comparisons.
641 import path-to-predef-src/tools/check/predef
643 : predef-check predef-require ;
645 lib my_special_lib : source.cpp
646 : [ predef-require "BOOST_OS_WINDOWS != 0" "BOOST_OS_VMS != 0"] ;
650 And in that case the [^my_special_lib] is built only when the OS is
651 not Windows or VMS. The [^requires] rule is a special case of the
652 [^check] rule. And is defined in terms of it:
656 rule require ( expressions + : language ? )
658 return [ check $(expressions) : $(language) : : <build>no ] ;
663 The expression can also use explicit "and", "or" logical operators
664 to for more complex checks:
669 import path-to-predef-src/tools/check/predef
671 : predef-check predef-require ;
673 lib my_special_lib : source.cpp
674 : [ predef-require "BOOST_OS_WINDOWS" or "BOOST_OS_VMS"] ;
678 You can use the [^check] rule for more control and to implement
679 something other than control of what gets built. The definition
680 for the [^check] rule is:
684 rule check ( expressions + : language ? : true-properties * : false-properties * )
688 When invoked as a reuirement of a Boost Build target this rule
689 will add the [^true-properties] to the target if all the [^expressions]
690 evaluate to true. Otherwise the [^false-properties] get added as
691 requirements. For example you could use it to enable or disable
692 features in your programs:
696 import path-to-predef-src/tools/check/predef
698 : predef-check predef-require ;
700 exe my_special_exe : source.cpp
701 : [ predef-check "BOOST_OS_WINDOWS == 0"
702 : : <define>ENABLE_WMF=0
703 : <define>ENABLE_WMF=1 ] ;
707 For both [^check] and [^require] the [^language] argument controls
708 which variant of the [^predef_check] program is used to check the
709 expressions. It defaults to "c++", but can be any of: "c", "cpp",
710 "objc", and "objcpp".
714 [include history.qbk]
717 [section Acknoledgements]
719 The comprehensiveness of this library would not be
720 possible without the existence of the indispensable
722 [@http://sourceforge.net/p/predef/ Pre-defined C/C++ Compiler Macros]
723 Project. It was, and continues to be, the primary source
724 of the definitions that make up this library. Thanks
725 to Bjorn Reese and all the volunteers that make that
728 This library would be an incoherent mess if it weren't for
729 Boost community that provided invaluable feedback for the
730 eight years that it took to polish into a useable form.
731 In particular I would like to thank: Mathias Gaunard,
732 Robert Stewart, Joël Lamotte, Lars Viklund, Nathan Ridge,
733 Artyom Beilis, Joshua Boyce, Gottlob Frege, Thomas Heller,
734 Edward Diener, Dave Abrahams, Iain Denniston, Dan Price,
735 Ioannis Papadopoulos, and Robert Ramey. And thanks to
736 Joel Falcou for managing the review of this library.