# HG changeset patch
# User Rob Landley <rob@landley.net>
# Date 1197550827 21600
# Node ID f868f933bd3b29d0db54812a91e495ead8ee9517
# Parent  3f8c97fd1f93eb460d40f9f77555e32ed2042020
Update web pages.

diff -r 3f8c97fd1f93 -r f868f933bd3b www/code.html
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/www/code.html	Thu Dec 13 07:00:27 2007 -0600
@@ -0,0 +1,213 @@
+<!--#include file="header.html" -->
+
+<p><h1>Infrastructure:</h1></p>
+
+<p>The toybox source code is in three directories.  The top level directory
+contains the file main.c and the header file toys.h.  The "lib" directory
+contains generic functions shared by multiple commands.  The "toys" directory
+contains the implementations of individual commands.</p>
+
+<p><h2>Top level directory.</h2></p>
+
+<p>lib: llist, getmountlist(), error_msg/error_exit, xmalloc(),
+strlcpy(), xexec(), xopen()/xread(), xgetcwd(), xabspath(), find_in_path(),
+itoa().</p>
+
+<h3>main.c</h3>
+<p>Contains the main() function where execution starts, plus
+common infrastructure to initialize global variables and select which command
+to run.</p>
+
+<p>Execution starts in main() which removes the path from the first command
+name and calls toybox_main(), which calls toy_exec(), which calls toy_find(),
+toy_init() and the appropriate command's function from toy_list.</p>
+
+<p>The following global variables are defined here:</p>
+<ul>
+<li><p>struct toy_list <b>toy_list[]</b> - array describing all the
+commands currently configured into toybox.  The first entry (toy_list[0]) is
+for the "toybox" multiplexer command, which runs all the other built-in commands
+without symlinks by using its first argument as the name of the command to
+run and the rest as that command's argument list (ala "./toybox echo hello").
+The remaining entries are the commands in alphabetical order (for efficient
+binary search).</p>
+
+<p>This is a read-only array initialized at compile time by
+defining macros and #including toys/toylist.h.</p>
+
+<p>Members of struct toy_list include:</p>
+<ul>
+<li><p>char *<b>name</b> - the name of this command.</p></li>
+<li><p>void (*<b>toy_main</b>)(void) - function pointer to run this
+command.</p></li>
+<li><p>char *<b>options</b> - command line option string (used by
+get_optflags() in lib/args.c to intialize toys.optflags, toys.optargs, and
+entries in the toy union).  If this is NULL, no option parsing is done before
+calling toy_main().</p></li>
+<li><p>int <b>flags</b> - Behavior flags such as where to install this command
+(in usr/bin/sbin) and whether this is a shell builtin (NOFORK) or a standalone
+command.</p></li>
+</ul><br>
+</li>
+
+<li><p>struct toy_context <b>toys</b> - global structure containing information
+common to all commands, initializd by toy_init().  Members of this structure
+include:</p>
+<ul>
+<li><p>struct toy_list *<b>which</b> - a pointer to this command's toy_list
+structure.  Mostly used to grab the name of the running command
+(toys->which.name).</p>
+</li>
+<li><p>int <b>exitval</b> - Exit value of this command.  Defaults to zero.  The
+error_exit() functions will return 1 if this is zero, otherwise they'll
+return this value.</p></li>
+<li><p>char **<b>argv</b> - "raw" command line options, I.E. the original
+unmodified string array passed in to main().  Note that modifying this changes
+"ps" output, and is not recommended.</p>
+<p>Most commands don't use this field, instead the use optargs, optflags,
+and the fields in the toy union initialized by get_optflags().</p>
+</li>
+<li><p>unsigned <b>optflags</b> - Command line option flags, set by
+get_optflags().  Indicates which of the command line options listed in
+toys->which.options were seen this time.  See get_optflags() for
+details.</p></li>
+<li><p>char **<b>optargs</b> - Null terminated array of arguments left over
+after get_optflags() removed all the ones it understood.  Note: optarg[0] is
+the first argument, not the command name.  Use toys.which->name for the command
+name.</p></li>
+<li><p>int <b>exithelp</b> - Whether error_exit() should print a usage message
+via help_main() before exiting.  (True during option parsing, defaults to
+false afterwards.)</p></li>
+</ul><br>
+
+<li><p>union toy_union <b>toy</b> - Union of structures containing each
+command's global variables.</p>
+
+<p>A command that needs global variables should declare a structure to
+contain them all, and add that structure to this union.  A command should never
+declare global variables outside of this, because such global variables would
+allocate memory when running other commands that don't use those global
+variables.</p>
+
+<p>The first few fields of this structure can be intialized by get_optargs(),
+as specified by the options field off this command's toy_list entry.  See
+the get_optargs() description in lib/args.c for details.</p>
+</li>
+
+<li><b>toybuf</b> - a common scratch space buffer (4096 byte char array) so
+commands don't need to allocate their own.  Any command is free to use this,
+and it should never be directly referenced by functions in lib/ (although
+commands are free to pass toybuf in to a library function as an argument).</li>
+</ul>
+
+<p>The following functions are defined here:</p>
+<ul>
+<li><p>struct toy_list *<b>toy_find</b>(char *name) - Return the toy_list
+structure for this command name, or NULL if not found.</p></li>
+<li>void <b>toy_init</b>(struct toy_list *which, char *argv[]) - fill out
+the global toys structure, calling get_optargs() if necessary.</li>
+<li><p>void <b>toy_exec</b>(char *argv[]) - Run a built-in command with arguments.
+Calls toy_find() on the first argument (which must be just a command name
+without path).  Returns if it can't find this command, otherwise calls
+toy_init(), toys->which.toy_main(), and exit() instead of returning.</p></li>
+
+<li><p>void <b>toybox_main</b>(void) - the main function for multiplexer
+command.  Given a command name as its first argument, calls toy_exec() on its
+arguments.  With no arguments, it lists available commands.  If the first
+argument starts with "-" it lists each command with its default install
+path prepended.</p></li>
+
+</ul>
+
+<h3>Config.in</h3>
+
+<p>Top level configuration file in a stylized variant of
+<a href=http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt>kconfig</a> format.  Includes toys/Config.in.</p>
+
+<p>These files are directly used by "make menuconfig" to select which commands
+to build into toybox (thus generating a .config file), and by
+scripts/config2help.py to generate toys/help.h.</p>
+
+<h3>Temporary files:</h3>
+
+<ul>
+<li><p><b>.config</b> - Configuration file generated by kconfig, indicating
+which commands (and options to commands) are currently enabled.  Used
+to generate gen_config.h and the toys/*.c dependency list.</p></li>
+
+<li><p><b>gen_config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros,
+generated from .config by a sed invocation in the top level Makefile.</p>
+
+<p>CFG_SYMBOL is a comple time constant set to 1 for enabled symbols and 0 for
+disabled symbols.  This can be used via normal if() statements to remove
+code at compile time via the optimizer's dead code elimination, which removes
+from the binary any code that cannot be reached.  This saves space without
+cluttering the code with #ifdefs or leading to configuration dependent build
+breaks.  (See the 1992 Usenix paper
+<a href=http://www.chris-lott.org/resources/cstyle/ifdefs.pdf>#ifdef
+Considered Harmful</a> for more information.)</p>
+
+<p>USE_SYMBOL(code) evaluates to the code in parentheses when the symbol
+is enabled, and nothing when the symbol is disabled.  This can be used
+for things like varargs or variable declarations which can't always be
+eliminated by a compile time removalbe test on CFG_SYMBOL.  Note that
+(unlike CFG_SYMBOL) this is really just a variant of #ifdef, and can
+still result in configuration dependent build breaks.  Use with caution.</p>
+</li>
+</ul>
+
+<p><h2>toys/ directory.</h2></p>
+
+<h3>toys/Config.in</h3>
+
+<p>Included from the top level Config.in, contains one or more
+configuration entries for each command.</p>
+
+<p>Each command has a configuration entry matching the command name (except
+that configuration symbols are uppercase and command names are lower case).
+Options to commands start with the command name followed by an underscore and
+the option name.  Global options are attachd to the "toybox" command,
+and thus use the prefix "TOYBOX_".  This organization is used by
+scripts/cfg2files to select which </p>
+
+<p>A commands with multiple names (or multiple similar commands implemented in
+the same .c file) should have config symbols prefixed with the name of their
+C file.  I.E. config symbol prefixes are NEWTOY() names.  If OLDTOY() names
+have config symbols they're options (symbols with an underscore and suffix)
+to the NEWTOY() name.  (See toys/toylist.h)</p>
+
+<h3>toys/toylist.h</h3>
+<p>
+
+<h3>toys/help.h</h3>
+
+<p>#defines two help text strings for each command: a single line
+command_help and an additinal command_help_long.  This is used by help_main()
+in toys/help.c to display help for commands.</p>
+
+<p>Although this file is generated from Config.in help entries by
+scripts/config2help.py, it's shipped in release tarballs so you don't need
+python on the build system.  (If you check code out of source control, or
+modify Config.in, then you'll need python installed to rebuild it.)</p>
+
+<p>This file contains help for all commands, regardless of current
+configuration, but only the currently enabled ones are entered into help_data[]
+in toys/help.c.</p>
+
+<h2>lib/ directory.</h2>
+
+<h2>scripts/ directory.</h2>
+
+<h3>scripts/cfg2files.sh</h3>
+
+<p>Run .config through this filter to get a list of enabled commands, which
+is turned into a list of files in toys via a sed invocation in the top level
+Makefile.
+</p>
+
+<h2>kconfig/ directory.</h2>
+
+<p>Menuconfig infrastructure copied from the Linux kernel.  See the
+Linux kernel's Documentation/kbuild/kconfig-language.txt</p>
+
+<!--#include file="footer.html" -->
diff -r 3f8c97fd1f93 -r f868f933bd3b www/design.html
--- a/www/design.html	Wed Dec 12 16:19:00 2007 -0600
+++ b/www/design.html	Thu Dec 13 07:00:27 2007 -0600
@@ -181,9 +181,9 @@
 that works and has been paid for is a corporate asset not lightly abandoned.
 Open source software can afford to re-implement code that works, over and
 over from scratch, for incremental gains.  Before toybox, the unix command line
-has already been reimplemented from scratch several in a row (the
-original Unix and BSD tools, the GNU tools, BusyBox...)
-but maybe toybox can do a better job. :)</p>
+has already been reimplemented from scratch several times in a row (the
+original AT&amp;T Unix command line in assembly and then in C, the BSD
+versions, the GNU tools, BusyBox...) but maybe toybox can do a better job. :)</p>
 
 <p>P.S.  How could I resist linking to an article about
 <a href=http://blog.outer-court.com/archive/2005-08-24-n14.html>why
@@ -194,7 +194,7 @@
 <b><h3>Platforms</h3></b>
 <p>Toybox should run on every hardware platform Linux runs on.  Other
 posix/susv3 environments (perhaps MacOS X or newlib+libgloss) are vaguely
-interesting but only if they're easy to support, I'm not going to spend much
+interesting but only if they're easy to support; I'm not going to spend much
 effort on them.</p>
 
 <p>I don't do windows.</p>
diff -r 3f8c97fd1f93 -r f868f933bd3b www/footer.html
--- a/www/footer.html	Wed Dec 12 16:19:00 2007 -0600
+++ b/www/footer.html	Thu Dec 13 07:00:27 2007 -0600
@@ -1,7 +1,7 @@
 </td></tr></table>
 <hr />
 <table width="100%">
-<tr><td>Copyright 2006 Rob Landley &lt;rob@landley.net&gt;</td></tr>
+<tr><td>Copyright 2007 Rob Landley &lt;rob@landley.net&gt;</td></tr>
 </table>
 </body>
 </html>
diff -r 3f8c97fd1f93 -r f868f933bd3b www/header.html
--- a/www/header.html	Wed Dec 12 16:19:00 2007 -0600
+++ b/www/header.html	Thu Dec 13 07:00:27 2007 -0600
@@ -16,6 +16,8 @@
     <li><a href="index.html">News</a></li>
     <li><a href="about.html">What is it?</a></li>
     <li><a href="design.html">Design Docs</a></li>
+    <li><a href="code.html">Source walkthrough</a></li>
+    <li><a href="todo.txt">TODO list</a></li>
   </ul>
   <b>Download</b>
   <ul>
diff -r 3f8c97fd1f93 -r f868f933bd3b www/index.html
--- a/www/index.html	Wed Dec 12 16:19:00 2007 -0600
+++ b/www/index.html	Thu Dec 13 07:00:27 2007 -0600
@@ -1,5 +1,9 @@
 <!--#include file="header.html" -->
 
+<p><b>December 12, 2007</b> - Updated the list of implemented applications,
+put up a <a href=todo.txt>todo list</a> and <a href=code.html>infrastructure
+documentation</a>.  Expect another release towards the end of the month.</p>
+
 <p><b>June 18, 2007</b> - Put out
 <a href=downloads/toybox-0.0.3.tar.bz2>toybox-0.0.3.tar.bz2</a> since it's
 been too long since I did something like that.  This one implements
@@ -14,7 +18,8 @@
 <p>I don't have nearly as much time to work on this as I'd like, but I'm making
 a little progress.</p>
 
-<p>Jan 31: Screwing up the web page a bit, adding an index bar along the side
+<p><b>January 31, 2007</b> -
+Screwing up the web page a bit, adding an index bar along the side
 which doesn't properly connect up to anything yet.  (Busy implementing
 mke2fs and gene2fs.)</p>
 
@@ -25,12 +30,12 @@
 
 <h2><a name="what" />What is ToyBox?</h2>
 
-<p>The Toybox project is creating simple implementations of all the Linux
-command line utilities.  Other goals are small size (the produced binaries
-should total less than a megabyte, uncompressed), speed of execution, and
-correctness of implementation (which is related to standards compliance, but
-isn't quite the same thing).
-Click for <a href="design.html">more about the design goals</a></p>
+<p>The goal of the Toybox project is to create simple implementations of all
+the important Linux command line utilities.  These implementations should
+be small (the entire project should total less than a megabyte, uncompressed),
+fast, simple, and correctly implemented (which is related to standards
+compliance, but isn't quite the same thing).  Click for
+<a href="design.html">more about the design goals</a></p>
 
 <p>Toybox has configurable levels of functionality, and should scale from tiny
 embedded systems up to full general purpose desktop and development
@@ -62,38 +67,32 @@
 the behavior of existing commands (although not generally looking at their
 source code).</p>
 
+<b><h2><a name="status" />What commands are implemented?</h2></b>
+
+<p>The following commands are currently implemented: basename, catv, chroot,
+count, df, dirname, dmesg, echo, false, hello, mkfifo, oneit, pwd, sha1sum,
+sleep, sync, true, tty, which, yes.</p>
+
+<p>The following commands are partly implemented, in a somewhat usable but not
+necessarily complete state: bzcat/bunzip2, help, mke2fs, netcat/nc, sh/toysh,
+mdev, touch, readlink.</p>
+
+<p>The following are partially implemented commands that don't actually do
+anything yet: mke2fs, md5sum.</p>
+
+<p>For more information, see <a href=todo.txt>the todo list</a>.</p>
+
 <b><h3>Command Shell</h3></b>
-<p>The Toybox Shell aims to be a reasonable bash replacement.  It implements
-the "sh" and "toysh" commands, plus the built-in commands "cd" and "exit".
-The following additional commands may be built into the shell (but not as
+<p>The Toybox Shell (toysh) aims to be a reasonable bash replacement.  It
+implements the "sh" and "toysh" commands, plus the built-in commands "cd" and
+"exit".  This is the largest single sub-project in toybox.</p>
+
+<p>The following additional commands may be built into the shell (but not as
 separate executables): cd, exit, if, while, for, function, fg, bg, jobs, source,
 <a href="http://www.opengroup.org/onlinepubs/009695399/utilities/alias.html">alias</a>,
-export, set, unset, read, trap, and exec.</p>
-
-<b><h3>General Purpose Commands:</h3></b>
-
-<p>[TODO]</p>
-
-<b><h3>Development tools:</h3></b>
-
-<p>Commands: ar, make [TODO]</p>
-
-<b><h2><a name="status />What commands are implemented?</h2></b>
+export, set, unset, read, trap, and exec.  (Note: not done yet.)</p>
 
-<p>Toybox is a work in progress, and nowhere near a 1.0 release.  The first
-commit was September 27, 2006, and work is ongoing.</p>
-
-<p>Partial (in progress): sh/toysh (cd, exit), df, which.</p>
-
-<p>Complete: hello, pwd.</p>
-
-<p>Infrastructure:</p>
-
-<ul>
-<li>main: toy_list[], toy_find(), toy_exec(), main/toybox_main().</li>
-<ul>lib: llist, getmountlist(), error_msg/error_exit, xmalloc(),
-strlcpy(), xexec(), xopen()/xread(), xgetcwd(), xabspath(), find_in_path(),
-itoa().</li>
+</ul>
 
 <b><h2><a name="downloads" />Download</h2></b>