[thirdparty/squid.git] / compat / compat.dox

/*
 * Copyright (C) 1996-2017 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 */

/**
\defgroup compat Portability Library

\title Squid Portability


\section sec1 Aim

\par 
Squid aims to build and run on many modern systems. To do this we have traditionally
added small hacks and wrappers all over the code whenever one was needed.
The final result of that is a vast amount of code duplication, dodgy licensing on
some older hacks, and some cases of obsolete algorithms sitting side by side with their
current equivalent.

\par
The Portability library libcompatsquid.la has been created to correct the three issues of
stable build portability, code cleanliness, and clearer licensing.


\section sec2 Requirements

\par
The system calls used by Squid are not required to be standard. Often we depend on
some non-standard call which can give great performance benefits.
But they are required to meet several other criteria:
 \li  They must be of actual benefit to Squid during its operation.
 \li  A better alternative must not exist.
 \li  If not available on all OS an open-source GPLv2+ compatible implementation must be
      available to be included with the Squid sources and used when required.

\par
To be built into the libcompatsquid.la as a layer below all Squid-bundled binaries. The
code must also qualify by being provided natively by some OS where Squid builds. \br
Code and Algorithms which do not meet this final criteria are relegated to the slightly
higher level of basic component, rather than portability.


\section sec3 Component Types

\par Macro re-definition
Where the only difference between systems is their naming scheme. One of the schemes is
chosen by the developers for use and mappings are created in the form of Macros.

\par Inline Functions

\par Algorithm Templates and Inline functions
Being C++ we are able to use templates in place of inline functions where that is more
convenient. Care is taken to provide no additional requirements upon the callers when
using the template as to when using the native constructs.

\par Emulators
As mentioned above if a useful library function calls or global is not available on all
operating systems a GPLv2+ alternative may be added to the compat layer. As an emulator
it retains the exact naming and definition of the source systems. Thus being able to be
used seamlessly across all platforms by the main code.

\par Wrappers
Sometimes common and useful library functions are not always as safe as they could be.
An alternative which wraps the original in extra safety checks is provided under the
same name with an 'x' pre-pended. Currently these extra protections are added on string
handling and memory allocation.


\section sec4 Layout
The internal code structure of libcompatsquid.la files has a hierarchy. The API has a flat
global scope separate from the file layout. The API is pulled in by including compat/compat.h.
The strict dependency requirements which exist within the compat API make including an
individual part separately a risky operation.

\par
Squid coding guidelines require each .c and .cc file to include squid.h first in their
included files. squid.h begins with an order-specific sequence of defines and includes
compat/compat.h to incorporate the compat layer appropriately in every source file.

\par
Internally the compat/ directory contains the public API file compat/compat.h which structures
order-specific includes as documented inside that file. Included by that is compat/osdetect.h
which determines which operating system and in some cases compiler is being used.

\par
The compat/os/ directory contains separate files for each supported system which requires
special compat layer handling. Hacks for specific systems should be restricted to these files
as much as possible.

\par
compat/compat_shared.h file contains the portability definitions which are shared across a
great many systems. These should be written with protective macros to prevent any symbols or
code being defined which is not necessary. Protections here must not be system-specific.

\par
Also in compat/ directory are the .h and .c files for emulators detected by autoconf. These
are added by autoconf to the build objects as required.

*/
Commit	Line	Data
8ef1f381	1	/*
4ac4a490	2	* Copyright (C) 1996-2017 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 AJ	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
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
d6d0eb11 AJ	38	available to be included with the Squid sources and used when required.
823b0590 AJ	39
823b0590 AJ	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	*/