compat/compat.dox

   1 /**
   2 \defgroup compat Portability Library
   3
   4 \title Squid Portability
   5
   6
   7 \section 1 Aim
   8
   9 \par
  10 Squid aims to build and run on many modern systems. To do this we have traditionally
  11 added small hacks and wrappers all over the code whenever one was needed.
  12 The final result of that is a vast amount of code duplication, dodgy licensing on
  13 some older hacks, and some cases of obsolete algorithms sitting side by side with their
  14 current equivalent.
  15
  16 \par
  17 The Portability library libcompat-squid.la has been created to correct the three issues of
  18 stable build portability, code cleanliness, and clearer licensing.
  19
  20
  21 \section 2 Requirements
  22
  23 \par
  24 The system calls used by Squid are not required to be standard. Often we depend on
  25 some non-standard call which can give great performance benefits.
  26 But they are required to meet several other criteria:
  27  \li  They must be of actual benefit to Squid during its operation.
  28  \li  A better alternative must not exist.
  29  \li  If not available on all OS an open-source GPLv2+ implementation must be available
  30       to be included with the Squid sources and used when required.
  31
  32 \par
  33 To be built into the libcompat-squid.la as a layer below all Squid-bundled binaries. The code
  34 must also qualify by being provided natively by some OS where Squid builds. \br
  35 Code and Algorithms which do not meet this final criteria are relegated to the slightly
  36 higher level of basic component, rather than portability.
  37
  38
  39 \section 3 Component Types
  40
  41 \par Macro re-definition
  42 Where the only difference between systems is their naming scheme. One of the schemes is
  43 chosen by the developers for use and mappings are created in the form of Macros.
  44
  45 \par Inline Functions
  46
  47 \par Algorithm Templates and Inline functions
  48 Being C++ we are able to use templates in place of inline functions where that is more
  49 convenient. Care is taken to provide no additional requirements upon the callers when
  50 using the template as to when using the native constructs.
  51
  52 \par Emulators
  53 As mentioned above if a useful library function calls or global is not available on all
  54 operating systems a GPLv2+ alternative may be added to the compat layer. As an emulator
  55 it retains the exact naming and definition of the source systems. Thus being able to be
  56 used seamlessly across all platforms by the main code.
  57
  58 \par Wrappers
  59 Sometimes common and useful library functions are not always as safe as they could be.
  60 An alternative which wraps the original in extra safety checks is provided under the
  61 same name with an 'x' pre-pended. Currently these extra protections are added on string
  62 handling and memory allocation.
  63
  64
  65 \section 4 Layout
  66 The internal code structure of libcompat-squid.la files has a hierarchy. The API has a flat
  67 global scope separate from the file layout. The API is pulled in by including compat/compat.h.
  68 The strict dependency requirements which exist within the compat API make including
  69 individual part separately a risky operation.
  70
  71 \par
  72 Squid coding guidelines require each .c and .cc file to include squid-old.h or squid.h first
  73 in their included files. squid.h begin with an order-specific sequence of defines and
  74 includes compat/compat.h to incorporate the compat layer appropriately in every soure file.
  75 squid.h begins by including squid.h to prepare for its sub-includes and definitions.
  76
  77 \par
  78 Internally the compat/ directory contains the public API file compat/compat.h which structures
  79 order-specific includes as documented inside that file. Included by that is compat/osdetect.h
  80 which determines which operating system and in some cases compiler is being used.
  81
  82 \par
  83 The compat/os/ directory contains separate files for each supported system which requires
  84 special compat layer handling. Hacks for specific systems should be restricted to these files
  85 as much as possible.
  86
  87 \par
  88 compat/compat_shared.h file contains the shared portability definitions which are shared
  89 across a great many systems. These should be written with protective macros to prevent any
  90 symbols or code being defined which is not necessary. Protections here must not be system-specific.
  91
  92 \par
  93 Also in compat/ directory are the .h and .c files for emulators detected by autoconf. These
  94 are added by autoconf to the build objects as required.
  95
  96 */