diff --git a/doc/history.qbk b/doc/history.qbk index 5cd80ac..b2fb81e 100644 --- a/doc/history.qbk +++ b/doc/history.qbk @@ -19,6 +19,9 @@ http://www.boost.org/LICENSE_1_0.txt) * Addition of exclusive plus emulated definitions for platform and compiler detection. -[warning The big change for this version is the restructuring of the definitions to avoid duplicate definitions in one category. That is, only one `BOOST_OS_*` variant will be detected (except for sub-categories).] +[warning The big change for this version is the restructuring of the +definitions to avoid duplicate definitions in one category. That is, only one +`BOOST_OS_*`, `BOOST_COMP_*`, and `BOOST_PLAT_*` variant will be detected +(except for sub-categories).] [endsect] diff --git a/doc/html/index.html b/doc/html/index.html index f3af5b2..024453d 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -52,7 +52,7 @@ - +

Last revised: June 03, 2014 at 03:39:11 GMT

Last revised: June 04, 2014 at 03:28:01 GMT
diff --git a/doc/html/predef/adding_new_predefs.html b/doc/html/predef/adding_new_predefs.html index b4dfcba..091b7b7 100644 --- a/doc/html/predef/adding_new_predefs.html +++ b/doc/html/predef/adding_new_predefs.html @@ -37,20 +37,21 @@ The headers must use the Boost Software License.
  • - The predef must, by default, be defined as BOOST_VERSION_NUMBER(0,0,0). + The predef must, by default, be defined as BOOST_VERSION_NUMBER_NOT_AVAILABLE.
  • The predef must be redefined to a non-zero value once detected.
  • - The predef must, by default, be defined to BOOST_VERSION_NUMBER(0,0,1) when the predef is detected. + The predef must, by default, be defined to BOOST_VERSION_NUMBER_AVAILABLE + when the predef is detected.
  • If possible, the predef will be defined as the version number detected.
  • The predef must define *_AVAILABLE - macros. + macros as needed.
  • The predef must define a symbolic constant string name macro. @@ -58,6 +59,16 @@
  • The predef must declare itself, after being defined, for the testing system.
    • +
  • + The predef must guarantee that it is the only one defined as detected per + category. +
    • +
  • + But a predef can define *_EMULATED macros to indicate that it + was previously detected by another header and is being "emulated" + by the system. Note that the *_AVAILABLE macros must still be defined + in this situation. +

    • And there are some extra guidelines that predef headers should follow: @@ -97,6 +108,12 @@ http://www.boost.org/LICENSE_1_0.txt) #ifndef BOOST_PREDEF_category_tag_H #define BOOST_PREDEF_category_tag_H +

    + If the detection depends on the detection of another predef you should include + those headers here. +

    +
    #include <boost/predef/CATEGORY_TAG/DEPENDENCY.h>
+

    Depending on how you are defining the predef you will at minimum have to include the version_number.h header. But you might also want to include @@ -120,7 +137,7 @@ http://www.boost.org/LICENSE_1_0.txt) Documentation about what is detected. */ -#define BOOST_category_tag BOOST_VERSION_NUMBER(0,0,0) +#define BOOST_category_tag BOOST_VERSION_NUMBER_NOT_AVAILABLE

    Next is the detection and definition of the particular predef. The structure @@ -130,27 +147,29 @@ Documentation about what is detected. BOOST_category_tag" which undefines the zero-value default. The rest is up to the you how to do the checks for defining the version. But at minimum it must "#define - BOOST_category_tag BOOST_VERSION_NUMBER(0,0,1)" as the fallback to minimally indicate - that the predef was detected: + BOOST_category_tag BOOST_VERSION_NUMBER_AVAILABLE" + as the fallback to minimally indicate that the predef was detected: 

    #if (condition_a)
 #   undef BOOST_category_tag
 #   if (condition_b)
 #        define BOOST_category_tag BOOST_VERSION_NUMBER(major,minor,patch)
 #    else
