summaryrefslogtreecommitdiff
path: root/Build/source/README.6coding
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/README.6coding')
-rw-r--r--Build/source/README.6coding112
1 files changed, 112 insertions, 0 deletions
diff --git a/Build/source/README.6coding b/Build/source/README.6coding
new file mode 100644
index 00000000000..a8abaa9c2d7
--- /dev/null
+++ b/Build/source/README.6coding
@@ -0,0 +1,112 @@
+(This file was generated by makeinfo and splitinfo.gawk.)
+(Released under the old-style GNU documentation license;
+ see sources or other output files for full text.)
+
+8 Coding conventions
+********************
+
+Ideally, building all of TeX Live 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 or variables and the use of
+'const'. These rules should be applied to most of the TeX Live tree,
+the exception being code that is maintained independently and whose
+maintainers don't want to accept patches.
+
+8.1 Declarations and definitions
+================================
+
+C standards
+...........
+
+The TeX Live 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). On the other hand, TL is built for a wide variety of
+systems, not all of which support the C99 standard. Therefore using C99
+features should be avoided if that can easily be done. In particular C
+code must not contain declarations after statements or C++-style
+comments.
+
+ If some C99 (or later) constructs must be used, the module should
+verify that they are available and otherwise provide an alternative.
+For example, the module 'texk/chktex' uses the C99 function 'stpcpy()'
+that may or may not be available on a particular system. It uses
+'AC_CHECK_DECLS([stpcpy])' in 'configure.ac' to test this, and provides
+the perhaps slightly less efficient alternative
+
+ #if !(defined HAVE_DECL_STPCPY && HAVE_DECL_STPCPY)
+ static inline char *stpcpy(char *dest, const char *src)
+ {
+ return strcpy(dest, src) + strlen(src);
+ }
+ #endif
+
+in the file 'Utility.h'.
+
+Static functions
+................
+
+Functions used in only one file should be declared 'static'; they
+require no prototype except as forward declaration.
+
+Extern functions
+................
+
+Functions not declared 'static', usually because they are used in
+several files, require an ('extern') prototype in exactly one header
+file, which is 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. There should be no 'extern' declarations
+sprinkled throughout the C code (with or without comments as to where
+that function is defined).
+
+Variable declarations
+.....................
+
+The declaration of global variables follows analogous rules: they are
+either declared 'static' if used in only one file or declared 'extern'
+in exactly one header and instantiated in exactly one file.
+
+8.2 Const
+=========
+
+The 'const' feature of C is valuable, but easy to mis-use.
+
+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 the actual arguments are often string literals. It is
+perfectly legitimate and safe to use a type 'char*' value for a type
+'const char*' variable (in an assignment, as initializer, as function
+argument, or as return value). It is equally safe to use a type
+'char**' value for a type 'const char*const*' variable, but not for a
+type 'const char**' variable since that might cause modification of a
+quantity supposed to be constant.
+
+ Getting all 'const' qualifiers right can get quite involved but can
+almost always be done. There are only a couple 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 'libfreetype' (but,
+thankfully, not for 'zlib' nowadays).
+
+What must be avoided with 'const'
+.................................
+
+The GCC compiler warnings "assignment discards qualifiers..." and
+analogous warnings for "initialization", "passing arg", or "return" must
+be strenously avoided in our own code. The only exception is when they
+are caused by X11 headers or macros or other third party code.
+
+What should be avoided with 'const'
+...................................
+
+A type cast, e.g., from 'const char*' to 'char*' does not solve any
+problems; depending on warning options, it may only hide them.
+Therefore such casts should be avoided whenever possible and otherwise
+must be carefully analyzed to make sure that they cannot cause the
+modification of quantities supposed to be constant.
+