| <!--#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 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>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> |
| |
| <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" --> |