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

/**
\defgroup compat Portability Library

\title Squid Portability


\section 1 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 libcompat-squid.la has been created to correct the three issues of
stable build portability, code cleanliness, and clearer licensing.


\section 2 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+ implementation must be available
      to be included with the Squid sources and used when required.

\par
To be built into the libcompat-squid.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 3 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 4 Layout
The internal code structure of libcompat-squid.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
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 begin with an order-specific sequence of defines and
includes compat/compat.h to incorporate the compat layer appropriately in every soure 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 shared 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
823b0590 AJ	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
582c2af2	72	Squid coding guidelines require each .c and .cc file to include squid.h first
f7f3304a	73	in their included files. squid.h begin with an order-specific sequence of defines and
823b0590	74	includes compat/compat.h to incorporate the compat layer appropriately in every soure file.
823b0590 AJ	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 shared portability definitions which are shared
	88	across a great many systems. These should be written with protective macros to prevent any
	89	symbols or 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	*/