]>
Commit | Line | Data |
---|---|---|
8ef1f381 | 1 | /* |
b8ae064d | 2 | * Copyright (C) 1996-2023 The Squid Software Foundation and contributors |
8ef1f381 AJ |
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 | ||
823b0590 AJ |
9 | /** |
10 | \defgroup compat Portability Library | |
11 | ||
12 | \title Squid Portability | |
13 | ||
14 | ||
d6d0eb11 | 15 | \section sec1 Aim |
823b0590 | 16 | |
9603207d | 17 | \par |
823b0590 AJ |
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 | |
ca3a08e2 | 25 | The Portability library libcompatsquid.la has been created to correct the three issues of |
823b0590 AJ |
26 | stable build portability, code cleanliness, and clearer licensing. |
27 | ||
28 | ||
d6d0eb11 | 29 | \section sec2 Requirements |
823b0590 AJ |
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. | |
d6d0eb11 AJ |
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. | |
823b0590 AJ |
39 | |
40 | \par | |
ca3a08e2 | 41 | To be built into the libcompatsquid.la as a layer below all Squid-bundled binaries. The |
d6d0eb11 | 42 | code must also qualify by being provided natively by some OS where Squid builds. \br |
823b0590 AJ |
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 | ||
d6d0eb11 | 47 | \section sec3 Component Types |
823b0590 AJ |
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 | ||
d6d0eb11 | 73 | \section sec4 Layout |
ca3a08e2 | 74 | The internal code structure of libcompatsquid.la files has a hierarchy. The API has a flat |
823b0590 | 75 | global scope separate from the file layout. The API is pulled in by including compat/compat.h. |
d6d0eb11 | 76 | The strict dependency requirements which exist within the compat API make including an |
823b0590 AJ |
77 | individual part separately a risky operation. |
78 | ||
79 | \par | |
d6d0eb11 AJ |
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. | |
823b0590 AJ |
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 | |
d6d0eb11 AJ |
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. | |
823b0590 AJ |
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 | */ |