changeset 1167:17387db4d979 draft

New section on #including header files.
author Rob Landley <rob@landley.net>
date Fri, 27 Dec 2013 06:53:15 -0600
parents 8b3cf974c66d
children fbe6804a3f33
files www/code.html
diffstat 1 files changed, 27 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/www/code.html	Thu Dec 26 09:37:03 2013 -0600
+++ b/www/code.html	Fri Dec 27 06:53:15 2013 -0600
@@ -224,6 +224,33 @@
 <a href="#lib_args">get_optflags()</a> for details.</p></li>
 </ul>
 
+<a name="headers" /><h2>Headers.</h2>
+
+<p>Commands generally don't have their own headers. If it's common code
+it can live in lib/, if it isn't put it in the command's .c file. (The line
+between implementing multiple commands in a C file via OLDTOY() to share
+infrastructure and moving that shared infrastructure to lib/ is a judgement
+call. Try to figure out which is simplest.)</p>
+
+<p>The top level toys.h should #include all the standard (posix) headers
+that any command uses. (Partly this is friendly to ccache and partly this
+makes the command implementations shorter.) Individual commands should only
+need to include nonstandard headers that might prevent that command from
+building in some context we'd care about (and thus requiring that command to
+be disabled to avoid a build break).</p>
+
+<p>Target-specific stuff (differences between compiler versions, libc versions,
+or operating systems) should be confined to lib/portability.h and
+lib/portability.c. (There's even some minimal compile-time environment probing
+that writes data to generated/portability.h, see scripts/genconfig.sh.)</p>
+
+<p>Only include linux/*.h headers from individual commands (not from other
+headers), and only if you really need to. Data that varies per architecture
+is a good reason to include a header. If you just need a couple constants
+that haven't changed since the 1990's, it's ok to #define them yourself or
+just use the constant inline with a comment explaining what it is. (A
+#define that's only used once isn't really helping.)</p>
+
 <p><a name="top" /><h2>Top level directory.</h2></p>
 
 <p>This directory contains global infrastructure.</p>