From 4e68de1ef854fadd74fcb63c3a5ad15dce457a4c Mon Sep 17 00:00:00 2001
From: Rob Landley <rob@landley.net>
Date: Thu, 13 Dec 2007 07:00:27 -0600
Subject: Update web pages.

---
 www/code.html | 213 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 213 insertions(+)
 create mode 100755 www/code.html

(limited to 'www/code.html')

diff --git a/www/code.html b/www/code.html
new file mode 100755
index 00000000..12dd6785
--- /dev/null
+++ b/www/code.html
@@ -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" -->
-- 
cgit v1.2.3