directories not used for build moved to extra/

git-svn-id: svn://tug.org/texlive/trunk@15980 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 70 insertions, 0 deletions

diff --git a/Build/source/README.coding b/Build/source/README.coding
new file mode 100644
index 00000000000..fe7edbd3209
--- /dev/null
+++ b/Build/source/README.coding
@@ -0,0 +1,70 @@
+Copyright (C) 2009 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
+functions prototypes and definitions must conform to the ANSI C standard
+(including 'void' in the declaration of functions that take no parameters).
+
+1.2. Static
+-----------
+Functions used in only one file must be declared 'static'; no prototype is
+required except as forward declaration.
+
+1.3. Extern
+-----------
+Functions 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 instatiated in
+exectly 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 particiular for strings ('char *')
+because frequently string literals are used as actual arguments.  Note,
+however, that 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.
+
+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 only may hide them.  Therefore
+such casts should be avoided whenever possible but some such casts may be
+unavoidable.
+