Mercurial > hg > toybox
annotate www/code.html @ 256:20f1e3da0492
Partial update. Needs more work.
| author | Rob Landley <rob@landley.net> |
|---|---|
| date | Tue, 12 Feb 2008 18:41:34 -0600 |
| parents | 4f1ca01db000 |
| children | f6ffc6685a9e |
| 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 | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
18 <p>The primary goal of toybox is _simple_ code. Small is second, |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
19 speed and lots of features come in somewhere after that. Note that |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
20 environmental dependencies are a type of complexity, so needing other packages |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
21 to build or run is a downside. For example, don't use curses when you can |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
22 output ansi escape sequences instead.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
23 |
| 200 | 24 <p><h1>Infrastructure:</h1></p> |
| 25 | |
|
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
|
26 <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
|
27 <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
|
28 <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
|
29 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
|
30 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
|
31 <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
|
32 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
|
33 <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
|
34 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
|
35 <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
|
36 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
|
37 <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
|
38 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
|
39 <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
|
40 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
|
41 </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
|
42 |
|
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 <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
|
44 <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
|
45 the toys directory. No other files need to be modified; the build extracts |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
46 all the information it needs (such as command line arguments) from specially |
|
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
|
47 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
|
48 <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
|
49 |
|
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 <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
|
51 the name of the new command, and modify this copy to implement the new command. |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
52 This file is an example command meant to be used as a "skeleton" for |
|
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
|
53 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
|
54 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
|
55 help data, and then filling out its "main" function with code that does |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
56 something interesting). It provides examples of all the build infrastructure |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
57 (including optional elements like command line argument parsing and global |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
58 variables that a "hello world" program doesn't strictly need).</p> |
|
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
|
59 |
|
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 <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
|
61 |
|
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 <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
|
63 <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
|
64 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
|
65 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
|
66 |
|
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 <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
|
68 "hello.c - A hello world program") to describe your new file.</p></li> |
| 200 | 69 |
|
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
|
70 <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
|
71 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
|
72 |
|
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 <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
|
74 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
|
75 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
|
76 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
|
77 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
|
78 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
|
79 |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
80 <li><p>Update the USE_YOURCOMMAND(NEWTOY(yourcommand,"blah",0)) line. The |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
81 arguments to newtoy are: 1) the name used to run your command, 2) |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
82 the command line arguments (NULL if none), and additional information such |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
83 as where your command should be installed on a running system. See [TODO] for |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
84 details.</p></li> |
|
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 |
|
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 <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
|
87 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
|
88 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
|
89 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
|
90 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
|
91 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
|
92 unfinished commands default to "n" and finished commands default to "y".<p></li> |
| 200 | 93 |
|
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
|
94 <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
|
95 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
|
96 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
|
97 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
|
98 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
|
99 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
|
100 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
|
101 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
|
102 |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
103 <li><p>If you didn't delete the DEFINE_GLOBALS macro, change the "#define TT |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
104 this.hello" line to use your command name in place of the "hello". This is a |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
105 shortcut to access your global variables as if they were members of the global |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
106 struct "TT". (Access these members with a period ".", not a right arrow |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
107 "->".)</p></li> |
|
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
|
108 |
|
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
|
109 <li><p>Rename hello_main() to yourcommand_main(). This is the main() function |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
110 where execution of your command starts. See [TODO] to figure out what |
|
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 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
|
112 </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
|
113 |
|
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
|
114 <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
|
115 |
|
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 <p>This directory contains global infrastructure. |
| 200 | 117 |
| 118 <h3>main.c</h3> | |
| 119 <p>Contains the main() function where execution starts, plus | |
| 120 common infrastructure to initialize global variables and select which command | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
121 to run. The "toybox" multiplexer command also lives here. (This is the |
|
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
|
122 only command defined outside of the toys directory.)</p> |
| 200 | 123 |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
124 <p>Execution starts in main() which trims any path off of the first command |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
125 name and calls toybox_main(), which calls toy_exec(), which calls toy_find() |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
126 and toy_init() before calling the appropriate command's function from toy_list. |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
127 If the command is "toybox", execution recurses into toybox_main(), otherwise |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
128 the call goes to the appropriate commandname_main() from a C file in the toys |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
129 directory.</p> |
| 200 | 130 |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
131 <p>The following global variables are defined in main.c:</p> |
| 200 | 132 <ul> |
| 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 | |
| 139 binary search).</p> | |
| 140 | |
| 141 <p>This is a read-only array initialized at compile time by | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
142 defining macros and #including generated/newtoys.h.</p> |
| 200 | 143 |
| 144 <p>Members of struct toy_list include:</p> | |
| 145 <ul> | |
| 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 | |
| 148 command.</p></li> | |
| 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> | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
153 <li><p>int <b>flags</b> - Behavior flags for this command. The following flags are currently understood:</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
154 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
155 <ul> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
156 <li><b>TOYFLAG_USR</b> - Install this command under /usr</li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
157 <li><b>TOYFLAG_BIN</b> - Install this command under /bin</li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
158 <li><b>TOYFLAG_SBIN</b> - Install this command under /sbin</li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
159 <li><b>TOYFLAG_NOFORK</b> - This command can be used as a shell builtin.</li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
160 <li><b>TOYFLAG_UMASK</b> - Call umask(0) before running this command.</li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
161 </ul> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
162 <br> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
163 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
164 <p>These flags are combined with | (or). For example, to install a command |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
165 in /usr/bin, or together TOYFLAG_USR|TOYFLAG_BIN.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
166 </ul> |
| 200 | 167 </li> |
| 168 | |
| 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 | |
| 171 include:</p> | |
| 172 <ul> | |
| 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> | |
| 176 </li> | |
| 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> | |
| 185 </li> | |
| 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 | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
188 toys->which.options occurred this time.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
189 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
190 <p>The rightmost command line argument listed in toys->which.options sets bit |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
191 1, the next one sets bit 2, and so on. This means the bits are set in the same |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
192 order the binary digits would be listed if typed out as a string. For example, |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
193 the option string "abcd" would parse the command line "-c" to set optflags to 2, |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
194 "-a" would set optflags to 8, and "-bd" would set optflags to 6 (4|2).</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
195 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
196 <p>Only letters are relevant to optflags. In the string "a*b:c#d", d=1, c=2, |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
197 b=4, a=8. The punctuation after a letter initializes global variables |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
198 (see [TODO] DECLARE_GLOBALS() for details).</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
199 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
200 <p>For more information on option parsing, see [TODO] get_optflags().</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
201 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
202 </li> |
| 200 | 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 | |
| 206 name.</p></li> | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
207 <li><p>int <b>optc</b> - Optarg count, equivalent to argc but for |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
208 optargs[].<p></li> |
| 200 | 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> | |
| 212 </ul><br> | |
| 213 | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
214 <li><p>union toy_union <b>this</b> - Union of structures containing each |
| 200 | 215 command's global variables.</p> |
| 216 | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
217 <p>Global variables are useful: they reduce the overhead of passing extra |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
218 command line arguments between functions, they conveniently start prezeroed to |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
219 save initialization costs, and the command line argument parsing infrastructure |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
220 can also initialize global variables with its results.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
221 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
222 <p>But since each toybox process can only run one command at a time, allocating |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
223 space for global variables belonging to other commands you aren't currently |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
224 running would be wasteful.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
225 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
226 <p>Toybox handles this by encapsulating each command's global variables in |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
227 a structure, and declaring a union of those structures. The DECLARE_GLOBALS() |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
228 macro contains the global variables that should go in a command's global |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
229 structure. Each variable can then be accessed as "this.commandname.varname". |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
230 Generally, the macro TT is #defined to this.commandname so the variable |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
231 can then be accessed as "TT.variable".</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
232 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
233 A command that needs global variables should declare a structure to |
| 200 | 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 | |
| 237 variables.</p> | |
| 238 | |
| 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> | |
| 242 </li> | |
| 243 | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
244 <li><b>char toybuf[4096]</b> - a common scratch space buffer so |
| 200 | 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> | |
| 248 </ul> | |
| 249 | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
250 <p>The following functions are defined in main.c:</p> |
| 200 | 251 <ul> |
| 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> | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
254 <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
|
255 the global toys structure, calling get_optargs() if necessary.</p></li> |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
256 <li><p>void <b>toy_exec</b>(char *argv[]) - Run a built-in command with |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
257 arguments.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
258 <p>Calls toy_find() on argv[0] (which must be just a command name |
| 200 | 259 without path). Returns if it can't find this command, otherwise calls |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
260 toy_init(), toys->which.toy_main(), and exit() instead of returning.</p> |
| 200 | 261 |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
262 <p>Use the library function xexec() to fall back to external executables |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
263 in $PATH if toy_exec() can't find a built-in command. Note that toy_exec() |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
264 does not strip paths before searching for a command, so "./command" will |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
265 never match an internal command.</li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
266 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
267 <li><p>void <b>toybox_main</b>(void) - the main function for the multiplexer |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
268 command (I.E. "toybox"). Given a command name as its first argument, calls |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
269 toy_exec() on its arguments. With no arguments, it lists available commands. |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
270 If the first argument starts with "-" it lists each command with its default |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
271 install path prepended.</p></li> |
| 200 | 272 |
| 273 </ul> | |
| 274 | |
| 275 <h3>Config.in</h3> | |
| 276 | |
| 277 <p>Top level configuration file in a stylized variant of | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
278 <a href=http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt>kconfig</a> format. Includes generated/Config.in.</p> |
| 200 | 279 |
| 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 | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
282 scripts/config2help.py to create generated/help.h.</p> |
| 200 | 283 |
| 284 <h3>Temporary files:</h3> | |
| 285 | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
286 <p>There is one temporary file in the top level source directory:</p> |
| 200 | 287 <ul> |
| 288 <li><p><b>.config</b> - Configuration file generated by kconfig, indicating | |
| 289 which commands (and options to commands) are currently enabled. Used | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
290 to make generated/config.h and determine which toys/*.c files to build.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
291 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
292 <p>You can create a human readable "miniconfig" version of this file using |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
293 <a href=http://landley.net/code/firmware/new_platform.html#miniconfig>these |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
294 instructions</a>.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
295 </li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
296 </ul> |
| 200 | 297 |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
298 <p>The "generated/" directory contains files generated from other source code |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
299 in toybox. All of these files can be recreated by the build system, although |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
300 some (such as generated/help.h) are shipped in release versions to reduce |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
301 environmental dependencies (I.E. so you don't need python on your build |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
302 system).</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
303 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
304 <ul> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
305 <li><p><b>generated/config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros, |
| 200 | 306 generated from .config by a sed invocation in the top level Makefile.</p> |
| 307 | |
| 308 <p>CFG_SYMBOL is a comple time constant set to 1 for enabled symbols and 0 for | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
309 disabled symbols. This allows the use of normal if() statements to remove |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
310 code at compile time via the optimizer's dead code elimination (which removes |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
311 from the binary any code that cannot be reached). This saves space without |
| 200 | 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> | |
| 316 | |
| 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 | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
320 eliminated by a simple test on CFG_SYMBOL. Note that |
| 200 | 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> | |
| 323 </li> | |
| 324 </ul> | |
| 325 | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
326 <p><h2>Directory toys/</h2></p> |
| 200 | 327 |
| 328 <h3>toys/Config.in</h3> | |
| 329 | |
| 330 <p>Included from the top level Config.in, contains one or more | |
| 331 configuration entries for each command.</p> | |
| 332 | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
333 <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
|
334 configuration symbols are uppercase and command names are lower case). |
| 200 | 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 | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
338 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
|
339 .config.</p> |
| 200 | 340 |
| 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> | |
| 346 | |
| 347 <h3>toys/toylist.h</h3> | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
348 <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
|
349 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
|
350 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
|
351 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
|
352 prototypes).</p> |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
353 |
|
213
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
354 <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
|
355 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
|
356 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
|
357 are enabled wind up in the list.</p> |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
358 |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
359 <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
|
360 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
|
361 |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
362 |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
363 <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
|
364 prototypes. |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
365 This |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
366 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
|
367 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
|
368 and to put the help entries in the right order in toys/help.c.</p> |
| 200 | 369 |
| 370 <h3>toys/help.h</h3> | |
| 371 | |
| 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> | |
| 375 | |
| 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> | |
| 380 | |
| 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[] | |
| 383 in toys/help.c.</p> | |
| 384 | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
385 <h2>Directory lib/</h2> |
| 200 | 386 |
|
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
|
387 <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
|
388 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
|
389 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
|
390 |
|
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
|
391 |
|
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
|
392 |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
393 <h2>Directory scripts/</h2> |
| 200 | 394 |
| 395 <h3>scripts/cfg2files.sh</h3> | |
| 396 | |
| 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 | |
| 399 Makefile. | |
| 400 </p> | |
| 401 | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
402 <h2>Directory kconfig/</h2> |
| 200 | 403 |
| 404 <p>Menuconfig infrastructure copied from the Linux kernel. See the | |
| 405 Linux kernel's Documentation/kbuild/kconfig-language.txt</p> | |
| 406 | |
| 407 <!--#include file="footer.html" --> |