-#        define BOOST_category_tag BOOST_VERSION_NUMBER(0,0,1)
+#        define BOOST_category_tag BOOST_VERSION_NUMBER_AVAILABLE
 #    endif
 #endif

    - We also need to provide the *_AVAILABLE versions of the predef. And for - convenience we also want to provide a *_NAME macro: + We also need to provide the *_AVAILABLE versions of the predef. 

    #if BOOST_category_tag
 #   define BOOST_category_tag_AVAILABLE
 #endif
-
-#define BOOST_catagory_tag_NAME "Name"
+
    +

    + And for convenience we also want to provide a *_NAME macro: +

    +
    #define BOOST_catagory_tag_NAME "Name"

    The testing of the predef macros is automated to generate checks for all the @@ -168,6 +187,84 @@ Documentation about what is detected.

    + Adding + exclusive predefs +

    +

    + For headers of predefs that need to be mutually exclusive in the detection + we need to add checks and definitions to detect when the predef is detected + by multiple headers. +

    +

    + Internally compiler, operating system, and platforms define BOOST_PREDEF_DETAIL_COMP_DETECTED, + BOOST_PREDEF_DEFAIL_OS_DETECTED, + and BOOST_PREDEF_DETAIL_PLAT_DETECTED + respectively when the predef is first detected. This is used to guard against + multiple definition of the detection in later included headers. In those cases + the detection would instead be written as: +

    +
    #if !BOOST_PREDEF_DETAIL_category_DETECTED && (condition_a)
+#   undef BOOST_category_tag
+#   if (condition_b)
+#        define BOOST_category_tag BOOST_VERSION_NUMBER(major,minor,patch)
+#    else
+#        define BOOST_category_tag BOOST_VERSION_NUMBER(0,0,1)
+#    endif
+#endif
+
    +

    + And we also include a header that defines the *_DETECTED macro when we have the detection: +

    +
    #if BOOST_category_tag
+#   define BOOST_category_tag_AVAILABLE
+#   include <boost/predef/detail/CATEGORY_detected.h>
+#endif
+
    +

    + Everything else about the header is the same as the basic detection header. +

    +

    + + Adding + an exclusive but emulated predef +

    +

    + Because compilers are frequently emulated by other compilers we both want to + have exclusive detection of the compiler and also provide information that + we detected the emulation of the compiler. To accomplish this we define a local + *_DETECTION + macro for the compiler detection. And conditionally define either the base + compiler predef BOOST_COMP_compiler + or the alternate BOOST_COMP_compiler_EMULATED + predef. +

    +

    + The initial detection would look like: +

    +
    #if (condition_a)
+#   if (condition_b)
+#        define BOOST_COMP_tag_DETECTION BOOST_VERSION_NUMBER(major,minor,patch)
+#    else
+#        define BOOST_COMP_tag_DETECTION BOOST_VERSION_NUMBER_AVAILABLE
+#    endif
+#endif
+
    +

    + And then we can conditionally define the base or emulated predefs: +

    +
    #ifdef BOOST_COMP_tag_DETECTION
