compat/compat.dox

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