Mercurial > hg > toybox
changeset 1303:2b89b13df19e draft
Update docs for example and pending directories.
author | Rob Landley <rob@landley.net> |
---|---|
date | Thu, 22 May 2014 08:16:55 -0500 |
parents | 1253f0c3dd53 |
children | ee18ddbb783b |
files | www/code.html |
diffstat | 1 files changed, 32 insertions(+), 18 deletions(-) [+] |
line wrap: on
line diff
--- a/www/code.html Wed May 21 07:57:48 2014 -0500 +++ b/www/code.html Thu May 22 08:16:55 2014 -0500 @@ -112,8 +112,8 @@ <li><a href="#lib_dirtree">lib/dirtree.c</a></li> </ul> <li>The <a href="#toys">toys directory</a> contains the C files implementating -each command. Currently it contains three subdirectories: -posix, lsb, and other.</li> +each command. Currently it contains five subdirectories categorizing the +commands: posix, lsb, other, example, and pending.</li> <li>The <a href="#scripts">scripts directory</a> contains the build and test infrastructure.</li> <li>The <a href="#kconfig">kconfig directory</a> contains the configuration @@ -130,27 +130,41 @@ formatted comments and macros in the C file. (See the description of the <a href="#generated">"generated" directory</a> for details.)</p> -<p>Currently there are three subdirectories under "toys", one for commands +<p>Currently there are five subdirectories under "toys", one for commands defined by the POSIX standard, one for commands defined by the Linux Standard -Base, and one for all other commands. (This is just for developer convenience -sorting them, the directories are otherwise functionally identical.)</p> +Base, an "other" directory for commands not covered by an obvious standard, +a directory of example commands (templates to use when starting new commands), +and a "pending" directory of commands that need further review/cleanup +before moving to one of the other directories (run these at your own risk, +cleanup patches welcome). +These directories are just for developer convenience sorting the commands, +the directories are otherwise functionally identical. To add a new category, +create the appropriate directory with a README file in it whose first line +is the description menuconfig should use for the directory.)</p> -<p>An easy way to start a new command is copy the file "toys/other/hello.c" to -the name of the new command, and modify this copy to implement the new command. -This file is an example command meant to be used as a "skeleton" for -new commands (more or less by turning every instance of "hello" into the +<p>An easy way to start a new command is copy the file "toys/example/hello.c" +to the name of the new command, and modify this copy to implement the new +command (more or less by turning every instance of "hello" into the name of your command, updating the command line arguments, globals, and -help data, and then filling out its "main" function with code that does -something interesting). It provides examples of all the build infrastructure -(including optional elements like command line argument parsing and global -variables that a "hello world" program doesn't strictly need).</p> +help data, and then filling out its "main" function with code that does +something interesting).</p> + +<p>You could also start with "toys/example/skeleton.c", which provides a lot +more example code (showing several variants of command line option +parsing, how to implement multiple commands in the same file, and so on). +But usually it's just more stuff to delete.</p> <p>Here's a checklist of steps to turn hello.c into another command:</p> <ul> -<li><p>First "cd toys/other" and "cp hello.c yourcommand.c". Note that the name -of this file is significant, it's the name of the new command you're adding -to toybox. Open your new file in your favorite editor.</p></li> +<li><p>First "cp toys/example/hello.c toys/other/yourcommand.c" and open +the new file in your preferred text editor.</p> +<ul><li><p>Note that the +name of the new file is significant: it's the name of the new command you're +adding to toybox. The build includes all *.c files under toys/*/ whose +names are a case insensitive match for an enabled config symbol. So +toys/posix/cat.c only gets included if you have "CAT=y" in ".config".</p></li> +</ul></p></li> <li><p>Change the one line comment at the top of the file (currently "hello.c - A hello world program") to describe your new file.</p></li> @@ -168,7 +182,7 @@ <ol> <li><p>the name used to run your command</p></li> -<li><p>the command line argument <a href="#lib_args">option parsing string</a> (NULL if none)</p></li> +<li><p>the command line argument <a href="#lib_args">option parsing string</a> (0 if none)</p></li> <li><p>a bitfield of TOYFLAG values (defined in toys.h) providing additional information such as where your command should be installed on a running system, whether to blank umask @@ -216,7 +230,7 @@ where execution of your command starts. Your command line options are already sorted into this.optflags, this.optargs, this.optc, and the GLOBALS() as appropriate by the time this function is called. (See -<a href="#lib_args">get_optflags()</a> for details.</p></li> +<a href="#lib_args">get_optflags()</a> for details.)</p></li> </ul> <a name="headers" /><h2><a href="#headers">Headers.</a></h2>