compat/compat.dox

   1 /**
   2 \defgroup compat Portability Library
   3
   4 \title Squid Portability
   5
   6
   7 \section sec1 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 sec2 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+ compatible implementation must be
  30       available 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
  34 code 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 sec3 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 sec4 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 an
  69 individual part separately a risky operation.
  70
  71 \par
  72 Squid coding guidelines require each .c and .cc file to include squid.h first in their
  73 included files. squid.h begins with an order-specific sequence of defines and includes
  74 compat/compat.h to incorporate the compat layer appropriately in every source file.
  75
  76 \par
  77 Internally the compat/ directory contains the public API file compat/compat.h which structures
  78 order-specific includes as documented inside that file. Included by that is compat/osdetect.h
  79 which determines which operating system and in some cases compiler is being used.
  80
  81 \par
  82 The compat/os/ directory contains separate files for each supported system which requires
  83 special compat layer handling. Hacks for specific systems should be restricted to these files
  84 as much as possible.
  85
  86 \par
  87 compat/compat_shared.h file contains the portability definitions which are shared across a
  88 great many systems. These should be written with protective macros to prevent any symbols or
  89 code being defined which is not necessary. Protections here must not be system-specific.
  90
  91 \par
  92 Also in compat/ directory are the .h and .c files for emulators detected by autoconf. These
  93 are added by autoconf to the build objects as required.
  94
  95 */