+#   if defined(BOOST_PREDEF_DETAIL_COMP_DETECTED)
+#       define BOOST_COMP_tag_EMULATED BOOST_COMP_tag_DETECTION
+#   else
+#       undef BOOST_COMP_tag
+#       define BOOST_COMP_tag BOOST_COMP_tag_DETECTION
+#   endif
+#   define BOOST_category_tag_AVAILABLE
+#   include <boost/predef/detail/comp_detected.h>
+#endif
+
    +

    + Using utility pattern macros

    diff --git a/doc/html/predef/history.html b/doc/html/predef/history.html index def9e4a..9d9a2ef 100644 --- a/doc/html/predef/history.html +++ b/doc/html/predef/history.html @@ -51,7 +51,9 @@

    The big change for this version is the restructuring of the definitions to - avoid duplicate definitions in one category. That is, only one BOOST_OS_* + avoid duplicate definitions in one category. That is, only one BOOST_OS_*, + BOOST_COMP_*, + and BOOST_PLAT_* variant will be detected (except for sub-categories).

    diff --git a/doc/html/predef/reference/boost_arch_architecture_macros.html b/doc/html/predef/reference/boost_arch_architecture_macros.html index c7113c0..c790a49 100644 --- a/doc/html/predef/reference/boost_arch_architecture_macros.html +++ b/doc/html/predef/reference/boost_arch_architecture_macros.html @@ -204,7 +204,7 @@

    - `_M_ARM' + _M_ARM

    diff --git a/doc/html/predef/using_the_predefs.html b/doc/html/predef/using_the_predefs.html index 171d5e4..7ce9d04 100644 --- a/doc/html/predef/using_the_predefs.html +++ b/doc/html/predef/using_the_predefs.html @@ -145,6 +145,24 @@

    + The + *_EMULATED + macros +

    +

    + Predef definitions are guaranteed to be uniquely detected within one category. + But there are contexts under which multiple underlying detections are possible. + The well known example of this is detection of GCC and MSVC compilers which + are commonly emulated by other compilers by defining the same base macros. + To account for this detection headers are allowed to define *_EMULATED predefs when this situation is + detected. The emulated predefs will be set to the version number of the detection + instead of the regular predef macro for that 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. +

    +

    + Using the BOOST_VERSION_NUMBER macro

    diff --git a/doc/predef.qbk b/doc/predef.qbk index 1ff91d3..75ec39d 100644 --- a/doc/predef.qbk +++ b/doc/predef.qbk @@ -223,6 +223,17 @@ detected. I.e. a definition equivalent to: Also for each aspect there is a macro defined with a descriptive name of what the detection is. +[heading The `*_EMULATED` macros] + +Predef definitions are guaranteed to be uniquely detected within one category. +But there are contexts under which multiple underlying detections are possible. +The well known example of this is detection of GCC and MSVC compilers which are +commonly emulated by other compilers by defining the same base macros. To +account for this detection headers are allowed to define `*_EMULATED` predefs +when this situation is detected. The emulated predefs will be set to the +version number of the detection instead of the regular predef macro for that +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`. + [heading Using the `BOOST_VERSION_NUMBER` macro] All the predefs are defined to be a use of the `BOOST_VERSION_NUMBER` macro. @@ -276,15 +287,21 @@ the same structure and requirements. All predefs need to follow a set of requirements: * The headers must use the Boost Software License. -* The predef must, by default, be defined as `BOOST_VERSION_NUMBER(0,0,0)`. +* The predef must, by default, be defined as `BOOST_VERSION_NUMBER_NOT_AVAILABLE`. * The predef must be redefined to a non-zero value once detected. -* The predef must, by default, be defined to `BOOST_VERSION_NUMBER(0,0,1)` +* The predef must, by default, be defined to `BOOST_VERSION_NUMBER_AVAILABLE` when the predef is detected. * If possible, the predef will be defined as the version number detected. -* The predef must define `*_AVAILABLE` macros. +* The predef must define `*_AVAILABLE` macros as needed. * The predef must define a symbolic constant string name macro. * The predef must declare itself, after being defined, for the testing system. +* The predef must guarantee that it is the only one defined as detected + per category. +* But a predef can define `*_EMULATED` macros to indicate that it was + previously detected by another header and is being "emulated" by the + system. Note that the `*_AVAILABLE` macros must still be defined in this + situation. And there are some extra guidelines that predef headers should follow: @@ -315,6 +332,13 @@ http://www.boost.org/LICENSE_1_0.txt) #define BOOST_PREDEF_category_tag_H `` +If the detection depends on the detection of another predef you should +include those headers here. + +`` +#include +`` + Depending on how you are defining the predef you will at minimum have to include the `version_number.h` header. But you might also want to include the `make.h` header for the version number decomposing utility @@ -340,7 +364,7 @@ for the macro. In particular this works for the popular Eclipse IDE: Documentation about what is detected. */ -#define BOOST_category_tag BOOST_VERSION_NUMBER(0,0,0) +#define BOOST_category_tag BOOST_VERSION_NUMBER_NOT_AVAILABLE `` Next is the detection and definition of the particular predef. The @@ -349,7 +373,7 @@ place further version detection inside this. The first action inside the overall check is to "`#undef BOOST_category_tag`" which undefines the zero-value default. The rest is up to the you how to do the checks for defining the version. But at minimum it must -"`#define BOOST_category_tag BOOST_VERSION_NUMBER(0,0,1)`" as the fallback +"`#define BOOST_category_tag BOOST_VERSION_NUMBER_AVAILABLE`" as the fallback to minimally indicate that the predef was detected: `` @@ -358,19 +382,22 @@ to minimally indicate that the predef was detected: # if (condition_b) # define BOOST_category_tag BOOST_VERSION_NUMBER(major,minor,patch) # else -# define BOOST_category_tag BOOST_VERSION_NUMBER(0,0,1) +# define BOOST_category_tag BOOST_VERSION_NUMBER_AVAILABLE # endif #endif `` -We also need to provide the `*_AVAILABLE` versions of the predef. And -for convenience we also want to provide a `*_NAME` macro: +We also need to provide the `*_AVAILABLE` versions of the predef. `` #if BOOST_category_tag # define BOOST_category_tag_AVAILABLE #endif +`` +And for convenience we also want to provide a `*_NAME` macro: + +`` #define BOOST_catagory_tag_NAME "Name" `` @@ -391,6 +418,78 @@ And, of course, we last need to close out the include guard: #endif `` +[heading Adding exclusive predefs] + +For headers of predefs that need to be mutually exclusive in the detection +we need to add checks and definitions to detect when the predef is +detected by multiple headers. + +Internally compiler, operating system, and platforms define +`BOOST_PREDEF_DETAIL_COMP_DETECTED`, `BOOST_PREDEF_DEFAIL_OS_DETECTED`, and +`BOOST_PREDEF_DETAIL_PLAT_DETECTED` respectively when the predef is first +detected. This is used to guard against multiple definition of the detection +in later included headers. In those cases the detection would instead be +written as: + +`` +#if !BOOST_PREDEF_DETAIL_category_DETECTED && (condition_a) +# undef BOOST_category_tag +# if (condition_b) +# define BOOST_category_tag BOOST_VERSION_NUMBER(major,minor,patch) +# else +# define BOOST_category_tag BOOST_VERSION_NUMBER(0,0,1) +# endif +#endif +`` + +And we also include a header that defines the `*_DETECTED` macro when we have +the detection: + +`` +#if BOOST_category_tag +# define BOOST_category_tag_AVAILABLE +# include +#endif +`` + +Everything else about the header is the same as the basic detection header. + +[heading Adding an exclusive but emulated predef] + +Because compilers are frequently emulated by other compilers we both want +to have exclusive detection of the compiler and also provide information +that we detected the emulation of the compiler. To accomplish this we define +a local `*_DETECTION` macro for the compiler detection. And conditionally +define either the base compiler predef `BOOST_COMP_compiler` or the alternate +`BOOST_COMP_compiler_EMULATED` predef. + +The initial detection would look like: + +`` +#if (condition_a) +# if (condition_b) +# define BOOST_COMP_tag_DETECTION BOOST_VERSION_NUMBER(major,minor,patch) +# else +# define BOOST_COMP_tag_DETECTION BOOST_VERSION_NUMBER_AVAILABLE +# endif +#endif +`` + +And then we can conditionally define the base or emulated predefs: + +`` +#ifdef BOOST_COMP_tag_DETECTION +# if defined(BOOST_PREDEF_DETAIL_COMP_DETECTED) +# define BOOST_COMP_tag_EMULATED BOOST_COMP_tag_DETECTION +# else +# undef BOOST_COMP_tag +# define BOOST_COMP_tag BOOST_COMP_tag_DETECTION +# endif +# define BOOST_category_tag_AVAILABLE +# include +#endif +`` + [heading Using utility pattern macros] By including: diff --git a/include/boost/predef/architecture/arm.h b/include/boost/predef/architecture/arm.h index 589b14d..4974895 100644 --- a/include/boost/predef/architecture/arm.h +++ b/include/boost/predef/architecture/arm.h @@ -26,7 +26,7 @@ http://www.boost.org/LICENSE_1_0.txt) [[`__thumb__`] [__predef_detection__]] [[`__TARGET_ARCH_ARM`] [__predef_detection__]] [[`__TARGET_ARCH_THUMB`] [__predef_detection__]] - [[`_M_ARM'] [__predef_detection__]] + [[`_M_ARM`] [__predef_detection__]] [[`__arm64`] [8.0.0]] [[`__TARGET_ARCH_ARM`] [V.0.0]]