ahill/toybox
1
0
Fork 0
mirror of https://codeberg.org/landley/toybox.git synced 2026-01-26 14:13:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update web pages.

Browse Source
This commit is contained in:
Rob Landley 2007-12-13 07:00:27 -06:00
parent 8eff1e6393
commit 4e68de1ef8
5 changed files with 254 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

213
www/code.html Executable file
View File

@ -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" -->

8
www/design.html
View File

@ -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&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 @@ 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>

2
www/footer.html
View File

@ -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>

2
www/header.html
View File

@ -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>

69
www/index.html
View File

@ -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><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>
export, set, unset, read, trap, and exec. (Note: not done yet.)</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>
<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>