1 <!--#include file="header.html" -->
3 <p><h1>Code style</h1></p>
5 <p>Toybox source is formatted to be read with 4-space tab stops. Each file
6 starts with a special comment telling vi to set the tab stop to 4. Note that
7 one of the bugs in Ubuntu 7.10 broke vi's ability to parse these comments; you
8 must either rebuild vim from source, or go ":ts=4" yourself each time you load
11 <p>Gotos are allowed for error handling, and for breaking out of
12 nested loops. In general, a goto should only jump forward (not back), and
13 should either jump to the end of an outer loop, or to error handling code
14 at the end of the function. Goto labels are never indented: they override the
15 block structure of the file. Putting them at the left edge makes them easy
16 to spot as overrides to the normal flow of control, which they are.</p>
18 <p>The primary goal of toybox is _simple_ code. Small is second,
19 speed and lots of features come in somewhere after that. Note that
20 environmental dependencies are a type of complexity, so needing other packages
21 to build or run is a downside. For example, don't use curses when you can
22 output ansi escape sequences instead.</p>
24 <p><h1>Infrastructure:</h1></p>
26 <p>The toybox source code is in following directories:</p>
28 <li>The <a href="#top">top level directory</a> contains the file main.c (were
29 execution starts), the header file toys.h (included by every command), and
30 other global infrastructure.</li>
31 <li>The <a href="#lib">lib directory</a> contains common functions shared by
32 multiple commands.</li>
33 <li>The <a href="#toys">toys directory</a> contains the C files implementating
35 <li>The <a href="#scripts">scripts directory</a> contains the build and
36 test infrastructure.</li>
37 <li>The <a href="#kconfig">kconfig directory</a> contains the configuration
38 infrastructure implementing menuconfig (copied from the Linux kernel).</li>
39 <li>The <a href="#generated">generated directory</a> contains intermediate
40 files generated from other parts of the source code.</li>
43 <p><h1>Adding a new command</h1></p>
44 <p>To add a new command to toybox, add a C file implementing that command to
45 the toys directory. No other files need to be modified; the build extracts
46 all the information it needs (such as command line arguments) from specially
47 formatted comments and macros in the C file. (See the description of the
48 <a href="#generated">generated directory</a> for details.)</p>
50 <p>An easy way to start a new command is copy the file "hello.c" to
51 the name of the new command, and modify this copy to implement the new command.
52 This file is an example command meant to be used as a "skeleton" for
53 new commands (more or less by turning every instance of "hello" into the
54 name of your command, updating the command line arguments, globals, and
55 help data, and then filling out its "main" function with code that does
56 something interesting). It provides examples of all the build infrastructure
57 (including optional elements like command line argument parsing and global
58 variables that a "hello world" program doesn't strictly need).</p>
60 <p>Here's a checklist of steps to turn hello.c into another command:</p>
63 <li><p>First "cd toys" and "cp hello.c yourcommand.c". Note that the name
64 of this file is significant, it's the name of the new command you're adding
65 to toybox. Open your new file in your favorite editor.</p></li>
67 <li><p>Change the one line comment at the top of the file (currently
68 "hello.c - A hello world program") to describe your new file.</p></li>
70 <li><p>Change the copyright notice to your name, email, and the current
73 <li><p>Give a URL to the relevant standards document, or say "Not in SUSv3" if
74 there is no relevant standard. (Currently both lines are there, delete
75 whichever is appropriate.) The existing link goes to the directory of SUSv3
76 command line utility standards on the Open Group's website, where there's often
77 a relevant commandname.html file. Feel free to link to other documentation or
78 standards as appropriate.</p></li>
80 <li><p>Update the USE_YOURCOMMAND(NEWTOY(yourcommand,"blah",0)) line. The
81 arguments to newtoy are: 1) the name used to run your command, 2)
82 the command line arguments (NULL if none), and additional information such
83 as where your command should be installed on a running system. See [TODO] for
86 <li><p>Change the kconfig data (from "config YOURCOMMAND" to the end of the
87 comment block) to supply your command's configuration and help
88 information. The uppper case config symbols are used by menuconfig, and are
89 also what the CFG_ and USE_() macros are generated from (see [TODO]). The
90 help information here is used by menuconfig, and also by the "help" command to
91 describe your new command. (See [TODO] for details.) By convention,
92 unfinished commands default to "n" and finished commands default to "y".<p></li>
94 <li><p>Update the DEFINE_GLOBALS() macro to contain your command's global
95 variables, and also change the name "hello" in the #define TT line afterwards
96 to the name of your command. If your command has no global variables, delete
97 this macro (and the #define TT line afterwards). Note that if you specified
98 two-character command line arguments in NEWTOY(), the first few global
99 variables will be initialized by the automatic argument parsing logic, and
100 the type and order of these variables must correspond to the arguments
101 specified in NEWTOY(). See [TODO] for details.</p></li>
103 <li><p>If you didn't delete the DEFINE_GLOBALS macro, change the "#define TT
104 this.hello" line to use your command name in place of the "hello". This is a
105 shortcut to access your global variables as if they were members of the global
106 struct "TT". (Access these members with a period ".", not a right arrow
109 <li><p>Rename hello_main() to yourcommand_main(). This is the main() function
110 where execution of your command starts. See [TODO] to figure out what
111 happened to your command line arguments and how to access them.</p></li>
114 <p><a name="top" /><h2>Top level directory.</h2></p>
116 <p>This directory contains global infrastructure.
119 <p>Contains the main() function where execution starts, plus
120 common infrastructure to initialize global variables and select which command
121 to run. The "toybox" multiplexer command also lives here. (This is the
122 only command defined outside of the toys directory.)</p>
124 <p>Execution starts in main() which trims any path off of the first command
125 name and calls toybox_main(), which calls toy_exec(), which calls toy_find()
126 and toy_init() before calling the appropriate command's function from toy_list.
127 If the command is "toybox", execution recurses into toybox_main(), otherwise
128 the call goes to the appropriate commandname_main() from a C file in the toys
131 <p>The following global variables are defined in main.c:</p>
133 <li><p>struct toy_list <b>toy_list[]</b> - array describing all the
134 commands currently configured into toybox. The first entry (toy_list[0]) is
135 for the "toybox" multiplexer command, which runs all the other built-in commands
136 without symlinks by using its first argument as the name of the command to
137 run and the rest as that command's argument list (ala "./toybox echo hello").
138 The remaining entries are the commands in alphabetical order (for efficient
141 <p>This is a read-only array initialized at compile time by
142 defining macros and #including generated/newtoys.h.</p>
144 <p>Members of struct toy_list include:</p>
146 <li><p>char *<b>name</b> - the name of this command.</p></li>
147 <li><p>void (*<b>toy_main</b>)(void) - function pointer to run this
149 <li><p>char *<b>options</b> - command line option string (used by
150 get_optflags() in lib/args.c to intialize toys.optflags, toys.optargs, and
151 entries in the toy union). If this is NULL, no option parsing is done before
152 calling toy_main().</p></li>
153 <li><p>int <b>flags</b> - Behavior flags for this command. The following flags are currently understood:</p>
156 <li><b>TOYFLAG_USR</b> - Install this command under /usr</li>
157 <li><b>TOYFLAG_BIN</b> - Install this command under /bin</li>
158 <li><b>TOYFLAG_SBIN</b> - Install this command under /sbin</li>
159 <li><b>TOYFLAG_NOFORK</b> - This command can be used as a shell builtin.</li>
160 <li><b>TOYFLAG_UMASK</b> - Call umask(0) before running this command.</li>
164 <p>These flags are combined with | (or). For example, to install a command
165 in /usr/bin, or together TOYFLAG_USR|TOYFLAG_BIN.</p>
169 <li><p>struct toy_context <b>toys</b> - global structure containing information
170 common to all commands, initializd by toy_init(). Members of this structure
173 <li><p>struct toy_list *<b>which</b> - a pointer to this command's toy_list
174 structure. Mostly used to grab the name of the running command
175 (toys->which.name).</p>
177 <li><p>int <b>exitval</b> - Exit value of this command. Defaults to zero. The
178 error_exit() functions will return 1 if this is zero, otherwise they'll
179 return this value.</p></li>
180 <li><p>char **<b>argv</b> - "raw" command line options, I.E. the original
181 unmodified string array passed in to main(). Note that modifying this changes
182 "ps" output, and is not recommended.</p>
183 <p>Most commands don't use this field, instead the use optargs, optflags,
184 and the fields in the toy union initialized by get_optflags().</p>
186 <li><p>unsigned <b>optflags</b> - Command line option flags, set by
187 get_optflags(). Indicates which of the command line options listed in
188 toys->which.options occurred this time.</p>
190 <p>The rightmost command line argument listed in toys->which.options sets bit
191 1, the next one sets bit 2, and so on. This means the bits are set in the same
192 order the binary digits would be listed if typed out as a string. For example,
193 the option string "abcd" would parse the command line "-c" to set optflags to 2,
194 "-a" would set optflags to 8, and "-bd" would set optflags to 6 (4|2).</p>
196 <p>Only letters are relevant to optflags. In the string "a*b:c#d", d=1, c=2,
197 b=4, a=8. The punctuation after a letter initializes global variables
198 (see [TODO] DECLARE_GLOBALS() for details).</p>
200 <p>For more information on option parsing, see [TODO] get_optflags().</p>
203 <li><p>char **<b>optargs</b> - Null terminated array of arguments left over
204 after get_optflags() removed all the ones it understood. Note: optarg[0] is
205 the first argument, not the command name. Use toys.which->name for the command
207 <li><p>int <b>optc</b> - Optarg count, equivalent to argc but for
209 <li><p>int <b>exithelp</b> - Whether error_exit() should print a usage message
210 via help_main() before exiting. (True during option parsing, defaults to
211 false afterwards.)</p></li>
214 <li><p>union toy_union <b>this</b> - Union of structures containing each
215 command's global variables.</p>
217 <p>Global variables are useful: they reduce the overhead of passing extra
218 command line arguments between functions, they conveniently start prezeroed to
219 save initialization costs, and the command line argument parsing infrastructure
220 can also initialize global variables with its results.</p>
222 <p>But since each toybox process can only run one command at a time, allocating
223 space for global variables belonging to other commands you aren't currently
224 running would be wasteful.</p>
226 <p>Toybox handles this by encapsulating each command's global variables in
227 a structure, and declaring a union of those structures. The DECLARE_GLOBALS()
228 macro contains the global variables that should go in a command's global
229 structure. Each variable can then be accessed as "this.commandname.varname".
230 Generally, the macro TT is #defined to this.commandname so the variable
231 can then be accessed as "TT.variable".</p>
233 A command that needs global variables should declare a structure to
234 contain them all, and add that structure to this union. A command should never
235 declare global variables outside of this, because such global variables would
236 allocate memory when running other commands that don't use those global
239 <p>The first few fields of this structure can be intialized by get_optargs(),
240 as specified by the options field off this command's toy_list entry. See
241 the get_optargs() description in lib/args.c for details.</p>
244 <li><b>char toybuf[4096]</b> - a common scratch space buffer so
245 commands don't need to allocate their own. Any command is free to use this,
246 and it should never be directly referenced by functions in lib/ (although
247 commands are free to pass toybuf in to a library function as an argument).</li>
250 <p>The following functions are defined in main.c:</p>
252 <li><p>struct toy_list *<b>toy_find</b>(char *name) - Return the toy_list
253 structure for this command name, or NULL if not found.</p></li>
254 <li><p>void <b>toy_init</b>(struct toy_list *which, char *argv[]) - fill out
255 the global toys structure, calling get_optargs() if necessary.</p></li>
256 <li><p>void <b>toy_exec</b>(char *argv[]) - Run a built-in command with
258 <p>Calls toy_find() on argv[0] (which must be just a command name
259 without path). Returns if it can't find this command, otherwise calls
260 toy_init(), toys->which.toy_main(), and exit() instead of returning.</p>
262 <p>Use the library function xexec() to fall back to external executables
263 in $PATH if toy_exec() can't find a built-in command. Note that toy_exec()
264 does not strip paths before searching for a command, so "./command" will
265 never match an internal command.</li>
267 <li><p>void <b>toybox_main</b>(void) - the main function for the multiplexer
268 command (I.E. "toybox"). Given a command name as its first argument, calls
269 toy_exec() on its arguments. With no arguments, it lists available commands.
270 If the first argument starts with "-" it lists each command with its default
271 install path prepended.</p></li>
277 <p>Top level configuration file in a stylized variant of
278 <a href=http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt>kconfig</a> format. Includes generated/Config.in.</p>
280 <p>These files are directly used by "make menuconfig" to select which commands
281 to build into toybox (thus generating a .config file), and by
282 scripts/config2help.py to create generated/help.h.</p>
284 <h3>Temporary files:</h3>
286 <p>There is one temporary file in the top level source directory:</p>
288 <li><p><b>.config</b> - Configuration file generated by kconfig, indicating
289 which commands (and options to commands) are currently enabled. Used
290 to make generated/config.h and determine which toys/*.c files to build.</p>
292 <p>You can create a human readable "miniconfig" version of this file using
293 <a href=http://landley.net/code/firmware/new_platform.html#miniconfig>these
294 instructions</a>.</p>
298 <p>The "generated/" directory contains files generated from other source code
299 in toybox. All of these files can be recreated by the build system, although
300 some (such as generated/help.h) are shipped in release versions to reduce
301 environmental dependencies (I.E. so you don't need python on your build
305 <li><p><b>generated/config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros,
306 generated from .config by a sed invocation in the top level Makefile.</p>
308 <p>CFG_SYMBOL is a comple time constant set to 1 for enabled symbols and 0 for
309 disabled symbols. This allows the use of normal if() statements to remove
310 code at compile time via the optimizer's dead code elimination (which removes
311 from the binary any code that cannot be reached). This saves space without
312 cluttering the code with #ifdefs or leading to configuration dependent build
313 breaks. (See the 1992 Usenix paper
314 <a href=http://www.chris-lott.org/resources/cstyle/ifdefs.pdf>#ifdef
315 Considered Harmful</a> for more information.)</p>
317 <p>USE_SYMBOL(code) evaluates to the code in parentheses when the symbol
318 is enabled, and nothing when the symbol is disabled. This can be used
319 for things like varargs or variable declarations which can't always be
320 eliminated by a simple test on CFG_SYMBOL. Note that
321 (unlike CFG_SYMBOL) this is really just a variant of #ifdef, and can
322 still result in configuration dependent build breaks. Use with caution.</p>
326 <p><h2>Directory toys/</h2></p>
328 <h3>toys/Config.in</h3>
330 <p>Included from the top level Config.in, contains one or more
331 configuration entries for each command.</p>
333 <p>Each command has a configuration entry matching the command name (although
334 configuration symbols are uppercase and command names are lower case).
335 Options to commands start with the command name followed by an underscore and
336 the option name. Global options are attachd to the "toybox" command,
337 and thus use the prefix "TOYBOX_". This organization is used by
338 scripts/cfg2files to select which toys/*.c files to compile for a given
341 <p>A commands with multiple names (or multiple similar commands implemented in
342 the same .c file) should have config symbols prefixed with the name of their
343 C file. I.E. config symbol prefixes are NEWTOY() names. If OLDTOY() names
344 have config symbols they're options (symbols with an underscore and suffix)
345 to the NEWTOY() name. (See toys/toylist.h)</p>
347 <h3>toys/toylist.h</h3>
348 <p>The first half of this file prototypes all the structures to hold
349 global variables for each command, and puts them in toy_union. These
350 prototypes are only included if the macro NEWTOY isn't defined (in which
351 case NEWTOY is defined to a default value that produces function
354 <p>The second half of this file lists all the commands in alphabetical
355 order, along with their command line arguments and install location.
356 Each command has an appropriate configuration guard so only the commands that
357 are enabled wind up in the list.</p>
359 <p>The first time this header is #included, it defines structures and
360 produces function prototypes for the commands in the toys directory.</p>
363 <p>The first time it's included, it defines structures and produces function
366 is used to initialize toy_list in main.c, and later in that file to initialize
367 NEED_OPTIONS (to figure out whether the command like parsing logic is needed),
368 and to put the help entries in the right order in toys/help.c.</p>
372 <p>#defines two help text strings for each command: a single line
373 command_help and an additinal command_help_long. This is used by help_main()
374 in toys/help.c to display help for commands.</p>
376 <p>Although this file is generated from Config.in help entries by
377 scripts/config2help.py, it's shipped in release tarballs so you don't need
378 python on the build system. (If you check code out of source control, or
379 modify Config.in, then you'll need python installed to rebuild it.)</p>
381 <p>This file contains help for all commands, regardless of current
382 configuration, but only the currently enabled ones are entered into help_data[]
385 <h2>Directory lib/</h2>
387 <p>lib: llist, getmountlist(), error_msg/error_exit, xmalloc(),
388 strlcpy(), xexec(), xopen()/xread(), xgetcwd(), xabspath(), find_in_path(),
393 <h2>Directory scripts/</h2>
395 <h3>scripts/cfg2files.sh</h3>
397 <p>Run .config through this filter to get a list of enabled commands, which
398 is turned into a list of files in toys via a sed invocation in the top level
402 <h2>Directory kconfig/</h2>
404 <p>Menuconfig infrastructure copied from the Linux kernel. See the
405 Linux kernel's Documentation/kbuild/kconfig-language.txt</p>
407 <!--#include file="footer.html" -->