From 80b14ea8a8ba0ad297ee0f316e809ab2e081148b Mon Sep 17 00:00:00 2001 From: John Maddock Date: Sun, 17 Aug 2003 12:03:01 +0000 Subject: [PATCH] Added minimal Docs for new macros and headers (abi fixing/link library selection/BOOST_HAS_DECLS|PEC), more to come on this... Added test cases for new macros and headers. [SVN r19655] --- config.htm | 163 ++++++++++++--- test/Jamfile | 4 +- test/abi/abi_test.cpp | 26 +++ test/abi/abi_test.hpp | 51 +++++ test/abi/main.cpp | 29 +++ test/config_test.cpp | 2 +- test/link/Jamfile | 12 ++ test/link/bc_gen.sh | 284 +++++++++++++++++++++++++ test/link/bcb4.mak | 231 +++++++++++++++++++++ test/link/bcb5.mak | 231 +++++++++++++++++++++ test/link/bcb6.mak | 413 +++++++++++++++++++++++++++++++++++++ test/link/common.sh | 8 + test/link/link_test.cpp | 25 +++ test/link/link_test.hpp | 76 +++++++ test/link/main.cpp | 14 ++ test/link/vc6-stlport.mak | 288 ++++++++++++++++++++++++++ test/link/vc6.mak | 256 +++++++++++++++++++++++ test/link/vc7-stlport.mak | 288 ++++++++++++++++++++++++++ test/link/vc7.mak | 256 +++++++++++++++++++++++ test/link/vc71-stlport.mak | 288 ++++++++++++++++++++++++++ test/link/vc71.mak | 256 +++++++++++++++++++++++ test/link/vc_gen.sh | 412 ++++++++++++++++++++++++++++++++++++ tools/generate | 1 + 23 files changed, 3583 insertions(+), 31 deletions(-) create mode 100644 test/abi/abi_test.cpp create mode 100644 test/abi/abi_test.hpp create mode 100644 test/abi/main.cpp create mode 100644 test/link/Jamfile create mode 100644 test/link/bc_gen.sh create mode 100644 test/link/bcb4.mak create mode 100644 test/link/bcb5.mak create mode 100644 test/link/bcb6.mak create mode 100644 test/link/common.sh create mode 100644 test/link/link_test.cpp create mode 100644 test/link/link_test.hpp create mode 100644 test/link/main.cpp create mode 100644 test/link/vc6-stlport.mak create mode 100644 test/link/vc6.mak create mode 100644 test/link/vc7-stlport.mak create mode 100644 test/link/vc7.mak create mode 100644 test/link/vc71-stlport.mak create mode 100644 test/link/vc71.mak create mode 100644 test/link/vc_gen.sh diff --git a/config.htm b/config.htm index 6ee593ab..3a802c3d 100644 --- a/config.htm +++ b/config.htm @@ -21,6 +21,7 @@ Macros that describe optional features Boost Helper Macros Boost Informational Macros + Macros for libraries with separate source code Guidelines for Boost Authors Adding New Defect Macros Adding New Feature Test Macros @@ -216,6 +217,22 @@ export LIBS="-lpthread" BOOST_HAS_PTHREADS is set. This option may be set automatically by the config system when it detects that the compiler is in "strict mode". + + BOOST_DISABLE_ABI_HEADERS + Stops boost headers from including any prefix/suffix headers that normally + control things like struct packing and alignment. + + + BOOST_ABI_PREFIX + A prefix header to include in place of whatever boost.config would normally + select, any replacement should set up struct packing and alignment options as + required. + + + BOOST_ABI_SUFFIX + A suffix header to include in place of whatever boost.config would normally + select, any replacement should undo the effects of the prefix header. +

Advanced configuration usage

By setting various macros on the compiler command line or by editing <boost/config/user.hpp>, @@ -709,6 +726,13 @@ void g() { return f(); } Platform The platform has the POSIX API clock_gettime. + + BOOST_HAS_DECLSPEC + + Compiler + The compiler uses __declspec(dllexport) and __declspec(dllimport) to + export/import symbols from dll's. + BOOST_HAS_DIRENT_H Platform @@ -913,23 +937,21 @@ void g() { return f(); } BOOST_EXPLICIT_TEMPLATE_TYPE(t)
- BOOST_EXPLICIT_TEMPLATE_NON_TYPE(t, v)
- - BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(t)
- BOOST_APPEND_EXPLICIT_TEMPLATE_NON_TYPE(t, v)
+ BOOST_EXPLICIT_TEMPLATE_NON_TYPE(t, v)
+ BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(t)
+ BOOST_APPEND_EXPLICIT_TEMPLATE_NON_TYPE(t, v)
- Some compilers silently "fold" different function template - instantiations if some of the template parameters don't appear - in the function parameter list. For instance: -

-  #include <iostream>
+            Some compilers silently "fold" different function template instantiations if 
+               some of the template parameters don't appear in the function parameter list. 
+               For instance:
+               
  #include <iostream>
   #include <ostream>
   #include <typeinfo>
 
   template <int n>
   void f() { std::cout << n << ' '; }
 
-  template <typename T>
+  template <typename T>
   void g() { std::cout << typeid(T).name() << ' '; }
 
   int main() {
@@ -940,29 +962,28 @@ void g() { return f(); }

     g<double>();
   }
