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.
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.
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.
lib: llist, getmountlist(), error_msg/error_exit, xmalloc(), strlcpy(), xexec(), xopen()/xread(), xgetcwd(), xabspath(), find_in_path(), itoa().
Contains the main() function where execution starts, plus common infrastructure to initialize global variables and select which command to run.
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.
The following global variables are defined here:
struct toy_list toy_list[] - 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).
This is a read-only array initialized at compile time by defining macros and #including toys/toylist.h.
Members of struct toy_list include:
char *name - the name of this command.
void (*toy_main)(void) - function pointer to run this command.
char *options - 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().
int flags - 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.
struct toy_context toys - global structure containing information common to all commands, initializd by toy_init(). Members of this structure include:
struct toy_list *which - a pointer to this command's toy_list structure. Mostly used to grab the name of the running command (toys->which.name).
int exitval - 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.
char **argv - "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.
Most commands don't use this field, instead the use optargs, optflags, and the fields in the toy union initialized by get_optflags().
unsigned optflags - 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.
char **optargs - 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.
int exithelp - Whether error_exit() should print a usage message via help_main() before exiting. (True during option parsing, defaults to false afterwards.)
union toy_union toy - Union of structures containing each command's global variables.
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.
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.
The following functions are defined here:
struct toy_list *toy_find(char *name) - Return the toy_list structure for this command name, or NULL if not found.
void toy_init(struct toy_list *which, char *argv[]) - fill out the global toys structure, calling get_optargs() if necessary.
void toy_exec(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.
void toybox_main(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.
Top level configuration file in a stylized variant of kconfig format. Includes toys/Config.in.
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.
.config - 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.
gen_config.h - list of CFG_SYMBOL and USE_SYMBOL() macros, generated from .config by a sed invocation in the top level Makefile.
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 #ifdef Considered Harmful for more information.)
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.
Included from the top level Config.in, contains one or more configuration entries for each command.
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.
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)
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).
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.
The first time this header is #included, it defines structures and produces function prototypes for the commands in the toys directory.
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.
#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.
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.)
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.
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.
Menuconfig infrastructure copied from the Linux kernel. See the Linux kernel's Documentation/kbuild/kconfig-language.txt