Mercurial > hg > toybox
annotate www/code.html @ 239:4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
and update a chunk of code.html (much more to do there).
author | Rob Landley <rob@landley.net> |
---|---|
date | Sun, 20 Jan 2008 19:00:16 -0600 |
parents | ca48a878255d |
children | 20f1e3da0492 |
rev | line source |
---|---|
200 | 1 <!--#include file="header.html" --> |
2 | |
217 | 3 <p><h1>Code style</h1></p> |
4 | |
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 | |
9 the file.</p> | |
10 | |
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> | |
17 | |
200 | 18 <p><h1>Infrastructure:</h1></p> |
19 | |
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
20 <p>The toybox source code is in following directories:</p> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
21 <ul> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
22 <li>The <a href="#top">top level directory</a> contains the file main.c (were |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
23 execution starts), the header file toys.h (included by every command), and |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
24 other global infrastructure.</li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
25 <li>The <a href="#lib">lib directory</a> contains common functions shared by |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
26 multiple commands.</li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
27 <li>The <a href="#toys">toys directory</a> contains the C files implementating |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
28 each command.</li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
29 <li>The <a href="#scripts">scripts directory</a> contains the build and |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
30 test infrastructure.</li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
31 <li>The <a href="#kconfig">kconfig directory</a> contains the configuration |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
32 infrastructure implementing menuconfig (copied from the Linux kernel).</li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
33 <li>The <a href="#generated">generated directory</a> contains intermediate |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
34 files generated from other parts of the source code.</li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
35 </ul> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
36 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
37 <p><h1>Adding a new command</h1></p> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
38 <p>To add a new command to toybox, add a C file implementing that command to |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
39 the toys directory. No other files need to be modified; the build extracts |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
40 other information it needs (such as command line arguments) from specially |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
41 formatted comments and macros in the C file. (See the description of the |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
42 <a href="#generated">generated directory</a> for details.)</p> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
43 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
44 <p>An easy way to start a new command is copy the file "hello.c" to |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
45 the name of the new command, and modify this copy to implement the new command. |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
46 This file is a small, simple command meant to be used as a "skeleton" for |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
47 new commands (more or less by turning every instance of "hello" into the |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
48 name of your command, updating the command line arguments, globals, and |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
49 help data, and then filling out its "main" function with code that does |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
50 something interesting).</p> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
51 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
52 <p>Here's a checklist of steps to turn hello.c into another command:</p> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
53 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
54 <ul> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
55 <li><p>First "cd toys" and "cp hello.c yourcommand.c". Note that the name |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
56 of this file is significant, it's the name of the new command you're adding |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
57 to toybox. Open your new file in your favorite editor.</p></li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
58 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
59 <li><p>Change the one line comment at the top of the file (currently |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
60 "hello.c - A hello world program") to describe your new file.</p></li> |
200 | 61 |
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
62 <li><p>Change the copyright notice to your name, email, and the current |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
63 year.</p></li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
64 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
65 <li><p>Give a URL to the relevant standards document, or say "Not in SUSv3" if |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
66 there is no relevant standard. (Currently both lines are there, delete |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
67 whichever is appropriate.) The existing link goes to the directory of SUSv3 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
68 command line utility standards on the Open Group's website, where there's often |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
69 a relevant commandname.html file. Feel free to link to other documentation or |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
70 standards as appropriate.</p></li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
71 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
72 <li><p>Update the USE_YOURCOMMAND(NEWTOY(yourcommand,NULL,0)) line. This |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
73 specifies the name used to run your command, the command line arguments (NULL |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
74 if none), and where your command should be installed on a running system. See |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
75 [TODO] for details.</p></li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
76 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
77 <li><p>Change the kconfig data (from "config YOURCOMMAND" to the end of the |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
78 comment block) to supply your command's configuration and help |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
79 information. The uppper case config symbols are used by menuconfig, and are |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
80 also what the CFG_ and USE_() macros are generated from (see [TODO]). The |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
81 help information here is used by menuconfig, and also by the "help" command to |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
82 describe your new command. (See [TODO] for details.) By convention, |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
83 unfinished commands default to "n" and finished commands default to "y".<p></li> |
200 | 84 |
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
85 <li><p>Update the DEFINE_GLOBALS() macro to contain your command's global |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
86 variables, and also change the name "hello" in the #define TT line afterwards |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
87 to the name of your command. If your command has no global variables, delete |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
88 this macro (and the #define TT line afterwards). Note that if you specified |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
89 two-character command line arguments in NEWTOY(), the first few global |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
90 variables will be initialized by the automatic argument parsing logic, and |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
91 the type and order of these variables must correspond to the arguments |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
92 specified in NEWTOY(). See [TODO] for details.</p></li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
93 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
94 <li><p>Change the "#define TT this.hello" line to use your command name in |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
95 place of the "hello". This is a shortcut to access your global variables |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
96 as if they were members of the global struct "TT". (Access these members with |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
97 a period ".", not a right arrow "->".)</p></li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
98 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
99 <li><p>Rename hello_main() to yourcommand_main(). This is the main() function |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
100 where execution off your command starts. See [TODO] to figure out what |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
101 happened to your command line arguments and how to access them.</p></li> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
102 </ul> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
103 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
104 <p><a name="top" /><h2>Top level directory.</h2></p> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
105 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
106 <p>This directory contains global infrastructure. |
200 | 107 |
108 <h3>main.c</h3> | |
109 <p>Contains the main() function where execution starts, plus | |
110 common infrastructure to initialize global variables and select which command | |
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
111 to run. The "toybox" multiplexer command is also defined here. (This is the |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
112 only command defined outside of the toys directory.)</p> |
200 | 113 |
114 <p>Execution starts in main() which removes the path from the first command | |
115 name and calls toybox_main(), which calls toy_exec(), which calls toy_find(), | |
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
116 toy_init() and the appropriate command's function from toy_list. If |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
117 the command is "toybox", execution returns to toybox_main(), otherwise |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
118 the call goes to the appropriate command_main() from the toys directory.</p> |
200 | 119 |
120 <p>The following global variables are defined here:</p> | |
121 <ul> | |
122 <li><p>struct toy_list <b>toy_list[]</b> - array describing all the | |
123 commands currently configured into toybox. The first entry (toy_list[0]) is | |
124 for the "toybox" multiplexer command, which runs all the other built-in commands | |
125 without symlinks by using its first argument as the name of the command to | |
126 run and the rest as that command's argument list (ala "./toybox echo hello"). | |
127 The remaining entries are the commands in alphabetical order (for efficient | |
128 binary search).</p> | |
129 | |
130 <p>This is a read-only array initialized at compile time by | |
131 defining macros and #including toys/toylist.h.</p> | |
132 | |
133 <p>Members of struct toy_list include:</p> | |
134 <ul> | |
135 <li><p>char *<b>name</b> - the name of this command.</p></li> | |
136 <li><p>void (*<b>toy_main</b>)(void) - function pointer to run this | |
137 command.</p></li> | |
138 <li><p>char *<b>options</b> - command line option string (used by | |
139 get_optflags() in lib/args.c to intialize toys.optflags, toys.optargs, and | |
140 entries in the toy union). If this is NULL, no option parsing is done before | |
141 calling toy_main().</p></li> | |
142 <li><p>int <b>flags</b> - Behavior flags such as where to install this command | |
143 (in usr/bin/sbin) and whether this is a shell builtin (NOFORK) or a standalone | |
144 command.</p></li> | |
145 </ul><br> | |
146 </li> | |
147 | |
148 <li><p>struct toy_context <b>toys</b> - global structure containing information | |
149 common to all commands, initializd by toy_init(). Members of this structure | |
150 include:</p> | |
151 <ul> | |
152 <li><p>struct toy_list *<b>which</b> - a pointer to this command's toy_list | |
153 structure. Mostly used to grab the name of the running command | |
154 (toys->which.name).</p> | |
155 </li> | |
156 <li><p>int <b>exitval</b> - Exit value of this command. Defaults to zero. The | |
157 error_exit() functions will return 1 if this is zero, otherwise they'll | |
158 return this value.</p></li> | |
159 <li><p>char **<b>argv</b> - "raw" command line options, I.E. the original | |
160 unmodified string array passed in to main(). Note that modifying this changes | |
161 "ps" output, and is not recommended.</p> | |
162 <p>Most commands don't use this field, instead the use optargs, optflags, | |
163 and the fields in the toy union initialized by get_optflags().</p> | |
164 </li> | |
165 <li><p>unsigned <b>optflags</b> - Command line option flags, set by | |
166 get_optflags(). Indicates which of the command line options listed in | |
167 toys->which.options were seen this time. See get_optflags() for | |
168 details.</p></li> | |
169 <li><p>char **<b>optargs</b> - Null terminated array of arguments left over | |
170 after get_optflags() removed all the ones it understood. Note: optarg[0] is | |
171 the first argument, not the command name. Use toys.which->name for the command | |
172 name.</p></li> | |
173 <li><p>int <b>exithelp</b> - Whether error_exit() should print a usage message | |
174 via help_main() before exiting. (True during option parsing, defaults to | |
175 false afterwards.)</p></li> | |
176 </ul><br> | |
177 | |
178 <li><p>union toy_union <b>toy</b> - Union of structures containing each | |
179 command's global variables.</p> | |
180 | |
181 <p>A command that needs global variables should declare a structure to | |
182 contain them all, and add that structure to this union. A command should never | |
183 declare global variables outside of this, because such global variables would | |
184 allocate memory when running other commands that don't use those global | |
185 variables.</p> | |
186 | |
187 <p>The first few fields of this structure can be intialized by get_optargs(), | |
188 as specified by the options field off this command's toy_list entry. See | |
189 the get_optargs() description in lib/args.c for details.</p> | |
190 </li> | |
191 | |
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
192 <li><b>char toybuf[4096]</b> - a common scratch space buffer so |
200 | 193 commands don't need to allocate their own. Any command is free to use this, |
194 and it should never be directly referenced by functions in lib/ (although | |
195 commands are free to pass toybuf in to a library function as an argument).</li> | |
196 </ul> | |
197 | |
198 <p>The following functions are defined here:</p> | |
199 <ul> | |
200 <li><p>struct toy_list *<b>toy_find</b>(char *name) - Return the toy_list | |
201 structure for this command name, or NULL if not found.</p></li> | |
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
202 <li><p>void <b>toy_init</b>(struct toy_list *which, char *argv[]) - fill out |
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
203 the global toys structure, calling get_optargs() if necessary.</p></li> |
200 | 204 <li><p>void <b>toy_exec</b>(char *argv[]) - Run a built-in command with arguments. |
205 Calls toy_find() on the first argument (which must be just a command name | |
206 without path). Returns if it can't find this command, otherwise calls | |
207 toy_init(), toys->which.toy_main(), and exit() instead of returning.</p></li> | |
208 | |
209 <li><p>void <b>toybox_main</b>(void) - the main function for multiplexer | |
210 command. Given a command name as its first argument, calls toy_exec() on its | |
211 arguments. With no arguments, it lists available commands. If the first | |
212 argument starts with "-" it lists each command with its default install | |
213 path prepended.</p></li> | |
214 | |
215 </ul> | |
216 | |
217 <h3>Config.in</h3> | |
218 | |
219 <p>Top level configuration file in a stylized variant of | |
220 <a href=http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt>kconfig</a> format. Includes toys/Config.in.</p> | |
221 | |
222 <p>These files are directly used by "make menuconfig" to select which commands | |
223 to build into toybox (thus generating a .config file), and by | |
224 scripts/config2help.py to generate toys/help.h.</p> | |
225 | |
226 <h3>Temporary files:</h3> | |
227 | |
228 <ul> | |
229 <li><p><b>.config</b> - Configuration file generated by kconfig, indicating | |
230 which commands (and options to commands) are currently enabled. Used | |
231 to generate gen_config.h and the toys/*.c dependency list.</p></li> | |
232 | |
233 <li><p><b>gen_config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros, | |
234 generated from .config by a sed invocation in the top level Makefile.</p> | |
235 | |
236 <p>CFG_SYMBOL is a comple time constant set to 1 for enabled symbols and 0 for | |
237 disabled symbols. This can be used via normal if() statements to remove | |
238 code at compile time via the optimizer's dead code elimination, which removes | |
239 from the binary any code that cannot be reached. This saves space without | |
240 cluttering the code with #ifdefs or leading to configuration dependent build | |
241 breaks. (See the 1992 Usenix paper | |
242 <a href=http://www.chris-lott.org/resources/cstyle/ifdefs.pdf>#ifdef | |
243 Considered Harmful</a> for more information.)</p> | |
244 | |
245 <p>USE_SYMBOL(code) evaluates to the code in parentheses when the symbol | |
246 is enabled, and nothing when the symbol is disabled. This can be used | |
247 for things like varargs or variable declarations which can't always be | |
248 eliminated by a compile time removalbe test on CFG_SYMBOL. Note that | |
249 (unlike CFG_SYMBOL) this is really just a variant of #ifdef, and can | |
250 still result in configuration dependent build breaks. Use with caution.</p> | |
251 </li> | |
252 </ul> | |
253 | |
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
254 <p><h2>Directory toys/</h2></p> |
200 | 255 |
256 <h3>toys/Config.in</h3> | |
257 | |
258 <p>Included from the top level Config.in, contains one or more | |
259 configuration entries for each command.</p> | |
260 | |
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
261 <p>Each command has a configuration entry matching the command name (although |
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
262 configuration symbols are uppercase and command names are lower case). |
200 | 263 Options to commands start with the command name followed by an underscore and |
264 the option name. Global options are attachd to the "toybox" command, | |
265 and thus use the prefix "TOYBOX_". This organization is used by | |
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
266 scripts/cfg2files to select which toys/*.c files to compile for a given |
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
267 .config.</p> |
200 | 268 |
269 <p>A commands with multiple names (or multiple similar commands implemented in | |
270 the same .c file) should have config symbols prefixed with the name of their | |
271 C file. I.E. config symbol prefixes are NEWTOY() names. If OLDTOY() names | |
272 have config symbols they're options (symbols with an underscore and suffix) | |
273 to the NEWTOY() name. (See toys/toylist.h)</p> | |
274 | |
275 <h3>toys/toylist.h</h3> | |
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
276 <p>The first half of this file prototypes all the structures to hold |
213
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
277 global variables for each command, and puts them in toy_union. These |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
278 prototypes are only included if the macro NEWTOY isn't defined (in which |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
279 case NEWTOY is defined to a default value that produces function |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
280 prototypes).</p> |
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
281 |
213
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
282 <p>The second half of this file lists all the commands in alphabetical |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
283 order, along with their command line arguments and install location. |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
284 Each command has an appropriate configuration guard so only the commands that |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
285 are enabled wind up in the list.</p> |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
286 |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
287 <p>The first time this header is #included, it defines structures and |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
288 produces function prototypes for the commands in the toys directory.</p> |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
289 |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
290 |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
291 <p>The first time it's included, it defines structures and produces function |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
292 prototypes. |
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
293 This |
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
294 is used to initialize toy_list in main.c, and later in that file to initialize |
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
295 NEED_OPTIONS (to figure out whether the command like parsing logic is needed), |
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
296 and to put the help entries in the right order in toys/help.c.</p> |
200 | 297 |
298 <h3>toys/help.h</h3> | |
299 | |
300 <p>#defines two help text strings for each command: a single line | |
301 command_help and an additinal command_help_long. This is used by help_main() | |
302 in toys/help.c to display help for commands.</p> | |
303 | |
304 <p>Although this file is generated from Config.in help entries by | |
305 scripts/config2help.py, it's shipped in release tarballs so you don't need | |
306 python on the build system. (If you check code out of source control, or | |
307 modify Config.in, then you'll need python installed to rebuild it.)</p> | |
308 | |
309 <p>This file contains help for all commands, regardless of current | |
310 configuration, but only the currently enabled ones are entered into help_data[] | |
311 in toys/help.c.</p> | |
312 | |
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
313 <h2>Directory lib/</h2> |
200 | 314 |
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
315 <p>lib: llist, getmountlist(), error_msg/error_exit, xmalloc(), |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
316 strlcpy(), xexec(), xopen()/xread(), xgetcwd(), xabspath(), find_in_path(), |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
317 itoa().</p> |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
318 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
319 |
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
320 |
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
321 <h2>Directory scripts/</h2> |
200 | 322 |
323 <h3>scripts/cfg2files.sh</h3> | |
324 | |
325 <p>Run .config through this filter to get a list of enabled commands, which | |
326 is turned into a list of files in toys via a sed invocation in the top level | |
327 Makefile. | |
328 </p> | |
329 | |
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
330 <h2>Directory kconfig/</h2> |
200 | 331 |
332 <p>Menuconfig infrastructure copied from the Linux kernel. See the | |
333 Linux kernel's Documentation/kbuild/kconfig-language.txt</p> | |
334 | |
335 <!--#include file="footer.html" --> |