1= Boost.Predef 2:author: Rene Rivera 3:toc: left 4:toclevels: 3 5:sectanchors: 6:sectnums: 7:nofooter: 8:source-highlighter: pygments 9:source-language: cpp 10:caution-caption: ⚑ 11:important-caption: ‼ 12:note-caption: ℹ 13:tip-caption: ☀ 14:warning-caption: ⚠ 15:CPP: C++ 16:predef_symbol: Symbol 17:predef_version: Version 18:predef_detection: pass:q[*detection*] 19 20ifdef::backend-html5[] 21++++ 22<style> 23include::predef.css[] 24</style> 25++++ 26endif::[] 27 28== Introduction 29 30This library defines a set of compiler, architecture, operating system, 31library, and other version numbers from the information it can gather of 32C, {CPP}, Objective C, and Objective {CPP} predefined macros or those defined 33in generally available headers. The idea for this library grew out of a 34proposal to extend the Boost Config library to provide more, and consistent, 35information than the feature definitions it supports. What follows is 36an edited version of that brief proposal. 37 38=== Proposal 39 40The idea is to define a set of macros to identify compilers and 41consistently represent their version. This includes: 42 43* A unique BOOST_VERSION_NUMBER(major,minor,patch) macro to specify version 44 numbers (unfortunately, the name BOOST_VERSION is already taken to designate 45 the version number of boost itself). 46* A compiler identification macro, suitable for use in `#if`/`#elif` directives, 47 for each of the supported compilers. All macros would be defined, regardless 48 of the compiler. The one macro corresponding to the compiler being used would 49 be defined, in terms of BOOST_VERSION_NUMBER, to carry the exact compiler 50 version. All other macros would expand to an expression evaluating to false 51 (for instance, the token 0) to indicate that the corresponding compiler is not 52 present. 53* "Null values" could be set, for all macros, in 54 boost/config/select_compiler.hpp; then, for each compiler the corresponding 55 identification macro would be #undef and re-#defined in the corresponding 56 boost/compiler/(cc).hpp; however in the context of the Boost.Config 57 infrastructure using a "prefix" header (to be introduced) or 58 boost/config/suffix.hpp is a better solution. 59 60=== Current Library 61 62The current Predef library is now, both an independent library, and expanded 63in scope. It includes detection and definition of architectures, compilers, 64languages, libraries, operating systems, and endianness. The key benefits are: 65 66* Version numbers that are always defined so that one doesn't have to guard 67 with `#ifdef`. 68* Guard macros that can be used for `#ifdef` checks. 69* All possible definitions are included with the single `#include <boost/predef.h>` 70 so that it's friendly to pre-compiled header usage. 71* Specific definitions can be included, ex. `#include <boost/predef/os/windows.h>` 72 for single checks. 73* Predefs can be directly used in both preprocessor and compiler expressions 74 for comparison to other similarly defined values. 75* The headers are usable from multiple languages, that support the C preprocessor. 76 In particular {CPP}, C, Objective C, and Objective {CPP}. 77 78=== Design choices 79 80An important design choice concerns how to represent compiler versions by means 81of a single integer number suitable for use in preprocessing directives. Let's 82do some calculation. The "basic" signed type for preprocessing 83constant-expressions is long in C90 (and {CPP}, as of 2006) and intmax_t in C99. 84The type long shall at least be able to represent the number `+2 147 483 647`. 85This means the most significant digit can only be 0, 1 or 2; and if we want all 86decimal digits to be able to vary between 0 and 9, the largest range we can 87consider is `[0, 999 999 999\`]. Distributing evenly, this means 3 decimal 88digits for each version number part. 89 90So we can: 91 92. use an uneven distribution or 93. use more bits (a larger type) or 94. use 3/3/3 and have the particular compiler/platform/stdlib deal with setting 95 the numbers within the 3-digit range. 96 97It appears relatively safe to go for the first option and set it at 2/2/5. That 98covers CodeWarrior and others, which are up to and past 10 for the major number. 99Some compilers use the build number in lieu of the patch one; five digits 100(which is already reached by V{CPP} 8) seems a reasonable limit even in this case. 101 102NOTE: A 2/2/6 scheme would allow for bigger patch/build numbers at the cost, 103for instance, of limiting the major version number to 20 (or, with further 104constraints, to 21). 105 106It might reassure the reader that this decision is actually encoded in one place 107in the code; the definition of `BOOST_VERSION_NUMBER`. 108 109=== Future work 110 111Even though the basics of this library are done, there is much work that can be 112done: 113 114* Right now we limit the detection of libraries to known built-in predefined 115 macros, and to guaranteed to exist system and library headers. It might be 116 interesting to add something like auto-configuration predefs. This way we can 117 add definitions for user specific libraries and features. 118* Along with the above, it might be good to add some user control as to which 119 headers are included with the top-level header. Although in the current 120 form of the library this is less of an issue as one can include the 121 specific headers one needs. 122* Additionally, even if there is no auto-configure style option.. It would be 123 good to add optionally included headers so that user can get consistent 124 version number definitions for libraries they use. 125* And obviously there's lots of work to do in reformulating the existing 126 Boost libraries to use the Predef library. 127* And there's the continuing work of adding definitions for present and 128 future compilers, platforms, architectures, languages, and libraries. 129 130 131== Using the predefs 132 133To use the automatically defined predefs one needs to only include the 134single top-level header: 135 136[source] 137---- 138#include <boost/predef.h> 139---- 140 141This defines [*all] the version macros known to the library. For each 142macro it will be defined to either a`_zero_`valued expression for when 143the particular item is not detected, and to a`_positive_`value if it 144is detected. The predef macros fall onto five categories each with 145macros of a particular prefix: 146 147* `BOOST_ARCH_` for system/CPU architecture one is compiling for. 148* `BOOST_COMP_` for the compiler one is using. 149* `BOOST_LANG_` for language standards one is compiling against. 150* `BOOST_LIB_C_` and `BOOST_LIB_STD_` for the C and {CPP} standard library 151 in use. 152* `BOOST_OS_` for the operating system we are compiling to. 153* `BOOST_PLAT_` for platforms on top of operating system or compilers. 154* `BOOST_ENDIAN_` for endianness of the os and architecture combination. 155* `BOOST_HW_` for hardware specific features. 156* `BOOST_HW_SIMD` for SIMD (Single Instruction Multiple Data) detection. 157 158NOTE: The detected definitions are for the configuration one is targeting 159during the compile. In particular in a cross-compile this means the target 160system, and not the host system. 161 162One uses the individual definitions to compare against specific versions 163by comparing against the `BOOST_VERSION_NUMBER` macro. For example, to make 164a choice based on the version of the GCC {CPP} compiler one would: 165 166[source] 167---- 168#include <boost/predef.h> 169#include <iostream> 170 171int main() 172{ 173 if (BOOST_COMP_GNUC >= BOOST_VERSION_NUMBER(4,0,0)) 174 std::cout << "GCC compiler is at least version 4.0.0" << std::endl; 175 else 176 std::cout << "GCC compiler is at older than version 4.0.0, or not a GCC compiler" << std::endl; 177 return 0; 178} 179---- 180 181As you might notice above the `else` clause also covers the case where 182the particular compiler is not detected. But one can make the test 183also test for the detection. All predef definitions are defined 184as a zero (0) expression when not detected. Hence one could use the 185detection with a natural single condition. For example: 186 187[source] 188---- 189#include <boost/predef.h> 190#include <iostream> 191 192int main() 193{ 194 if (BOOST_COMP_GNUC) 195 std::cout << "This is GNU GCC!" << std::endl; 196 else 197 std::cout << "Not GNU GCC." << std::endl; 198 return 0; 199} 200---- 201 202And since the predef's are preprocessor definitions the same is possible 203from the preprocessor: 204 205[source] 206---- 207#include <boost/predef.h> 208#include <iostream> 209 210#if BOOST_COMP_GNUC 211 #if BOOST_COMP_GNUC >= BOOST_VERSION_NUMBER(4,0,0) 212 const char * the_compiler = "GNU GCC, of at least version 4." 213 #else 214 const char * the_compiler = "GNU GCC, less than version 4." 215 #endif 216#else 217 const char * the_compiler = "Not GNU GCC." 218#endif 219 220int main() 221{ 222 std::cout << the_compiler << std::endl; 223 return 0; 224} 225---- 226 227In addition, for each version macro defined there is an 228`*_AVAILABLE` macro defined only when the particular aspect is 229detected. I.e. a definition equivalent to: 230 231[source] 232---- 233#if BOOST_PREDEF_ABC 234 #define BOOST_PREDEF_ABC_AVAILABLE 235#endif 236---- 237 238Also for each aspect there is a macro defined with a descriptive 239name of what the detection is. 240 241=== The `*_EMULATED` macros 242 243Predef definitions are guaranteed to be uniquely detected within one category. 244But there are contexts under which multiple underlying detections are possible. 245The well known example of this is detection of GCC and MSVC compilers which are 246commonly emulated by other compilers by defining the same base macros. To 247account for this detection headers are allowed to define `*_EMULATED` predefs 248when this situation is detected. The emulated predefs will be set to the 249version number of the detection instead of the regular predef macro for that 250detection. For example MSVC will set `BOOST_COMP_MSVC_EMULATED` but not set `BOOST_COMP_MSVC`, and it will also set `BOOST_COMP_MSVC_AVAILABLE`. 251 252=== Using the `BOOST_VERSION_NUMBER` macro 253 254All the predefs are defined to be a use of the `BOOST_VERSION_NUMBER` macro. 255The macro takes individual major, minor, and patch value expressions: 256 257[source] 258---- 259#define BOOST_VERSION_NUMBER( major, minor, patch ) ... 260---- 261 262The arguments are: 263 264. Major version number, as a constant value expression in the range [0,99]. 265. Minor version number, as a constant value expression in the range [0,99]. 266. Patch-level version number, as a constant value expression in the 267 range [0,99999]. 268 269The ranges for each are "enforced" by the use of a modulo ("%"), i.e. truncation, 270as opposed to a clamp. And hence this means that the limits are enforced only 271enough to keep from having out-of-range problems. But not enough to prevent 272other kinds of problems. Like exceeding the range and getting false detections, 273or non-detections. It is up to the individual predefs to ensure correct 274usage beyond the range guarantee. 275 276The values for the arguments can be any preprocessor valid constant value expression. 277Only constant value arithmetic is used in the definition of the `BOOST_VERSION_NUMBER` 278macro and in any of the other predef macros. This means that any allowed base is 279possible, i.e. binary, octal, decimal, and hexadecimal. For example: 280 281[source] 282---- 283#define MY_APPLICATION_VERSION_NUMBER BOOST_VERSION_NUMBER(2,0xA,015) 284---- 285 286Is equivalent to: 287 288[source] 289---- 290#define MY_APPLICATION_VERSION_NUMBER BOOST_VERSION_NUMBER(2,10,13) 291---- 292 293 294== Adding new predefs 295 296We know that a library like this one will be an eternal work-in-progress. And 297as such we expect, and look forward to, others contributing corrections and 298additions to the predefs. With that in mind we need to keep a consistent way 299of defining the new predefs. Hence all current, and future, predefs follow 300the same structure and requirements. 301 302=== Requirements of the header 303 304All predefs need to follow a set of requirements: 305 306* The headers must use the Boost Software License. 307* The predef must, by default, be defined as `BOOST_VERSION_NUMBER_NOT_AVAILABLE`. 308* The predef must be redefined to a non-zero value once detected. 309* The predef must, by default, be defined to `BOOST_VERSION_NUMBER_AVAILABLE` 310 when the predef is detected. 311* If possible, the predef will be defined as the version number detected. 312* The predef must define `*_AVAILABLE` macros as needed. 313* The predef must define a symbolic constant string name macro. 314* The predef must declare itself, after being defined, for the testing 315 system. 316* The predef must guarantee that it is the only one defined as detected 317 per category. 318* But a predef can define `*_EMULATED` macros to indicate that it was 319 previously detected by another header and is being "emulated" by the 320 system. Note that the `*_AVAILABLE` macros must still be defined in this 321 situation. 322 323And there are some extra guidelines that predef headers should follow: 324 325* The detection should avoid including extra headers that might otherwise 326 not be included by default. 327* If the detection must include a header, prefer guarding it within the 328 detection if possible. 329* If the detection must include headers unconditionally, and has a choice 330 of headers to include, prefer the ones with the least impact. I.e. 331 include the one with the minimal set of definitions and other 332 dependencies. 333 334=== Structure of the header 335 336For general consistency it's suggested that new predef headers follow the 337structure below, as current predef headers do. First we have the copyright 338and license statement, followed by the include guard: 339 340[source] 341---- 342/* 343Copyright Jane Doe YYYY 344Distributed under the Boost Software License, Version 1.0. 345(See accompanying file LICENSE_1_0.txt or copy at 346http://www.boost.org/LICENSE_1_0.txt) 347*/ 348 349#ifndef BOOST_PREDEF_category_tag_H 350#define BOOST_PREDEF_category_tag_H 351---- 352 353If the detection depends on the detection of another predef you should 354include those headers here. 355 356[source] 357---- 358#include <boost/predef/CATEGORY_TAG/DEPENDENCY.h> 359---- 360 361Depending on how you are defining the predef you will at minimum have 362to include the `version_number.h` header. But you might also want to 363include the `make.h` header for the version number decomposing utility 364macros: 365 366[source] 367---- 368#include <boost/predef/version_number.h> 369#include <boost/predef/make.h> 370---- 371 372The Predef library uses https://asciidoctor.org/[Asciidoctor] for documentation 373and for the individual predefs to appear in the reference section we add 374in-code documentation followed by the zero-value default definition of the 375predef macro. We strongly recommend this particular placement of the 376documentation and default definition because some development 377environments automatically interpret this and provide in-line help 378for the macro. In particular this works for the popular Eclipse IDE: 379 380[source] 381---- 382/* tag::reference[] 383 384= `BOOST_category_tag` 385 386Documentation about what is detected. 387 388*/ 389 390#define BOOST_category_tag BOOST_VERSION_NUMBER_NOT_AVAILABLE 391---- 392 393Next is the detection and definition of the particular predef. The 394structure for this is to do a single overall check (`condition_a`) and 395place further version detection inside this. The first action inside 396the overall check is to "`#undef BOOST_category_tag`" which removes 397the zero-value default. The rest is up to the you how to do the checks 398for defining the version. But at minimum it must 399"`#define BOOST_category_tag BOOST_VERSION_NUMBER_AVAILABLE`" as 400the fallback to minimally indicate that the predef was detected: 401 402[source] 403---- 404#if (condition_a) 405# undef BOOST_category_tag 406# if (condition_b) 407# define BOOST_category_tag BOOST_VERSION_NUMBER(major,minor,patch) 408# else 409# define BOOST_category_tag BOOST_VERSION_NUMBER_AVAILABLE 410# endif 411#endif 412---- 413 414We also need to provide the `*_AVAILABLE` versions of the predef. 415 416[source] 417---- 418#if BOOST_category_tag 419# define BOOST_category_tag_AVAILABLE 420#endif 421---- 422 423And for convenience we also want to provide a `*_NAME` macro: 424 425[source] 426---- 427#define BOOST_category_tag_NAME "Name" 428---- 429 430We close out the include guard at this point. We do whis before the test 431declaration as the testing system includes the headers multiple times 432to generate the needed testing code. 433 434[source] 435---- 436#endif 437---- 438 439The testing of the predef macros is automated to generate checks for all 440the defined predefs, whether detected or not. To do this we need to 441declare the predef to the test system. This declaration is empty for 442regular use. And during the test programs they expand out specially 443to create informational output: 444 445[source] 446---- 447#include <boost/predef/detail/test.h> 448BOOST_PREDEF_DECLARE_TEST(BOOST_category_tag,BOOST_category_tag_NAME) 449---- 450 451=== Adding exclusive predefs 452 453For headers of predefs that need to be mutually exclusive in the detection 454we need to add checks and definitions to detect when the predef is 455detected by multiple headers. 456 457Internally compiler, operating system, and platforms define 458`BOOST_PREDEF_DETAIL_COMP_DETECTED`, `BOOST_PREDEF_DEFAIL_OS_DETECTED`, and 459`BOOST_PREDEF_DETAIL_PLAT_DETECTED` respectively when the predef is first 460detected. This is used to guard against multiple definition of the detection 461in later included headers. In those cases the detection would instead be 462written as: 463 464[source] 465---- 466#if !BOOST_PREDEF_DETAIL_category_DETECTED && (condition_a) 467# undef BOOST_category_tag 468# if (condition_b) 469# define BOOST_category_tag BOOST_VERSION_NUMBER(major,minor,patch) 470# else 471# define BOOST_category_tag BOOST_VERSION_NUMBER(0,0,1) 472# endif 473#endif 474---- 475 476And we also include a header that defines the `*_DETECTED` macro when we have 477the detection: 478 479[source] 480---- 481#if BOOST_category_tag 482# define BOOST_category_tag_AVAILABLE 483# include <boost/predef/detail/CATEGORY_detected.h> 484#endif 485---- 486 487Everything else about the header is the same as the basic detection header. 488 489=== Adding an exclusive but emulated predef 490 491Because compilers are frequently emulated by other compilers we both want 492to have exclusive detection of the compiler and also provide information 493that we detected the emulation of the compiler. To accomplish this we define 494a local `*_DETECTION` macro for the compiler detection. And conditionally 495define either the base compiler predef `BOOST_COMP_compiler` or the alternate 496`BOOST_COMP_compiler_EMULATED` predef. 497 498The initial detection would look like: 499 500[source] 501---- 502#if (condition_a) 503# if (condition_b) 504# define BOOST_COMP_tag_DETECTION BOOST_VERSION_NUMBER(major,minor,patch) 505# else 506# define BOOST_COMP_tag_DETECTION BOOST_VERSION_NUMBER_AVAILABLE 507# endif 508#endif 509---- 510 511And then we can conditionally define the base or emulated predefs: 512 513[source] 514---- 515#ifdef BOOST_COMP_tag_DETECTION 516# if defined(BOOST_PREDEF_DETAIL_COMP_DETECTED) 517# define BOOST_COMP_tag_EMULATED BOOST_COMP_tag_DETECTION 518# else 519# undef BOOST_COMP_tag 520# define BOOST_COMP_tag BOOST_COMP_tag_DETECTION 521# endif 522# define BOOST_category_tag_AVAILABLE 523# include <boost/predef/detail/comp_detected.h> 524#endif 525---- 526 527=== Using utility pattern macros 528 529By including: 530 531[source] 532---- 533#include <boost/predef/make.h> 534---- 535 536One will get a set of utility macros to decompose common version 537macros as defined by compilers. For example the EDG compiler 538uses a simple 3-digit version macro (M,N,P). It can be decomposed 539and defined as: 540 541[source] 542---- 543#define BOOST_COMP_EDG BOOST_PREDEF_MAKE_N_N_N(__EDG_VERSION__) 544---- 545 546The decomposition macros are split into three types: decimal 547decomposition, hexadecimal decomposition, and date decomposition. 548They follow the format of using "N" for decimal, "F" for hexadecimal, 549and "Y", "M", "D" for dates. 550 551 552 553== Reference 554 555=== `BOOST_ARCH` architecture macros 556 557:leveloffset: +3 558 559include::../include/boost/predef/architecture/alpha.h[tag=reference] 560 561include::../include/boost/predef/architecture/arm.h[tag=reference] 562 563include::../include/boost/predef/architecture/blackfin.h[tag=reference] 564 565include::../include/boost/predef/architecture/convex.h[tag=reference] 566 567include::../include/boost/predef/architecture/e2k.h[tag=reference] 568 569include::../include/boost/predef/architecture/ia64.h[tag=reference] 570 571include::../include/boost/predef/architecture/m68k.h[tag=reference] 572 573include::../include/boost/predef/architecture/mips.h[tag=reference] 574 575include::../include/boost/predef/architecture/parisc.h[tag=reference] 576 577include::../include/boost/predef/architecture/ppc.h[tag=reference] 578 579include::../include/boost/predef/architecture/ptx.h[tag=reference] 580 581include::../include/boost/predef/architecture/pyramid.h[tag=reference] 582 583include::../include/boost/predef/architecture/riscv.h[tag=reference] 584 585include::../include/boost/predef/architecture/rs6k.h[tag=reference] 586 587include::../include/boost/predef/architecture/sparc.h[tag=reference] 588 589include::../include/boost/predef/architecture/superh.h[tag=reference] 590 591include::../include/boost/predef/architecture/sys370.h[tag=reference] 592 593include::../include/boost/predef/architecture/sys390.h[tag=reference] 594 595include::../include/boost/predef/architecture/x86.h[tag=reference] 596 597include::../include/boost/predef/architecture/z.h[tag=reference] 598 599include::../include/boost/predef/architecture/x86/32.h[tag=reference] 600 601include::../include/boost/predef/architecture/x86/64.h[tag=reference] 602 603:leveloffset: -3 604 605=== `BOOST_COMP` compiler macros 606 607:leveloffset: +3 608 609include::../include/boost/predef/compiler/borland.h[tag=reference] 610 611include::../include/boost/predef/compiler/clang.h[tag=reference] 612 613include::../include/boost/predef/compiler/comeau.h[tag=reference] 614 615include::../include/boost/predef/compiler/compaq.h[tag=reference] 616 617include::../include/boost/predef/compiler/diab.h[tag=reference] 618 619include::../include/boost/predef/compiler/digitalmars.h[tag=reference] 620 621include::../include/boost/predef/compiler/dignus.h[tag=reference] 622 623include::../include/boost/predef/compiler/edg.h[tag=reference] 624 625include::../include/boost/predef/compiler/ekopath.h[tag=reference] 626 627include::../include/boost/predef/compiler/gcc.h[tag=reference] 628 629include::../include/boost/predef/compiler/gcc_xml.h[tag=reference] 630 631include::../include/boost/predef/compiler/greenhills.h[tag=reference] 632 633include::../include/boost/predef/compiler/hp_acc.h[tag=reference] 634 635include::../include/boost/predef/compiler/iar.h[tag=reference] 636 637include::../include/boost/predef/compiler/ibm.h[tag=reference] 638 639include::../include/boost/predef/compiler/intel.h[tag=reference] 640 641include::../include/boost/predef/compiler/kai.h[tag=reference] 642 643include::../include/boost/predef/compiler/llvm.h[tag=reference] 644 645include::../include/boost/predef/compiler/metaware.h[tag=reference] 646 647include::../include/boost/predef/compiler/metrowerks.h[tag=reference] 648 649include::../include/boost/predef/compiler/microtec.h[tag=reference] 650 651include::../include/boost/predef/compiler/mpw.h[tag=reference] 652 653include::../include/boost/predef/compiler/nvcc.h[tag=reference] 654 655include::../include/boost/predef/compiler/palm.h[tag=reference] 656 657include::../include/boost/predef/compiler/pgi.h[tag=reference] 658 659include::../include/boost/predef/compiler/sgi_mipspro.h[tag=reference] 660 661include::../include/boost/predef/compiler/sunpro.h[tag=reference] 662 663include::../include/boost/predef/compiler/tendra.h[tag=reference] 664 665include::../include/boost/predef/compiler/visualc.h[tag=reference] 666 667include::../include/boost/predef/compiler/watcom.h[tag=reference] 668 669:leveloffset: -3 670 671=== `BOOST_LANG` language standards macros 672 673:leveloffset: +3 674 675include::../include/boost/predef/language/cuda.h[tag=reference] 676 677include::../include/boost/predef/language/objc.h[tag=reference] 678 679include::../include/boost/predef/language/stdc.h[tag=reference] 680 681include::../include/boost/predef/language/stdcpp.h[tag=reference] 682 683:leveloffset: -3 684 685=== `BOOST_LIB` library macros 686 687:leveloffset: +3 688 689include::../include/boost/predef/library/c/cloudabi.h[tag=reference] 690 691include::../include/boost/predef/library/c/gnu.h[tag=reference] 692 693include::../include/boost/predef/library/c/uc.h[tag=reference] 694 695include::../include/boost/predef/library/c/vms.h[tag=reference] 696 697include::../include/boost/predef/library/c/zos.h[tag=reference] 698 699include::../include/boost/predef/library/std/cxx.h[tag=reference] 700 701include::../include/boost/predef/library/std/dinkumware.h[tag=reference] 702 703include::../include/boost/predef/library/std/libcomo.h[tag=reference] 704 705include::../include/boost/predef/library/std/modena.h[tag=reference] 706 707include::../include/boost/predef/library/std/msl.h[tag=reference] 708 709include::../include/boost/predef/library/std/roguewave.h[tag=reference] 710 711include::../include/boost/predef/library/std/sgi.h[tag=reference] 712 713include::../include/boost/predef/library/std/stdcpp3.h[tag=reference] 714 715include::../include/boost/predef/library/std/stlport.h[tag=reference] 716 717include::../include/boost/predef/library/std/vacpp.h[tag=reference] 718 719:leveloffset: -3 720 721=== `BOOST_OS` operating system macros 722 723:leveloffset: +3 724 725include::../include/boost/predef/os/aix.h[tag=reference] 726 727include::../include/boost/predef/os/amigaos.h[tag=reference] 728 729include::../include/boost/predef/os/beos.h[tag=reference] 730 731include::../include/boost/predef/os/bsd.h[tag=reference] 732 733include::../include/boost/predef/os/cygwin.h[tag=reference] 734 735include::../include/boost/predef/os/haiku.h[tag=reference] 736 737include::../include/boost/predef/os/hpux.h[tag=reference] 738 739include::../include/boost/predef/os/ios.h[tag=reference] 740 741include::../include/boost/predef/os/irix.h[tag=reference] 742 743include::../include/boost/predef/os/linux.h[tag=reference] 744 745include::../include/boost/predef/os/macos.h[tag=reference] 746 747include::../include/boost/predef/os/os400.h[tag=reference] 748 749include::../include/boost/predef/os/qnxnto.h[tag=reference] 750 751include::../include/boost/predef/os/solaris.h[tag=reference] 752 753include::../include/boost/predef/os/unix.h[tag=reference] 754 755include::../include/boost/predef/os/vms.h[tag=reference] 756 757include::../include/boost/predef/os/windows.h[tag=reference] 758 759include::../include/boost/predef/os/bsd/bsdi.h[tag=reference] 760 761include::../include/boost/predef/os/bsd/dragonfly.h[tag=reference] 762 763include::../include/boost/predef/os/bsd/free.h[tag=reference] 764 765include::../include/boost/predef/os/bsd/net.h[tag=reference] 766 767include::../include/boost/predef/os/bsd/open.h[tag=reference] 768 769:leveloffset: -3 770 771=== `BOOST_PLAT` platform macros 772 773:leveloffset: +3 774 775include::../include/boost/predef/platform/android.h[tag=reference] 776 777include::../include/boost/predef/platform/cloudabi.h[tag=reference] 778 779include::../include/boost/predef/platform/ios.h[tag=reference] 780 781include::../include/boost/predef/platform/mingw.h[tag=reference] 782 783include::../include/boost/predef/platform/mingw32.h[tag=reference] 784 785include::../include/boost/predef/platform/mingw64.h[tag=reference] 786 787include::../include/boost/predef/platform/windows_desktop.h[tag=reference] 788 789include::../include/boost/predef/platform/windows_phone.h[tag=reference] 790 791include::../include/boost/predef/platform/windows_runtime.h[tag=reference] 792 793include::../include/boost/predef/platform/windows_server.h[tag=reference] 794 795include::../include/boost/predef/platform/windows_store.h[tag=reference] 796 797include::../include/boost/predef/platform/windows_system.h[tag=reference] 798 799include::../include/boost/predef/platform/windows_uwp.h[tag=reference] 800 801:leveloffset: -3 802 803=== `BOOST_HW` hardware macros 804 805:leveloffset: +3 806 807include::../include/boost/predef/hardware/simd.h[tag=reference] 808 809include::../include/boost/predef/hardware/simd/arm.h[tag=reference] 810 811include::../include/boost/predef/hardware/simd/arm/versions.h[tag=reference] 812 813include::../include/boost/predef/hardware/simd/ppc.h[tag=reference] 814 815include::../include/boost/predef/hardware/simd/ppc/versions.h[tag=reference] 816 817include::../include/boost/predef/hardware/simd/x86.h[tag=reference] 818 819include::../include/boost/predef/hardware/simd/x86/versions.h[tag=reference] 820 821include::../include/boost/predef/hardware/simd/x86_amd.h[tag=reference] 822 823include::../include/boost/predef/hardware/simd/x86_amd/versions.h[tag=reference] 824 825:leveloffset: -3 826 827=== Other macros 828 829:leveloffset: +3 830 831include::../include/boost/predef/other/endian.h[tag=reference] 832 833include::../include/boost/predef/other/wordsize.h[tag=reference] 834 835include::../include/boost/predef/other/workaround.h[tag=reference] 836 837:leveloffset: -3 838 839=== Version definition macros 840 841:leveloffset: +3 842 843include::../include/boost/predef/version_number.h[tag=reference] 844 845include::../include/boost/predef/make.h[tag=reference] 846 847:leveloffset: -3 848 849== Check Utilities 850 851The `predef_check` utility provides a facility for building a 852program that will check a given set of expressions against 853the definitions it detected when it was built. 854 855=== `predef_check` programs 856 857Even though there is only one `predef_check` program, there 858are variations for each of the languages that are detected 859by Predef to match the convention for sources files. For all 860of them one invokes with a list of expression arguments. The 861expressions are evaluated within the context of the particular 862`predef_check` program and if they all are true zero (0) is returned. 863Otherwise the index of the first false expression is returned. 864 865The expression syntax is simple: 866 867[source,jam] 868---- 869predef-definition [ relational-operator version-value ] 870---- 871 872_predef-definition_ can be any of the Predef definitions. For 873example `BOOST_COMP_GCC`. 874 875_relational-operator_ can be any of: `>`, `<`, `>=`, `<=`, 876`==` and `!=`. 877 878_version-number_ can be a full or partial version triplet value. 879If it's a partial version triple it is completed with zeros. That 880is `x.y` is equivalent to `x.y.0` and `x` is equivalent to 881`x.0.0`. 882 883The _relations-operator_ and _version-number_ can be omitted. In 884which case it is equivalent to: 885 886[source,jam] 887---- 888predef-definition > 0.0.0 889---- 890 891=== Using with Boost.Build 892 893You can use the `predef_check` programs directly from Boost Build 894to configure target requirements. This is useful for controlling 895what gets built as part of your project based on the detailed 896version information available in Predef. The basic use is simple: 897 898[source,jam] 899---- 900import path-to-predef-src/tools/check/predef 901 : check require 902 : predef-check predef-require ; 903 904exe my_windows_program : windows_source.cpp 905 : [ predef-require "BOOST_OS_WINDOWS" ] ; 906---- 907 908That simple use case will skip building the `my_windows_program` 909unless one is building for Windows. Like the direct `predef_check` 910you can pass multiple expressions using relational comparisons. 911For example: 912 913[source,jam] 914---- 915import path-to-predef-src/tools/check/predef 916 : check require 917 : predef-check predef-require ; 918 919lib my_special_lib : source.cpp 920 : [ predef-require "BOOST_OS_WINDOWS != 0" "BOOST_OS_VMS != 0"] ; 921---- 922 923And in that case the `my_special_lib` is built only when the OS is 924not Windows or VMS. The `requires` rule is a special case of the 925`check` rule. And is defined in terms of it: 926 927[source,jam] 928---- 929rule require ( expressions + : language ? ) 930{ 931 return [ check $(expressions) : $(language) : : <build>no ] ; 932} 933---- 934 935The expression can also use explicit "and", "or" logical operators 936to for more complex checks: 937 938 939[source,jam] 940---- 941import path-to-predef-src/tools/check/predef 942 : check require 943 : predef-check predef-require ; 944 945lib my_special_lib : source.cpp 946 : [ predef-require "BOOST_OS_WINDOWS" or "BOOST_OS_VMS"] ; 947---- 948 949You can use the `check` rule for more control and to implement 950something other than control of what gets built. The definition 951for the `check` rule is: 952 953[source,jam] 954---- 955rule check ( expressions + : language ? : true-properties * : false-properties * ) 956---- 957 958When invoked as a requirement of a Boost Build target this rule 959will add the `true-properties` to the target if all the `expressions` 960evaluate to true. Otherwise the `false-properties` get added as 961requirements. For example you could use it to enable or disable 962features in your programs: 963 964[source,jam] 965---- 966import path-to-predef-src/tools/check/predef 967 : check require 968 : predef-check predef-require ; 969 970exe my_special_exe : source.cpp 971 : [ predef-check "BOOST_OS_WINDOWS == 0" 972 : : <define>ENABLE_WMF=0 973 : <define>ENABLE_WMF=1 ] ; 974---- 975 976For both `check` and `require` the `language` argument controls 977which variant of the `predef_check` program is used to check the 978expressions. It defaults to "c++", but can be any of: "c", "cpp", 979"objc", and "objcpp". 980 981 982:leveloffset: +1 983 984include::history.adoc[] 985 986include::todo.adoc[] 987 988:leveloffset: -1 989 990== Acknowledgements 991 992The comprehensiveness of this library would not be 993possible without the existence of the indispensable 994resource that is the 995http://sourceforge.net/p/predef/[Pre-defined C/{CPP} Compiler Macros] 996Project. It was, and continues to be, the primary source 997of the definitions that make up this library. Thanks 998to Bjorn Reese and all the volunteers that make that 999resource possible. 1000 1001This library would be an incoherent mess if it weren't for 1002Boost community that provided invaluable feedback for the 1003eight years that it took to polish into a useable form. 1004In particular I would like to thank: Mathias Gaunard, 1005Robert Stewart, Joël Lamotte, Lars Viklund, Nathan Ridge, 1006Artyom Beilis, Joshua Boyce, Gottlob Frege, Thomas Heller, 1007Edward Diener, Dave Abrahams, Iain Denniston, Dan Price, 1008Ioannis Papadopoulos, and Robert Ramey. And thanks to 1009Joel Falcou for managing the review of this library. 1010 1011[colophon] 1012== Colophon 1013 1014Distributed under the Boost Software License, Version 1.0. 1015(See accompanying file LICENSE_1_0.txt or copy at 1016https://www.boost.org/LICENSE_1_0.txt) 1017 1018Copyright 2005-2020 Rene Rivera; Copyright 2015 Charly Chevalier; Copyright 2015 Joel Falcou