- incorrectly outputs "2 2 double double " on VC++ 6. - - These macros, to be used in the function parameter list, fix the - problem without effects on the calling syntax. For instance, in - the case above write: -
+               incorrectly outputs "2 2 double double " on VC++ 6. These macros, to 
+               be used in the function parameter list, fix the problem without effects on the 
+               calling syntax. For instance, in the case above write:
+               
   template <int n>
   void f(BOOST_EXPLICIT_TEMPLATE_NON_TYPE(int, n)) { ... }
 
   template <typename T>
   void g(BOOST_EXPLICIT_TEMPLATE_TYPE(T)) { ... }
 

-
-                Beware that they can declare (for affected compilers) a dummy 
-                defaulted parameter, so they
-                

a) should be always invoked *at the end* of the parameter list
-                
    b) can't be used if your function template is multiply declared.
-                


-
-                Furthermore, in order to add any needed comma separator, an "APPEND_*"
-                version must be used when the macro invocation appears after a normal
-                parameter declaration or after the invocation of another macro of this
-                same group. 
+               Beware that they can declare (for affected compilers) a dummy defaulted parameter, 
+               so they
+               

+               

+               a) should be always invoked *at the end* of the parameter list
+               

+               b) can't be used if your function template is multiply declared.
+               

+               

+               Furthermore, in order to add any needed comma separator, an "APPEND_*" version 
+               must be used when the macro invocation appears after a normal parameter 
+               declaration or after the invocation of another macro of this same group.
             
          
          
@@ -1076,7 +1097,93 @@ void g() { return f(); }

-

Guidelines for Boost Authors

+

Macros for libraries with separate source code

+

The following macros and helper headers are of use to authors whose libraries + include separate source code, and are intended to address two issues: fixing + the ABI of the compiled library, and selecting which compiled library to link + against based upon the compilers settings.

+
ABI Fixing
+

When linking against a pre-compiled library it vital that the ABI used by the + compiler when building the library matches exactly the ABI + used by the code using the library.  In this case ABI means things like + the struct packing arrangement used, the name mangling scheme used, or the size + of some types (enum types for example).  This is separate from things like + threading support, or runtime library variations, which have to be dealt with + by build variants.  To put this in perspective there is one compiler + (Borland's) that has so many compiler options that make subtle changes to the + ABI, that at least in theory there 3200 combinations, and that's without + considering runtime library variations.  Fortunately these variations can + be managed by #pragma's that tell the compiler what ABI to use for the types + declared in your library, in order to avoid sprinkling #pragma's all over the + boost headers, there are some prefix and suffix headers that do the job, + typical usage would be:

+ 
+#ifndef MY_INCLUDE_GUARD
+#define MY_INCLUDE_GUARD
+
+// all includes go here:
+#include <boost/config.hpp>
+#include <whatever>
+
+#ifdef BOOST_HAS_ABI_HEADERS
+#  include BOOST_ABI_PREFIX
+#endif
+
+namespace boost{
+// your code goes here
+} 
+
+#ifdef BOOST_HAS_ABI_HEADERS
+#  include BOOST_ABI_SUFFIX
+#endif
+
+
+#endif // include guard
+
+

The user can disable this mechanism by defining BOOST_DISABLE_ABI_HEADERS, or + they can define BOOST_ABI_PREFIX and/or BOOST_ABI_SUFFIX to point to their own + prefix/suffix headers if they so wish.

+
Automatic library selection
+

It is essential that users link to a build of a library which was built against + the same runtime library that their application will be built against - if this + does not happen then the library will not be binary compatible with their own + code - and there is a high likelihood  that their application will + experience runtime crashes.  These kinds of problems can be extremely + time consuming and difficult to debug, and often lead to frustrated users and + authors alike (simply selecting the right library to link against is not as + easy as it seems when their are 6-8 of them to chose from, and some users seem + to be blissfully unaware that there even are different runtimes available to + them).

+

To solve this issue, some compilers allow source code to contain #pragma's that + instruct the linker which library to link against, all the user need do is + include the headers they need, place the compiled libraries in their library + search path, and the compiler and linker do the rest.  Boost.config + supports this via the header <boost/config/auto_link.hpp>, before + including this header one or more of the following macros need to be defined:

+

+ + + + + + + + + + + + + +
BOOST_LIB_NAMERequired: A string containing the basename of the library, for example + "boost_regex".
BOOST_DYN_LINKOptional: when set link to dll rather than static library.
BOOST_LIB_DIAGNOSTICOptional: when set the header will print out the name of the library selected + (useful for debugging).
+

+

If the compiler supports this mechanism, then it will be told to link against + the appropriately named library, the actual algorithm used to mangle the name + of the library is documented inside <boost/config/auto_link.hpp> and has + to match that used to create the libraries via bjam (see boost.regex Jamfile + for an example: we're working on simplifying this).

+

Guidelines for Boost Authors

The boost/config.hpp header is used to pass configuration information to other boost files, allowing them to cope with platform dependencies such as arithmetic byte ordering, compiler pragmas, or diff --git a/test/Jamfile b/test/Jamfile index 4f795b9a..9b0a49db 100644 --- a/test/Jamfile +++ b/test/Jamfile @@ -1,7 +1,7 @@ # # Regression test Jamfile for boost configuration setup. # *** DO NOT EDIT THIS FILE BY HAND *** -# This file was automatically generated on Sun Aug 3 11:37:53 GMTST 2003, +# This file was automatically generated on Fri Aug 15 12:02:00 GMTST 2003, # by libs/config/tools/generate # # If you need to alter build preferences then set them in @@ -16,6 +16,7 @@ include $(BOOST_ROOT)/libs/config/test/options.jam ; run config_info.cpp