annotate www/code.html @ 536:2c1cb0d35031

Add lib/portability.h description with explanation of SWAP() macros.
author Rob Landley <rob@landley.net>
date Fri, 09 Mar 2012 08:33:57 -0600
parents b93517f238d1
children 1a368546afd9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1 <!--#include file="header.html" -->
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
2
529
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
3 <p><h1>Code style</h1></p>
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
4
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
5 <p>The primary goal of toybox is _simple_ code. Keeping the code small is
529
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
6 second, with speed and lots of features coming in somewhere after that.
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
7 (For more on that, see the <a href=design.html>design</a> page.)</p>
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
8
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
9 <p>A simple implementation usually takes up fewer lines of source code,
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
10 meaning more code can fit on the screen at once, meaning the programmer can
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
11 see more of it on the screen and thus keep more if in their head at once.
529
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
12 This helps code auditing and thus reduces bugs. That said, sometimes being
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
13 more explicit is preferable to being clever enough to outsmart yourself:
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
14 don't be so terse your code is unreadable.</p>
217
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
15
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
16 <p>Toybox source is formatted to be read with 4-space tab stops. Each file
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
17 starts with a special comment telling vi to set the tab stop to 4. Note that
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
18 one of the bugs in Ubuntu 7.10 broke vi's ability to parse these comments; you
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
19 must either rebuild vim from source, or go ":ts=4" yourself each time you load
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
20 the file.</p>
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
21
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
22 <p>Gotos are allowed for error handling, and for breaking out of
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
23 nested loops. In general, a goto should only jump forward (not back), and
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
24 should either jump to the end of an outer loop, or to error handling code
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
25 at the end of the function. Goto labels are never indented: they override the
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
26 block structure of the file. Putting them at the left edge makes them easy
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
27 to spot as overrides to the normal flow of control, which they are.</p>
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
28
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
29 <p><h1>Building Toybox:</h1></p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
30
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
31 <p>Toybox is configured using the Kconfig language pioneered by the Linux
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
32 kernel, and adopted by many other projects (uClibc, OpenEmbedded, etc).
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
33 This generates a ".config" file containing the selected options, which
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
34 controls which features to enable when building toybox.</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
35
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
36 <p>Each configuration option has a default value. The defaults indicate the
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
37 "maximum sane configuration", I.E. if the feature defaults to "n" then it
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
38 either isn't complete or is a special-purpose option (such as debugging
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
39 code) that isn't intended for general purpose use.</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
40
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
41 <p>The standard build invocation is:</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
42
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
43 <ul>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
44 <li>make defconfig #(or menuconfig)</li>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
45 <li>make</li>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
46 <li>make install</li>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
47 </ul>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
48
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
49 <p>Type "make help" to see all available build options.</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
50
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
51 <p>The file "configure" contains a number of environment variable definitions
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
52 which influence the build, such as specifying which compiler to use or where
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
53 to install the resulting binaries. This file is included by the build, but
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
54 accepts existing definitions of the environment variables, so it may be sourced
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
55 or modified by the developer before building and the definitions exported
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
56 to the environment will take precedence.</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
57
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
58 <p>(To clarify: "configure" describes the build and installation environment,
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
59 ".config" lists the features selected by defconfig/menuconfig.)</p>
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
60
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
61 <p><h1>Infrastructure:</h1></p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
62
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
63 <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
64 <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
65 <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
66 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
67 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
68 <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
69 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
70 <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
71 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
72 <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
73 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
74 <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
75 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
76 <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
77 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
78 </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
79
501
8abb9e307d0c Web page tweaks. Remove background image (makes it hard ot read for some people), and use local roadmap instead of third party wiki.
Rob Landley <rob@landley.net>
parents: 432
diff changeset
80 <a name="adding" />
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
81 <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
82 <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
83 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
84 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
85 formatted comments and macros in the C file. (See the description of the
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
86 <a href="#generated">"generated" directory</a> for details.)</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
87
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 <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
89 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
90 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
91 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
92 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
93 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
94 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
95 (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
96 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
97
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 <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
99
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 <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
101 <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
102 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
103 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
104
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 <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
106 "hello.c - A hello world program") to describe your new file.</p></li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
107
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 <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
109 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
110
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
111 <li><p>Give a URL to the relevant standards document, or say "Not in SUSv4" if
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
112 there is no relevant standard. (Currently both lines are there, delete
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
113 whichever is inappropriate.) The existing link goes to the directory of SUSv4
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
114 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
115 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
116 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
117
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
118 <li><p>Update the USE_YOURCOMMAND(NEWTOY(yourcommand,"blah",0)) line.
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
119 The NEWTOY macro fills out this command's <a href="#toy_list">toy_list</a>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
120 structure. The arguments to the NEWTOY macro are:</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
121
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
122 <ol>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
123 <li><p>the name used to run your command</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
124 <li><p>the command line argument <a href="#lib_args">option parsing string</a> (NULL if none)</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
125 <li><p>a bitfield of TOYFLAG values
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
126 (defined in toys.h) providing additional information such as where your
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
127 command should be installed on a running system, whether to blank umask
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
128 before running, whether or not the command must run as root (and thus should
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
129 retain root access if installed SUID), and so on.</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
130 </ol>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
131 </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
132
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
133 <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
134 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
135 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
136 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
137 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
138 describe your new command. (See [TODO] for details.) By convention,
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
139 unfinished commands default to "n" and finished commands default to "y",
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
140 so "make defconfig" selects all finished commands. (Note, "finished" means
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
141 "ready to be used", not that it'll never change again.)<p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
142
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
143 <p>Each help block should start with a "usage: yourcommand" line explaining
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
144 any command line arguments added by this config option. The "help" command
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
145 outputs this text, and scripts/config2help.c in the build infrastructure
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
146 collates these usage lines for commands with multiple configuration
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
147 options when producing generated/help.h.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
148 </li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
149
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
150 <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
151 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
152 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
153 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
154 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
155 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
156 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
157 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
158
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
159 <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
160 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
161 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
162 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
163 "->".)</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
164
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
165 <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
166 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
167 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
168 </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
169
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
170 <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
171
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
172 <p>This directory contains global infrastructure.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
173
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
174 <h3>toys.h</h3>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
175 <p>Each command #includes "toys.h" as part of its standard prolog.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
176
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
177 <p>This file sucks in most of the commonly used standard #includes, so
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
178 individual files can just #include "toys.h" and not have to worry about
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
179 stdargs.h and so on. Individual commands still need to #include
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
180 special-purpose headers that may not be present on all systems (and thus would
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
181 prevent toybox from building that command on such a system with that command
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
182 enabled). Examples include regex support, any "linux/" or "asm/" headers, mtab
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
183 support (mntent.h and sys/mount.h), and so on.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
184
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
185 <p>The toys.h header also defines structures for most of the global variables
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
186 provided to each command by toybox_main(). These are described in
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
187 detail in the description for main.c, where they are initialized.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
188
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
189 <p>The global variables are grouped into structures (and a union) for space
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
190 savings, to more easily track the amount of memory consumed by them,
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
191 so that they may be automatically cleared/initialized as needed, and so
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
192 that access to global variables is more easily distinguished from access to
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
193 local variables.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
194
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
195 <h3>main.c</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
196 <p>Contains the main() function where execution starts, plus
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
197 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
198 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
199 only command defined outside of the toys directory.)</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
200
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
201 <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
202 name and calls toybox_main(), which calls toy_exec(), which calls toy_find()
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
203 and toy_init() before calling the appropriate command's function from
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
204 toy_list[] (via toys.which->toy_main()).
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
205 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
206 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
207 directory.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
208
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
209 <p>The following global variables are defined in main.c:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
210 <ul>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
211 <a name="toy_list" />
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
212 <li><p><b>struct toy_list toy_list[]</b> - array describing all the
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
213 commands currently configured into toybox. The first entry (toy_list[0]) is
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
214 for the "toybox" multiplexer command, which runs all the other built-in commands
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
215 without symlinks by using its first argument as the name of the command to
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
216 run and the rest as that command's argument list (ala "./toybox echo hello").
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
217 The remaining entries are the commands in alphabetical order (for efficient
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
218 binary search).</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
219
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
220 <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
221 defining macros and #including generated/newtoys.h.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
222
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
223 <p>Members of struct toy_list (defined in "toys.h") include:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
224 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
225 <li><p>char *<b>name</b> - the name of this command.</p></li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
226 <li><p>void (*<b>toy_main</b>)(void) - function pointer to run this
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
227 command.</p></li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
228 <li><p>char *<b>options</b> - command line option string (used by
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
229 get_optflags() in lib/args.c to intialize toys.optflags, toys.optargs, and
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
230 entries in the toy's DEFINE_GLOBALS struct). When this is NULL, no option
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
231 parsing is done before calling toy_main().</p></li>
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
232 <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
233
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
234 <ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
235 <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
236 <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
237 <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
238 <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
239 <li><b>TOYFLAG_UMASK</b> - Call umask(0) before running this command.</li>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
240 <li><b>TOYFLAG_STAYROOT</b> - Don't drop permissions for this command if toybox is installed SUID root.</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
241 <li><b>TOYFLAG_NEEDROOT</b> - This command cannot function unless run with root access.</li>
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
242 </ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
243 <br>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
244
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
245 <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
246 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
247 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
248 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
249
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
250 <li><p><b>struct toy_context toys</b> - global structure containing information
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
251 common to all commands, initializd by toy_init() and defined in "toys.h".
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
252 Members of this structure include:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
253 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
254 <li><p>struct toy_list *<b>which</b> - a pointer to this command's toy_list
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
255 structure. Mostly used to grab the name of the running command
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
256 (toys->which.name).</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
257 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
258 <li><p>int <b>exitval</b> - Exit value of this command. Defaults to zero. The
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
259 error_exit() functions will return 1 if this is zero, otherwise they'll
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
260 return this value.</p></li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
261 <li><p>char **<b>argv</b> - "raw" command line options, I.E. the original
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
262 unmodified string array passed in to main(). Note that modifying this changes
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
263 "ps" output, and is not recommended. This array is null terminated; a NULL
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
264 entry indicates the end of the array.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
265 <p>Most commands don't use this field, instead the use optargs, optflags,
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
266 and the fields in the DEFINE_GLOBALS struct initialized by get_optflags().</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
267 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
268 <li><p>unsigned <b>optflags</b> - Command line option flags, set by
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
269 <a href="#lib_args">get_optflags()</a>. 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
270 toys->which.options occurred this time.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
271
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
272 <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
273 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
274 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
275 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
276 "-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
277
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
278 <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
279 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
280 (see [TODO] DECLARE_GLOBALS() for details).</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
281
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
282 <p>For more information on option parsing, see <a href="#lib_args">get_optflags()</a>.</p>
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
283
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
284 </li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
285 <li><p>char **<b>optargs</b> - Null terminated array of arguments left over
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
286 after get_optflags() removed all the ones it understood. Note: optarg[0] is
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
287 the first argument, not the command name. Use toys.which->name for the command
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
288 name.</p></li>
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
289 <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
290 optargs[].<p></li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
291 <li><p>int <b>exithelp</b> - Whether error_exit() should print a usage message
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
292 via help_main() before exiting. (True during option parsing, defaults to
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
293 false afterwards.)</p></li>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
294 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
295
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
296 <li><p><b>union toy_union this</b> - Union of structures containing each
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
297 command's global variables.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
298
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
299 <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
300 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
301 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
302 can also initialize global variables with its results.</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 <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
305 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
306 running would be wasteful.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
307
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
308 <p>Toybox handles this by encapsulating each command's global variables in
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
309 a structure, and declaring a union of those structures with a single global
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
310 instance (called "this"). The DEFINE_GLOBALS() macro contains the global
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
311 variables that should go in the current command's global structure. Each
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
312 variable can then be accessed as "this.commandname.varname".
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
313 Generally, the macro TT is #defined to this.commandname so the variable
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
314 can then be accessed as "TT.variable". See toys/hello.c for an example.</p>
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
315
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
316 <p>A command that needs global variables should declare a structure to
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
317 contain them all, and add that structure to this union. A command should never
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
318 declare global variables outside of this, because such global variables would
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
319 allocate memory when running other commands that don't use those global
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
320 variables.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
321
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
322 <p>The first few fields of this structure can be intialized by <a href="#lib_args">get_optargs()</a>,
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
323 as specified by the options field off this command's toy_list entry. See
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
324 the get_optargs() description in lib/args.c for details.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
325 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
326
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
327 <li><b>char toybuf[4096]</b> - a common scratch space buffer so
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
328 commands don't need to allocate their own. Any command is free to use this,
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
329 and it should never be directly referenced by functions in lib/ (although
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
330 commands are free to pass toybuf in to a library function as an argument).</li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
331 </ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
332
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
333 <p>The following functions are defined in main.c:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
334 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
335 <li><p>struct toy_list *<b>toy_find</b>(char *name) - Return the toy_list
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
336 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
337 <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
338 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
339 <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
340 arguments.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
341 <p>Calls toy_find() on argv[0] (which must be just a command name
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
342 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
343 toy_init(), toys->which.toy_main(), and exit() instead of returning.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
344
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
345 <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
346 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
347 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
348 never match an internal command.</li>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
349
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
350 <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
351 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
352 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
353 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
354 install path prepended.</p></li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
355
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
356 </ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
357
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
358 <h3>Config.in</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
359
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
360 <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
361 <a href=http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt>kconfig</a> format. Includes generated/Config.in.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
362
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
363 <p>These files are directly used by "make menuconfig" to select which commands
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
364 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
365 scripts/config2help.py to create generated/help.h.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
366
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
367 <h3>Temporary files:</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
368
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
369 <p>There is one temporary file in the top level source directory:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
370 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
371 <li><p><b>.config</b> - Configuration file generated by kconfig, indicating
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
372 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
373 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
374
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
375 <p>You can create a human readable "miniconfig" version of this file using
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
376 <a href=http://landley.net/aboriginal/new_platform.html#miniconfig>these
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
377 instructions</a>.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
378 </li>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
379 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
380
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
381 <a name="generated" />
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
382 <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
383 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
384 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
385 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
386 system).</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
387
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
388 <ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
389 <li><p><b>generated/config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros,
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
390 generated from .config by a sed invocation in the top level Makefile.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
391
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
392 <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
393 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
394 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
395 from the binary any code that cannot be reached). This saves space without
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
396 cluttering the code with #ifdefs or leading to configuration dependent build
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
397 breaks. (See the 1992 Usenix paper
415
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
398 <a href=http://doc.cat-v.org/henry_spencer/ifdef_considered_harmful.pdf>#ifdef
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
399 Considered Harmful</a> for more information.)</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
400
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
401 <p>USE_SYMBOL(code) evaluates to the code in parentheses when the symbol
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
402 is enabled, and nothing when the symbol is disabled. This can be used
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
403 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
404 eliminated by a simple test on CFG_SYMBOL. Note that
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
405 (unlike CFG_SYMBOL) this is really just a variant of #ifdef, and can
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
406 still result in configuration dependent build breaks. Use with caution.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
407 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
408 </ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
409
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
410 <p><h2>Directory toys/</h2></p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
411
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
412 <h3>toys/Config.in</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
413
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
414 <p>Included from the top level Config.in, contains one or more
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
415 configuration entries for each command.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
416
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
417 <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
418 configuration symbols are uppercase and command names are lower case).
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
419 Options to commands start with the command name followed by an underscore and
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
420 the option name. Global options are attached to the "toybox" command,
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
421 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
422 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
423 .config.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
424
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
425 <p>A command with multiple names (or multiple similar commands implemented in
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
426 the same .c file) should have config symbols prefixed with the name of their
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
427 C file. I.E. config symbol prefixes are NEWTOY() names. If OLDTOY() names
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
428 have config symbols they're options (symbols with an underscore and suffix)
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
429 to the NEWTOY() name. (See toys/toylist.h)</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
430
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
431 <h3>toys/toylist.h</h3>
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
432 <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
433 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
434 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
435 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
436 prototypes).</p>
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
437
213
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
438 <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
439 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
440 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
441 are enabled wind up in the list.</p>
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
442
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
443 <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
444 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
445
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
446
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
447 <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
448 prototypes.
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
449 This
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
450 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
451 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
452 and to put the help entries in the right order in toys/help.c.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
453
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
454 <h3>toys/help.h</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
455
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
456 <p>#defines two help text strings for each command: a single line
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
457 command_help and an additinal command_help_long. This is used by help_main()
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
458 in toys/help.c to display help for commands.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
459
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
460 <p>Although this file is generated from Config.in help entries by
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
461 scripts/config2help.py, it's shipped in release tarballs so you don't need
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
462 python on the build system. (If you check code out of source control, or
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
463 modify Config.in, then you'll need python installed to rebuild it.)</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
464
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
465 <p>This file contains help for all commands, regardless of current
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
466 configuration, but only the currently enabled ones are entered into help_data[]
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
467 in toys/help.c.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
468
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
469 <a name="lib">
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
470 <h2>Directory lib/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
471
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
472 <p>TODO: document lots more here.</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
473
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
474 <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
475 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
476 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
477
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
478 <h3>lib/portability.h</h3>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
479
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
480 <p>This file is automatically included from the top of toys.h, and smooths
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
481 over differences between platforms (hardware targets, compilers, C libraries,
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
482 operating systems, etc).</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
483
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
484 <p>This file provides SWAP macros (SWAP_BE16(x) and SWAP_LE32(x) and so on).</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
485
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
486 <p>A macro like SWAP_LE32(x) means "The value in x is stored as a little
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
487 endian 32 bit value, so perform the translation to/from whatever the native
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
488 32-bit format is". You do the swap once on the way in, and once on the way
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
489 out. If your target is already little endian, the macro is a NOP.</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
490
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
491 <p>The SWAP macros come in BE and LE each with 16, 32, and 64 bit versions.
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
492 In each case, the name of the macro refers to the _external_ representation,
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
493 and converts to/from whatever your native representation happens to be (which
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
494 can vary depending on what you're currently compiling for).</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
495
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
496 <a name="lib_args"><h3>lib/args.c</h3>
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
497
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
498 <p>Toybox's main.c automatically parses command line options before calling the
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
499 command's main function. Option parsing starts in get_optflags(), which stores
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
500 results in the global structures "toys" (optflags and optargs) and "this".</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
501
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
502 <p>The option parsing infrastructure stores a bitfield in toys.optflags to
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
503 indicate which options the current command line contained. Arguments
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
504 attached to those options are saved into the command's global structure
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
505 ("this"). Any remaining command line arguments are collected together into
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
506 the null-terminated array toys.optargs, with the length in toys.optc. (Note
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
507 that toys.optargs does not contain the current command name at position zero,
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
508 use "toys.which->name" for that.) The raw command line arguments get_optflags()
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
509 parsed are retained unmodified in toys.argv[].</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
510
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
511 <p>Toybox's option parsing logic is controlled by an "optflags" string, using
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
512 a format reminiscent of getopt's optargs but has several important differences.
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
513 Toybox does not use the getopt()
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
514 function out of the C library, get_optflags() is an independent implementation
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
515 which doesn't permute the original arguments (and thus doesn't change how the
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
516 command is displayed in ps and top), and has many features not present in
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
517 libc optargs() (such as the ability to describe long options in the same string
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
518 as normal options).</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
519
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
520 <p>Each command's NEWTOY() macro has an optflags string as its middle argument,
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
521 which sets toy_list.options for that command to tell get_optflags() what
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
522 command line arguments to look for, and what to do with them.
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
523 If a command has no option
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
524 definition string (I.E. the argument is NULL), option parsing is skipped
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
525 for that command, which must look at the raw data in toys.argv to parse its
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
526 own arguments. (If no currently enabled command uses option parsing,
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
527 get_optflags() is optimized out of the resulting binary by the compiler's
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
528 --gc-sections option.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
529
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
530 <p>You don't have to free the option strings, which point into the environment
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
531 space (I.E. the string data is not copied). A TOYFLAG_NOFORK command
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
532 that uses the linked list type "*" should free the list objects but not
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
533 the data they point to, via "llist_free(TT.mylist, NULL);". (If it's not
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
534 NOFORK, exit() will free all the malloced data anyway unless you want
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
535 to implement a CONFIG_TOYBOX_FREE cleanup for it.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
536
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
537 <h4>Optflags format string</h4>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
538
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
539 <p>Note: the optflags option description string format is much more
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
540 concisely described by a large comment at the top of lib/args.c.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
541
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
542 <p>The general theory is that letters set optflags, and punctuation describes
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
543 other actions the option parsing logic should take.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
544
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
545 <p>For example, suppose the command line <b>command -b fruit -d walrus -a 42</b>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
546 is parsed using the optflags string "<b>a#b:c:d</b>". (I.E.
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
547 toys.which->options="a#b:c:d" and argv = ["command", "-b", "fruit", "-d",
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
548 "walrus", "-a", "42"]). When get_optflags() returns, the following data is
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
549 available to command_main():
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
550
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
551 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
552 <li><p>In <b>struct toys</b>:
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
553 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
554 <li>toys.optflags = 13; // -a = 8 | -b = 4 | -d = 1</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
555 <li>toys.optargs[0] = "walrus"; // leftover argument</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
556 <li>toys.optargs[1] = NULL; // end of list</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
557 <li>toys.optc=1; // there was 1 leftover argument</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
558 <li>toys.argv[] = {"-b", "fruit", "-d", "walrus", "-a", "42"}; // The original command line arguments
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
559 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
560 <p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
561
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
562 <li><p>In <b>union this</b> (treated as <b>long this[]</b>):
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
563 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
564 <li>this[0] = NULL; // -c didn't get an argument this time, so get_optflags() didn't change it and toys_init() zeroed "this" during setup.)</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
565 <li>this[1] = (long)"fruit"; // argument to -b</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
566 <li>this[2] = 42; // argument to -a</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
567 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
568 </p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
569 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
570
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
571 <p>If the command's globals are:</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
572
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
573 <blockquote><pre>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
574 DECLARE_GLOBALS(
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
575 char *c;
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
576 char *b;
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
577 long a;
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
578 )
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
579 #define TT this.command
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
580 </pre></blockquote>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
581 <p>That would mean TT.c == NULL, TT.b == "fruit", and TT.a == 42. (Remember,
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
582 each entry that receives an argument must be a long or pointer, to line up
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
583 with the array position. Right to left in the optflags string corresponds to
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
584 top to bottom in DECLARE_GLOBALS().</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
585
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
586 <p><b>long toys.optflags</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
587
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
588 <p>Each option in the optflags string corresponds to a bit position in
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
589 toys.optflags, with the same value as a corresponding binary digit. The
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
590 rightmost argument is (1<<0), the next to last is (1<<1) and so on. If
432
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents: 415
diff changeset
591 the option isn't encountered while parsing argv[], its bit remains 0.</p>
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents: 415
diff changeset
592
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents: 415
diff changeset
593 <p>For example,
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
594 the optflags string "abcd" would parse the command line argument "-c" to set
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
595 optflags to 2, "-a" would set optflags to 8, "-bd" would set optflags to
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
596 6 (I.E. 4|2), and "-a -c" would set optflags to 10 (2|8).</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
597
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
598 <p>Only letters are relevant to optflags, punctuation is skipped: in the
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
599 string "a*b:c#d", d=1, c=2, b=4, a=8. The punctuation after a letter
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
600 usually indicate that the option takes an argument.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
601
432
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents: 415
diff changeset
602 <p>Since toys.optflags is an unsigned int, it only stores 32 bits. (Which is
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents: 415
diff changeset
603 the amount a long would have on 32-bit platforms anyway; 64 bit code on
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents: 415
diff changeset
604 32 bit platforms is too expensive to require in common code used by almost
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents: 415
diff changeset
605 all commands.) Bit positions beyond the 1<<31 aren't recorded, but
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents: 415
diff changeset
606 parsing higher options can still set global variables.</p>
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents: 415
diff changeset
607
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
608 <p><b>Automatically setting global variables from arguments (union this)</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
609
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
610 <p>The following punctuation characters may be appended to an optflags
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
611 argument letter, indicating the option takes an additional argument:</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
612
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
613 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
614 <li><b>:</b> - plus a string argument, keep most recent if more than one.</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
615 <li><b>*</b> - plus a string argument, appended to a linked list.</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
616 <li><b>@</b> - plus an occurrence counter (stored in a long)</li>
415
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
617 <li><b>#</b> - plus a signed long argument.
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
618 <li><b>.</b> - plus a floating point argument (if CFG_TOYBOX_FLOAT).</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
619 <ul>The following can be appended to a float or double:
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
620 <li><b>&lt;123</b> - error if argument is less than this</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
621 <li><b>&gt;123</b> - error if argument is greater than this</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
622 <li><b>=123</b> - default value if argument not supplied</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
623 </ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
624 <ul><li>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
625 is enabled. (Otherwise the code to determine where floating point constants
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
626 end drops out. When disabled, it can reserve a global data slot for the
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
627 argument so offsets won't change, but will never fill it out.). You can handle
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
628 this by using the USE_BLAH() macros with C string concatenation, ala:
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
629 "abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</li></ul>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
630 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
631
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
632 <p>Arguments may occur with or without a space (I.E. "-a 42" or "-a42").
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
633 The command line argument "-abc" may be interepreted many different ways:
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
634 the optflags string "cba" sets toys.optflags = 7, "c:ba" sets toys.optflags=4
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
635 and saves "ba" as the argument to -c, and "cb:a" sets optflags to 6 and saves
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
636 "c" as the argument to -b.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
637
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
638 <p>Options which have an argument fill in the corresponding slot in the global
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
639 union "this" (see generated/globals.h), treating it as an array of longs
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
640 with the rightmost saved in this[0]. Again using "a*b:c#d", "-c 42" would set
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
641 this[0]=42; and "-b 42" would set this[1]="42"; each slot is left NULL if
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
642 the corresponding argument is not encountered.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
643
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
644 <p>This behavior is useful because the LP64 standard ensures long and pointer
432
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents: 415
diff changeset
645 are the same size. C99 guarantees structure members will occur in memory
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents: 415
diff changeset
646 in the same order they're declared, and that padding won't be inserted between
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
647 consecutive variables of register size. Thus the first few entries can
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
648 be longs or pointers corresponding to the saved arguments.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
649
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
650 <p><b>char *toys.optargs[]</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
651
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
652 <p>Command line arguments in argv[] which are not consumed by option parsing
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
653 (I.E. not recognized either as -flags or arguments to -flags) will be copied
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
654 to toys.optargs[], with the length of that array in toys.optc.
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
655 (When toys.optc is 0, no unrecognized command line arguments remain.)
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
656 The order of entries is preserved, and as with argv[] this new array is also
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
657 terminated by a NULL entry.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
658
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
659 <p>Option parsing can require a minimum or maximum number of optargs left
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
660 over, by adding "<1" (read "at least one") or ">9" ("at most nine") to the
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
661 start of the optflags string.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
662
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
663 <p>The special argument "--" terminates option parsing, storing all remaining
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
664 arguments in optargs. The "--" itself is consumed.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
665
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
666 <p><b>Other optflags control characters</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
667
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
668 <p>The following characters may occur at the start of each command's
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
669 optflags string, before any options that would set a bit in toys.optflags:</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
670
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
671 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
672 <li><b>^</b> - stop at first nonoption argument (for nice, xargs...)</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
673 <li><b>?</b> - allow unknown arguments (pass non-option arguments starting
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
674 with - through to optargs instead of erroring out).</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
675 <li><b>&amp;</b> - the first argument has imaginary dash (ala tar/ps. If given twice, all arguments have imaginary dash.)</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
676 <li><b>&lt;</b> - must be followed by a decimal digit indicating at least this many leftover arguments are needed in optargs (default 0)</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
677 <li><b>&gt;</b> - must be followed by a decimal digit indicating at most this many leftover arguments allowed (default MAX_INT)</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
678 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
679
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
680 <p>The following characters may be appended to an option character, but do
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
681 not by themselves indicate an extra argument should be saved in this[].
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
682 (Technically any character not recognized as a control character sets an
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
683 optflag, but letters are never control characters.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
684
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
685 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
686 <li><b>^</b> - stop parsing options after encountering this option, everything else goes into optargs.</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
687 <li><b>|</b> - this option is required. If more than one marked, only one is required.</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
688 <li><b>+X</b> enabling this option also enables option X (switch bit on).</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
689 <li><b>~X</b> enabling this option disables option X (switch bit off).</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
690 <li><b>!X</b> this option cannot be used in combination with X (die with error).</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
691 <li><b>[yz]</b> this option requires at least one of y or z to also be enabled.</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
692 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
693
415
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
694 <p>The following may be appended to a float or double:</p>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
695
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
696 <ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
697 <li><b>&lt;123</b> - error if argument is less than this</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
698 <li><b>&gt;123</b> - error if argument is greater than this</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
699 <li><b>=123</b> - default value if argument not supplied</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
700 </ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
701
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
702 <p>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
703 is enabled. (Otherwise the code to determine where floating point constants
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
704 end drops out. When disabled, it can reserve a global data slot for the
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
705 argument so offsets won't change, but will never fill it out.). You can handle
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
706 this by using the USE_BLAH() macros with C string concatenation, ala:</p>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
707
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
708 <blockquote>"abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</blockquote>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
709
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
710 <p><b>--longopts</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
711
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
712 <p>The optflags string can contain long options, which are enclosed in
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
713 parentheses. They may be appended to an existing option character, in
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
714 which case the --longopt is a synonym for that option, ala "a:(--fred)"
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
715 which understands "-a blah" or "--fred blah" as synonyms.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
716
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
717 <p>Longopts may also appear before any other options in the optflags string,
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
718 in which case they have no corresponding short argument, but instead set
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
719 their own bit based on position. So for "(walrus)#(blah)xy:z" "command
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
720 --walrus 42" would set toys.optflags = 16 (-z = 1, -y = 2, -x = 4, --blah = 8)
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
721 and would assign this[1] = 42;</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
722
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
723 <p>A short option may have multiple longopt synonyms, "a(one)(two)", but
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
724 each "bare longopt" (ala "(one)(two)abc" before any option characters)
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
725 always sets its own bit (although you can group them with +X).</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
726
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
727 <h2>Directory scripts/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
728
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
729 <h3>scripts/cfg2files.sh</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
730
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
731 <p>Run .config through this filter to get a list of enabled commands, which
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
732 is turned into a list of files in toys via a sed invocation in the top level
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
733 Makefile.
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
734 </p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
735
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
736 <h2>Directory kconfig/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
737
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
738 <p>Menuconfig infrastructure copied from the Linux kernel. See the
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
739 Linux kernel's Documentation/kbuild/kconfig-language.txt</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
740
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
741 <a name="generated">
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
742 <h2>Directory generated/</h2>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
743
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
744 <p>All the files in this directory except the README are generated by the
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
745 build. (See scripts/make.sh)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
746
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
747 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
748 <li><p><b>config.h</b> - CFG_COMMAND and USE_COMMAND() macros set by menuconfig via .config.</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
749
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
750 <li><p><b>Config.in</b> - Kconfig entries for each command. Included by top level Config.in. The help text in here is used to generated help.h</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
751
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
752 <li><p><b>help.h</b> - Help text strings for use by "help" command. Building
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
753 this file requires python on the host system, so the prebuilt file is shipped
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
754 in the build tarball to avoid requiring python to build toybox.</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
755
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
756 <li><p><b>newtoys.h</b> - List of NEWTOY() or OLDTOY() macros for all available
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
757 commands. Associates command_main() functions with command names, provides
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
758 option string for command line parsing (<a href="#lib_args">see lib/args.c</a>),
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
759 specifies where to install each command and whether toysh should fork before
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
760 calling it.</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
761 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
762
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
763 <p>Everything in this directory is a derivative file produced from something
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
764 else. The entire directory is deleted by "make distclean".</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
765 <!--#include file="footer.html" -->