www/code.html

<!--#include file="header.html" -->

<p><h1>Code style</h1></p>

<p>Toybox source is formatted to be read with 4-space tab stops.  Each file
starts with a special comment telling vi to set the tab stop to 4.  Note that
one of the bugs in Ubuntu 7.10 broke vi's ability to parse these comments; you
must either rebuild vim from source, or go ":ts=4" yourself each time you load
the file.</p>

<p>Gotos are allowed for error handling, and for breaking out of
nested loops.  In general, a goto should only jump forward (not back), and
should either jump to the end of an outer loop, or to error handling code
at the end of the function.  Goto labels are never indented: they override the
block structure of the file.  Putting them at the left edge makes them easy
to spot as overrides to the normal flow of control, which they are.</p>

<p><h1>Infrastructure:</h1></p>

<p>The toybox source code is in following directories:</p>
<ul>
<li>The <a href="#top">top level directory</a> contains the file main.c (were
execution starts), the header file toys.h (included by every command), and
other global infrastructure.</li>
<li>The <a href="#lib">lib directory</a> contains common functions shared by
multiple commands.</li>
<li>The <a href="#toys">toys directory</a> contains the C files implementating
each command.</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
infrastructure implementing menuconfig (copied from the Linux kernel).</li>
<li>The <a href="#generated">generated directory</a> contains intermediate
files generated from other parts of the source code.</li>
</ul>

<p><h1>Adding a new command</h1></p>
<p>To add a new command to toybox, add a C file implementing that command to
the toys directory.  No other files need to be modified; the build extracts
other information it needs (such as command line arguments) from specially
formatted comments and macros in the C file.  (See the description of the
<a href="#generated">generated directory</a> for details.)</p>

<p>An easy way to start a new command is copy the file "hello.c" to
the name of the new command, and modify this copy to implement the new command.
This file is a small, simple command meant to be used as a "skeleton" for
new commands (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).</p>

<p>Here's a checklist of steps to turn hello.c into another command:</p>

<ul>
<li><p>First "cd toys" 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>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>

<li><p>Change the copyright notice to your name, email, and the current
year.</p></li>

<li><p>Give a URL to the relevant standards document, or say "Not in SUSv3" if
there is no relevant standard.  (Currently both lines are there, delete
whichever is appropriate.)  The existing link goes to the directory of SUSv3
command line utility standards on the Open Group's website, where there's often
a relevant commandname.html file.  Feel free to link to other documentation or
standards as appropriate.</p></li>

<li><p>Update the USE_YOURCOMMAND(NEWTOY(yourcommand,NULL,0)) line.  This
specifies the name used to run your command, the command line arguments (NULL
if none), and where your command should be installed on a running system.  See
[TODO] for details.</p></li>

<li><p>Change the kconfig data (from "config YOURCOMMAND" to the end of the
comment block) to supply your command's configuration and help
information.  The uppper case config symbols are used by menuconfig, and are
also what the CFG_ and USE_() macros are generated from (see [TODO]).  The
help information here is used by menuconfig, and also by the "help" command to
describe your new command.  (See [TODO] for details.)  By convention,
unfinished commands default to "n" and finished commands default to "y".<p></li>

<li><p>Update the DEFINE_GLOBALS() macro to contain your command's global
variables, and also change the name "hello" in the #define TT line afterwards
to the name of your command.  If your command has no global variables, delete
this macro (and the #define TT line afterwards).  Note that if you specified
two-character command line arguments in NEWTOY(), the first few global
variables will be initialized by the automatic argument parsing logic, and
the type and order of these variables must correspond to the arguments
specified in NEWTOY().  See [TODO] for details.</p></li>

<li><p>Change the "#define TT this.hello" line to use your command name in
place of the "hello".  This is a shortcut to access your global variables
as if they were members of the global struct "TT".  (Access these members with
a period ".", not a right arrow "->".)</p></li>

<li><p>Rename hello_main() to yourcommand_main().  This is the main() function
where execution off your command starts.  See [TODO] to figure out what
happened to your command line arguments and how to access them.</p></li>
</ul>

<p><a name="top" /><h2>Top level directory.</h2></p>

<p>This directory contains global infrastructure.

<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.  The "toybox" multiplexer command is also defined here.  (This is the
only command defined outside of the toys directory.)</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.  If
the command is "toybox", execution returns to toybox_main(), otherwise
the call goes to the appropriate command_main() from the toys directory.</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>char toybuf[4096]</b> - a common scratch space buffer 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><p>void <b>toy_init</b>(struct toy_list *which, char *argv[]) - fill out
the global toys structure, calling get_optargs() if necessary.</p></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>Directory toys/</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 (although
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 toys/*.c files to compile for a given
.config.</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>The first half of this file prototypes all the structures to hold
global variables for each command, and puts them in toy_union.  These
prototypes are only included if the macro NEWTOY isn't defined (in which
case NEWTOY is defined to a default value that produces function
prototypes).</p>

<p>The second half of this file lists all the commands in alphabetical
order, along with their command line arguments and install location.
Each command has an appropriate configuration guard so only the commands that
are enabled wind up in the list.</p>

<p>The first time this header is #included, it defines structures and
produces function prototypes for the commands in the toys directory.</p>


<p>The first time it's included, it defines structures and produces function
prototypes.
  This
is used to initialize toy_list in main.c, and later in that file to initialize
NEED_OPTIONS (to figure out whether the command like parsing logic is needed),
and to put the help entries in the right order in toys/help.c.</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>Directory lib/</h2>

<p>lib: llist, getmountlist(), error_msg/error_exit, xmalloc(),
strlcpy(), xexec(), xopen()/xread(), xgetcwd(), xabspath(), find_in_path(),
itoa().</p>



<h2>Directory scripts/</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>Directory kconfig/</h2>

<p>Menuconfig infrastructure copied from the Linux kernel.  See the
Linux kernel's Documentation/kbuild/kconfig-language.txt</p>

<!--#include file="footer.html" -->