shotgun/external_libs/libbstring/porting.txt

   1 Better String library Porting Guide\r
   2 -----------------------------------\r
   3 \r
   4 by Paul Hsieh\r
   5 \r
   6 The bstring library is an attempt to provide improved string processing \r
   7 functionality to the C and C++ language.  At the heart of the bstring library \r
   8 is the management of "bstring"s which are a significant improvement over '\0'\r
   9 terminated char buffers.  See the accompanying documenation file bstrlib.txt\r
  10 for more information.\r
  11 \r
  12 ===============================================================================\r
  13 \r
  14 Identifying the Compiler\r
  15 ------------------------\r
  16 \r
  17 Bstrlib has been tested on the following compilers:\r
  18 \r
  19     Microsoft Visual C++\r
  20     Watcom C/C++ (32 bit flat)\r
  21     Intel's C/C++ compiler (on Windows)\r
  22     The GNU C/C++ compiler (on Windows/Linux on x86 and PPC64)\r
  23     Borland C++\r
  24     Turbo C\r
  25 \r
  26 There are slight differences in these compilers which requires slight \r
  27 differences in the implementation of Bstrlib.  These are accomodated in the\r
  28 same sources using #ifdef/#if defined() on compiler specific macros.  To\r
  29 port Bstrlib to a new compiler not listed above, it is recommended that the\r
  30 same strategy be followed.  If you are unaware of the compiler specific \r
  31 identifying preprocessor macro for your compiler you might find it here:\r
  32 \r
  33 http://predef.sourceforge.net/precomp.html\r
  34 \r
  35 Note that Intel C/C++ on Windows sets the Microsoft identifier: _MSC_VER.\r
  36 \r
  37 16-bit vs. 32-bit vs. 64-bit Systems\r
  38 ------------------------------------\r
  39 \r
  40 Bstrlib has been architected to deal with strings of length between 0 and\r
  41 INT_MAX (inclusive).  Since the values of int are never higher than size_t\r
  42 there will be no issue here.  Note that on most 64-bit systems int is 32-bit.\r
  43 \r
  44 Dependency on The C-Library\r
  45 ---------------------------\r
  46 \r
  47 Bstrlib uses the functions memcpy, memmove, malloc, realloc, free and \r
  48 vsnprintf.  Many free standing C compiler implementations that have a mode in \r
  49 which the C library is not available will typically not include these \r
  50 functions which will make porting Bstrlib to it onerous.  Bstrlib is not \r
  51 designed for such bare bones compiler environments.  This usually includes \r
  52 compilers that target ROM environments.\r
  53 \r
  54 Porting Issues\r
  55 --------------\r
  56 \r
  57 Bstrlib has been written completely in ANSI/ISO C and ISO C++, however, there \r
  58 are still a few porting issues.  These are described below.\r
  59 \r
  60 1. The vsnprintf () function.\r
  61 \r
  62 Unfortunately, the earlier ANSI/ISO C standards did not include this function.\r
  63 If the compiler of interest does not support this function then the \r
  64 BSTRLIB_NOVSNP should be defined via something like:\r
  65 \r
  66     #if !defined (BSTRLIB_VSNP_OK) && !defined (BSTRLIB_NOVSNP)\r
  67     # if defined (__TURBOC__) || defined (__COMPILERVENDORSPECIFICMACRO__)\r
  68     #  define BSTRLIB_NOVSNP\r
  69     # endif\r
  70     #endif\r
  71 \r
  72 which appears at the top of bstrlib.h.  Note that the bformat(a) functions \r
  73 will not be declared or implemented if the BSTRLIB_NOVSNP macro is set.  If \r
  74 the compiler has renamed vsnprintf() to some other named function, then \r
  75 search for the definition of the exvsnprintf macro in bstrlib.c file and be \r
  76 sure its defined appropriately:\r
  77 \r
  78     #if defined (__COMPILERVENDORSPECIFICMACRO__)\r
  79     # define exvsnprintf(r,b,n,f,a) {r=__compiler_specific_vsnprintf(b,n,f,a);}\r
  80     #else\r
  81     # define exvsnprintf(r,b,n,f,a) {r=vsnprintf(b,n,f,a);}\r
  82     #endif\r
  83 \r
  84 Take notice of the return value being captured in the variable r.  It is \r
  85 assumed that r exceeds n if and only if the underlying vsnprintf function has\r
  86 determined what the true maximal output length would be for output if the \r
  87 buffer were large enough to hold it.  Non-modern implementations must output a\r
  88 lesser number (the macro can and should be modified to ensure this).\r
  89 \r
  90 2. Weak C++ compiler.\r
  91 \r
  92 C++ is a much more complicated language to implement than C.  This has lead \r
  93 to varying quality of compiler implementations.  The weaknesses isolated in\r
  94 the initial ports are inclusion of the Standard Template Library, \r
  95 std::iostream and exception handling.  By default it is assumed that the C++\r
  96 compiler supports all of these things correctly.  If your compiler does not\r
  97 support one or more of these define the corresponding macro:\r
  98 \r
  99     BSTRLIB_CANNOT_USE_STL\r
 100     BSTRLIB_CANNOT_USE_IOSTREAM\r
 101     BSTRLIB_DOESNT_THROW_EXCEPTIONS\r
 102 \r
 103 The compiler specific detected macro should be defined at the top of \r
 104 bstrwrap.h in the Configuration defines section.  Note that these disabling\r
 105 macros can be overrided with the associated enabling macro if a subsequent\r
 106 version of the compiler gains support.  (For example, its possible to rig\r
 107 up STLport to provide STL support for WATCOM C/C++, so -DBSTRLIB_CAN_USE_STL\r
 108 can be passed in as a compiler option.)\r
 109 \r
 110 3. The bsafe module, and reserved words.\r
 111 \r
 112 The bsafe module is in gross violation of the ANSI/ISO C standard in the \r
 113 sense that it redefines what could be implemented as reserved words on a \r
 114 given compiler.  The typical problem is that a compiler may inline some of the \r
 115 functions and thus not be properly overridden by the definitions in the bsafe \r
 116 module.  It is also possible that a compiler may prohibit the redefinitions in \r
 117 the bsafe module.  Compiler specific action will be required to deal with \r
 118 these situations.\r
 119 \r
 120 Platform Specific Files\r
 121 -----------------------\r
 122 \r
 123 The makefiles for the examples are basically setup of for particular \r
 124 environments for each platform.  In general these makefiles are not portable\r
 125 and should be constructed as necessary from scratch for each platform.\r
 126 \r
 127 Testing a port\r
 128 --------------\r
 129 \r
 130 To test that a port compiles correctly do the following:\r
 131 \r
 132 1. Build a sample project that includes the bstrlib, bstraux, bstrwrap, and \r
 133    bsafe modules.\r
 134 2. Compile bstest against the bstrlib module.\r
 135 3. Run bstest and ensure that 0 errors are reported.\r
 136 4. Compile test against the bstrlib and bstrwrap modules.\r
 137 5. Run test and ensure that 0 errors are reported.\r
 138 6. Compile each of the examples (except for the "re" example, which may be \r
 139    complicated and is not a real test of bstrlib and except for the mfcbench \r
 140    example which is Windows specific.)\r
 141 7. Run each of the examples.\r
 142 \r
 143 The builds must have 0 errors, and should have the absolute minimum number of\r
 144 warnings (in most cases can be reduced to 0.)  The result of execution should \r
 145 be essentially identical on each platform.\r
 146 \r
 147 Performance\r
 148 -----------\r
 149 \r
 150 Different CPU and compilers have different capabilities in terms of \r
 151 performance.  It is possible for Bstrlib to assume performance \r
 152 characteristics that a platform doesn't have (since it was primarily \r
 153 developed on just one platform).  The goal of Bstrlib is to provide very good \r
 154 performance on all platforms regardless of this but without resorting to \r
 155 extreme measures (such as using assembly language, or non-portable intrinsics \r
 156 or library extensions.)\r
 157 \r
 158 There are two performance benchmarks that can be found in the example/ \r
 159 directory.  They are: cbench.c and cppbench.cpp.  These are variations and \r
 160 expansions of a benchmark for another string library.  They don't cover all\r
 161 string functionality, but do include the most basic functions which will be\r
 162 common in most string manipulation kernels.\r
 163 \r
 164 ...............................................................................\r
 165 \r
 166 Feedback\r
 167 --------\r
 168 \r
 169 In all cases, you may email issues found to the primary author of Bstrlib at \r
 170 the email address: websnarf@users.sourceforge.net\r
 171 \r
 172 ===============================================================================\r