Copyright (C) 2009-2011 Peter Breitenlohner <tex-live@tug.org>
You may freely use, modify and/or distribute this file.

	TeX Live (TL) coding rules
	==========================

Ideally, building all of TL with '--enable-compiler-warnings=max' should
produce no (gcc) compiler warnings at all.  In spite of considerable efforts
into that direction we are still far from that goal and there are reasons
that we may never fully reach it.  Below are some rules about declarations
(of functions and variables) and the use of `const'.  These rules should be
applied to all parts of the TL tree, except in some of those maintained
independently.

1. Declarations
===============

1.1. ANSI C function prototypes and definitions
-----------------------------------------------
The TL build system no longer supports pre-ANSI C compilers.  Thus all
function prototypes and definitions must conform to the ANSI C standard
(including `void' in the declaration of C functions with no parameters).

1.2. Static
-----------
Functions used in only one file should be declared `static'; no prototype is
then required except as forward declaration.

1.3. Extern
-----------
Non-static functions, e.g., used in several files, require (extern)
prototypes to be provided by a header files.  That header must be included
in the file defining the function and in all files using that function --
this is the only way to guarantee consistency between definition and use of
functions.  No more `extern's sprinkled throughout the C code (with or
without comment where that function is defined).

1.4. Variables
--------------
The declaration of global variables should follow analogous rules, they
should either be static or declared extern in a header and instantiated in
exactly one file.

2. Const
========

2.1. Function parameters
------------------------
Ideally, a function parameter not modified by the function should be
declared as const.  This is important in particular for strings (`char *')
because frequently the actual arguments are string literals.
However, a `char **' value is not assignment compatible with a `const
char **' variable.  Getting all `const's right often is quite involved but
usually can be done.  There are, however, a few notable exceptions: the X11
headers are full of declarations that ought to use const but do not and the
same is true to some extent for zlib and freetype2.

2.2. What must be avoided
-------------------------
The compiler warnings `assignment/initialization/passing arg/return discards
qualifiers...' must be avoided under all circumstances, except when caused
by X11 headers/macros or third party code.

2.3. What should be avoided
---------------------------
A type cast, e.g., from `const char *' to `char *' doesn't solve any
problems; depending on warning options, it may only hide them.  Therefore
such casts should be avoided whenever possible but some such casts may be
unavoidable.