Mercurial > hg > toybox
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>