diff options
| -rwxr-xr-x | www/code.html | 213 | ||||
| -rw-r--r-- | www/design.html | 8 | ||||
| -rw-r--r-- | www/footer.html | 2 | ||||
| -rw-r--r-- | www/header.html | 2 | ||||
| -rwxr-xr-x | www/index.html | 63 |
5 files changed, 251 insertions, 37 deletions
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" --> diff --git a/www/design.html b/www/design.html index 27e8af43..0c3815d4 100644 --- a/www/design.html +++ b/www/design.html @@ -181,9 +181,9 @@ don't understand the problem until you _have_ solved it.)</p> 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&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 @@ programmers should strive to be lazy and dumb</a>?</p> <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 --git a/www/footer.html b/www/footer.html index 546f63b8..5647c9f4 100644 --- a/www/footer.html +++ b/www/footer.html @@ -1,7 +1,7 @@ </td></tr></table> <hr /> <table width="100%"> -<tr><td>Copyright 2006 Rob Landley <rob@landley.net></td></tr> +<tr><td>Copyright 2007 Rob Landley <rob@landley.net></td></tr> </table> </body> </html> diff --git a/www/header.html b/www/header.html index eeda4aa5..6b714b24 100644 --- a/www/header.html +++ b/www/header.html @@ -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 --git a/www/index.html b/www/index.html index a201bd8e..51f3de79 100755 --- a/www/index.html +++ b/www/index.html @@ -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 @@ checked in yet, but I'm working on that.</p> <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 @@ archive</a>.</p> <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 @@ to bother with them.</p> the behavior of existing commands (although not generally looking at their source code).</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 -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> +<b><h2><a name="status" />What commands are implemented?</h2></b> -<p>[TODO]</p> +<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> -<b><h3>Development tools:</h3></b> +<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>Commands: ar, make [TODO]</p> +<p>The following are partially implemented commands that don't actually do +anything yet: mke2fs, md5sum.</p> -<b><h2><a name="status />What commands are implemented?</h2></b> +<p>For more information, see <a href=todo.txt>the todo list</a>.</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> +<b><h3>Command Shell</h3></b> +<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>Infrastructure:</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. (Note: not done yet.)</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> |