annotate www/code.html @ 677:43c4f709b9ff

Doc tweak about test suite.
author Rob Landley <rob@landley.net>
date Mon, 08 Oct 2012 21:31:07 -0500
parents 7e846e281e38
children 786841fdb1e0
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
625
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
69 multiple commands:</li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
70 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
71 <li><a href="#lib_lib">lib/lib.c</a></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
72 <li><a href="#lib_llist">lib/llist.c</a></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
73 <li><a href="#lib_args">lib/args.c</a></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
74 <li><a href="#lib_dirtree">lib/dirtree.c</a></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
75 </ul>
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
76 <li>The <a href="#toys">toys directory</a> contains the C files implementating
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
77 each command. Currently it contains three subdirectories:
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
78 posix, lsb, and other.</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
79 <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
80 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
81 <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
82 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
83 <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
84 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
85 </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
86
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
87 <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
88 <p><h1>Adding a new command</h1></p>
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
89 <p>To add a new command to toybox, add a C file implementing that command under
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
90 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
91 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
92 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
93 <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
94
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
95 <p>Currently there are three subdirectories under "toys", one for commands
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
96 defined by the POSIX standard, one for commands defined by the Linux Standard
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
97 Base, and one for all other commands. (This is just for developer convenience
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
98 sorting them, the directories are otherwise functionally identical.)</p>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
99
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
100 <p>An easy way to start a new command is copy the file "toys/other/hello.c" to
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
101 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
102 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
103 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
104 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
105 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
106 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
107 (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
108 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
109
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 <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
111
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
112 <ul>
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
113 <li><p>First "cd toys/other" and "cp hello.c yourcommand.c". Note that the name
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 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
115 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
116
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 <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
118 "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
119
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
120 <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
121 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
122
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
123 <li><p>Give a URL to the relevant standards document, where applicable.
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
124 (Sample links to SUSv4 and LSB are provided, feel free to link to other
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
125 documentation or standards as appropriate.)</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
126
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
127 <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
128 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
129 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
130
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
131 <ol>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
132 <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
133 <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
134 <li><p>a bitfield of TOYFLAG values
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
135 (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
136 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
137 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
138 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
139 </ol>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
140 </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
141
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
142 <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
143 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
144 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
145 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
146 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
147 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
148 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
149 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
150 "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
151
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
152 <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
153 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
154 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
155 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
156 options when producing generated/help.h.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
157 </li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
158
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
159 <li><p>Change the "#define FOR_hello" line to "#define FOR_yourcommand" right
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
160 before the "#include <toys.h>". (This selects the appropriate FLAG_ macros and
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
161 does a "#define TT this.yourcommand" so you can access the global variables
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
162 out of the space-saving union of structures. If you aren't using any command
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
163 flag bits and aren't defining a GLOBAL block, you can delete this line.)</p></li>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
164
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
165 <li><p>Update the GLOBALS() macro to contain your command's global
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
166 variables. If your command has no global variables, delete this macro.</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
167
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
168 <p>Variables in the GLOBALS() block are are stored in a space saving
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
169 <a href="#toy_union">union of structures</a> format, which may be accessed
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
170 using the TT macro as if TT were a global structure (so TT.membername).
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
171 If you specified two-character command line arguments in
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
172 NEWTOY(), the first few global variables will be initialized by the automatic
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
173 argument parsing logic, and the type and order of these variables must
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
174 correspond to the arguments specified in NEWTOY().
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
175 (See <a href="#lib_args">lib/args.c</a> for details.)</p></li>
239
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
176
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
177 <li><p>Rename hello_main() to yourcommand_main(). This is the main() function
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
178 where execution of your command starts. Your command line options are
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
179 already sorted into this.optflags, this.optargs, this.optc, and the GLOBALS()
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
180 as appropriate by the time this function is called. (See
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
181 <a href="#lib_args">get_optflags()</a> for details.</p></li>
239
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
182 </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
183
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
184 <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
185
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
186 <p>This directory contains global infrastructure.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
187
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
188 <h3>toys.h</h3>
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
189 <p>Each command #includes "toys.h" as part of its standard prolog. It
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
190 may "#define FOR_commandname" before doing so to get some extra entries
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
191 specific to this command.</p>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
192
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
193 <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
194 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
195 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
196 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
197 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
198 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
199 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
200
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
201 <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
202 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
203 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
204
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
205 <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
206 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
207 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
208 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
209 local variables.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
210
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
211 <h3>main.c</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
212 <p>Contains the main() function where execution starts, plus
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
213 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
214 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
215 only command defined outside of the toys directory.)</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
216
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
217 <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
218 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
219 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
220 toy_list[] (via toys.which->toy_main()).
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
221 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
222 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
223 directory.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
224
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
225 <p>The following global variables are defined in main.c:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
226 <ul>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
227 <a name="toy_list" />
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
228 <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
229 commands currently configured into toybox. The first entry (toy_list[0]) is
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
230 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
231 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
232 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
233 The remaining entries are the commands in alphabetical order (for efficient
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
234 binary search).</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
235
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
236 <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
237 defining macros and #including generated/newtoys.h.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
238
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
239 <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
240 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
241 <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
242 <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
243 command.</p></li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
244 <li><p>char *<b>options</b> - command line option string (used by
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
245 get_optflags() in lib/args.c to intialize toys.optflags, toys.optargs, and
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
246 entries in the toy's GLOBALS struct). When this is NULL, no option
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
247 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
248 <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
249
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
250 <ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
251 <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
252 <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
253 <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
254 <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
255 <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
256 <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
257 <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
258 </ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
259 <br>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
260
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
261 <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
262 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
263 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
264 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
265
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
266 <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
267 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
268 Members of this structure include:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
269 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
270 <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
271 structure. Mostly used to grab the name of the running command
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
272 (toys->which.name).</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
273 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
274 <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
275 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
276 return this value.</p></li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
277 <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
278 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
279 "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
280 entry indicates the end of the array.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
281 <p>Most commands don't use this field, instead the use optargs, optflags,
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
282 and the fields in the GLOBALS struct initialized by get_optflags().</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
283 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
284 <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
285 <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
286 toys->which.options occurred this time.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
287
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
288 <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
289 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
290 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
291 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
292 "-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
293
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
294 <p>Only letters are relevant to optflags. In the string "a*b:c#d", d=1, c=2,
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
295 b=4, a=8. Punctuation after a letter initializes global variables at the
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
296 start of the GLOBALS() block (see <a href="#toy_union">union toy_union this</a>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
297 for details).</p>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
298
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
299 <p>The build infrastructure creates FLAG_ macros for each option letter,
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
300 corresponding to the bit position, so you can check (toys.optflags & FLAG_x)
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
301 to see if a flag was specified. (The correct set of FLAG_ macros is selected
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
302 by defining FOR_mycommand before #including toys.h. The macros live in
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
303 toys/globals.h which is generated by scripts/make.sh.)</p>
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
304
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
305 <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
306
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
307 </li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
308 <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
309 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
310 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
311 name.</p></li>
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
312 <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
313 optargs[].<p></li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
314 <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
315 via help_main() before exiting. (True during option parsing, defaults to
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
316 false afterwards.)</p></li>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
317 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
318
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
319 <a name="toy_union" />
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
320 <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
321 command's global variables.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
322
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
323 <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
324 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
325 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
326 can also initialize global variables with its results.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
327
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
328 <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
329 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
330 running would be wasteful.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
331
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
332 <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
333 a structure, and declaring a union of those structures with a single global
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
334 instance (called "this"). The GLOBALS() macro contains the global
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
335 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
336 variable can then be accessed as "this.commandname.varname".
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
337 If you #defined FOR_commandname before including toys.h, the macro TT is
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
338 #defined to this.commandname so the variable can then be accessed as
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
339 "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
340
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
341 <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
342 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
343 declare global variables outside of this, because such global variables would
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
344 allocate memory when running other commands that don't use those global
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
345 variables.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
346
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
347 <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
348 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
349 the get_optargs() description in lib/args.c for details.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
350 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
351
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
352 <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
353 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
354 and it should never be directly referenced by functions in lib/ (although
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
355 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
356 </ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
357
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
358 <p>The following functions are defined in main.c:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
359 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
360 <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
361 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
362 <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
363 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
364 <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
365 arguments.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
366 <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
367 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
368 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
369
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
370 <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
371 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
372 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
373 never match an internal command.</li>
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 <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
376 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
377 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
378 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
379 install path prepended.</p></li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
380
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
381 </ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
382
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
383 <h3>Config.in</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
384
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
385 <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
386 <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
387
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
388 <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
389 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
390 scripts/config2help.py to create generated/help.h.</p>
200
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 <h3>Temporary files:</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
393
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
394 <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
395 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
396 <li><p><b>.config</b> - Configuration file generated by kconfig, indicating
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
397 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
398 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
399
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
400 <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
401 <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
402 instructions</a>.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
403 </li>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
404 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
405
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
406 <a name="generated" />
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
407 <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
408 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
409 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
410 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
411 system).</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
412
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
413 <ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
414 <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
415 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
416
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
417 <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
418 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
419 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
420 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
421 cluttering the code with #ifdefs or leading to configuration dependent build
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
422 breaks. (See the 1992 Usenix paper
415
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
423 <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
424 Considered Harmful</a> for more information.)</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
425
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
426 <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
427 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
428 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
429 eliminated by a simple test on CFG_SYMBOL. Note that
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
430 (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
431 still result in configuration dependent build breaks. Use with caution.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
432 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
433 </ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
434
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
435 <p><h2>Directory toys/</h2></p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
436
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
437 <h3>toys/Config.in</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
438
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
439 <p>Included from the top level Config.in, contains one or more
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
440 configuration entries for each command.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
441
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
442 <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
443 configuration symbols are uppercase and command names are lower case).
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
444 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
445 the option name. Global options are attached to the "toybox" command,
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
446 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
447 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
448 .config.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
449
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
450 <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
451 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
452 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
453 have config symbols they're options (symbols with an underscore and suffix)
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
454 to the NEWTOY() name. (See toys/toylist.h)</p>
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 <h3>toys/toylist.h</h3>
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
457 <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
458 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
459 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
460 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
461 prototypes).</p>
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
462
213
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
463 <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
464 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
465 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
466 are enabled wind up in the list.</p>
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
467
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
468 <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
469 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
470
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
471
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
472 <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
473 prototypes.
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
474 This
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
475 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
476 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
477 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
478
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
479 <h3>toys/help.h</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
480
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
481 <p>#defines two help text strings for each command: a single line
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
482 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
483 in toys/help.c to display help for commands.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
484
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
485 <p>Although this file is generated from Config.in help entries by
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
486 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
487 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
488 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
489
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
490 <p>This file contains help for all commands, regardless of current
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
491 configuration, but only the currently enabled ones are entered into help_data[]
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
492 in toys/help.c.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
493
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
494 <a name="lib">
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
495 <h2>Directory lib/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
496
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
497 <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
498
625
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
499 <p>lib: getmountlist(), error_msg/error_exit, xmalloc(),
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
500 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
501 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
502
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
503 <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
504
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
505 <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
506 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
507 operating systems, etc).</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
508
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
509 <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
510
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
511 <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
512 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
513 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
514 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
515
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
516 <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
517 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
518 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
519 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
520
625
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
521 <a name="lib_llist"><h3>lib/llist.c</h3>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
522
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
523 <p>Some generic single and doubly linked list functions, which take
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
524 advantage of a couple properties of C:</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
525
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
526 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
527 <li><p>Structure elements are laid out in memory in the order listed, and
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
528 the first element has no padding. This means you can always treat (typecast)
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
529 a pointer to a structure as a pointer to the first element of the structure,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
530 even if you don't know anything about the data following it.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
531
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
532 <li><p>An array of length zero at the end of a structure adds no space
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
533 to the sizeof() the structure, but if you calculate how much extra space
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
534 you want when you malloc() the structure it will be available at the end.
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
535 Since C has no bounds checking, this means each struct can have one variable
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
536 length array.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
537 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
538
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
539 <p>Toybox's list structures always have their <b>next</b> pointer as
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
540 the first entry of each struct, and singly linked lists end with a NULL pointer.
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
541 This allows generic code to traverse such lists without knowing anything
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
542 else about the specific structs composing them: if your pointer isn't NULL
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
543 typecast it to void ** and dereference once to get the next entry.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
544
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
545 <p><b>lib/lib.h</b> defines three structure types:</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
546 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
547 <li><p><b>struct string_list</b> - stores a single string (<b>char str[0]</b>),
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
548 memory for which is allocated as part of the node. (I.E. llist_traverse(list,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
549 free); can clean up after this type of list.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
550
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
551 <li><p><b>struct arg_list</b> - stores a pointer to a single string
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
552 (<b>char *arg</b>) which is stored in a separate chunk of memory.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
553
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
554 <li><p><b>struct double_list</b> - has a second pointer (<b>struct double_list
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
555 *prev</b> along with a <b>char *data</b> for payload.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
556 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
557
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
558 <b>List Functions</b>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
559
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
560 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
561 <li><p>void *<b>llist_pop</b>(void **list) - advances through a list ala
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
562 <b>node = llist_pop(&list);</b> This doesn't modify the list contents,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
563 but does advance the pointer you feed it (which is why you pass the _address_
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
564 of that pointer, not the pointer itself).</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
565
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
566 <li><p>void <b>llist_traverse</b>(void *list, void (*using)(void *data)) -
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
567 iterate through a list calling a function on each node.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
568
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
569 <li><p>struct double_list *<b>dlist_add</b>(struct double_list **llist, char *data)
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
570 - append an entry to a circular linked list.
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
571 This function allocates a new struct double_list wrapper and returns the
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
572 pointer to the new entry (which you can usually ignore since it's llist->prev,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
573 but if llist was NULL you need it). The argument is the ->data field for the
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
574 new node.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
575 <ul><li><p>void <b>dlist_add_nomalloc</b>(struct double_list **llist,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
576 struct double_list *new) - append existing struct double_list to
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
577 list, does not allocate anything.</p></li></ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
578 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
579
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
580 <b>Trivia questions:</b>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
581
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
582 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
583 <li><p><b>Why do arg_list and double_list contain a char * payload instead of
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
584 a void *?</b> - Because you always have to typecast a void * to use it, and
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
585 typecasting a char * does no harm. Thus having it default to the most common
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
586 pointer type saves a few typecasts (strings are the most common payload),
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
587 and doesn't hurt anything otherwise.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
588 </li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
589
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
590 <li><p><b>Why do the names ->str, ->arg, and ->data differ?</b> - To force
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
591 you to keep track of which one you're using, calling free(node->str) would
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
592 be bad, and _failing_ to free(node->arg) leaks memory.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
593
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
594 <li><p><b>Why does llist_pop() take a void * instead of void **?</b> -
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
595 because the stupid compiler complains about "type punned pointers" when
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
596 you typecast and dereference ont he same line,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
597 due to insane FSF developers hardwiring limitations of their optimizer
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
598 into gcc's warning system. Since C automatically typecasts any other
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
599 pointer _down_ to a void *, the current code works fine. It's sad that it
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
600 won't warn you if you forget the &, but the code crashes pretty quickly in
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
601 that case.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
602
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
603 <li><p><b>How do I assemble a singly-linked-list in order?</b> - use
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
604 a double_list, dlist_add() your entries, and then break the circle with
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
605 <b>list->prev->next = NULL;</b> when done.</li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
606 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
607
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
608 <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
609
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
610 <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
611 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
612 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
613
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
614 <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
615 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
616 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
617 ("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
618 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
619 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
620 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
621 parsed are retained unmodified in toys.argv[].</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
622
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
623 <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
624 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
625 Toybox does not use the getopt()
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
626 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
627 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
628 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
629 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
630 as normal options).</p>
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>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
633 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
634 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
635 If a command has no option
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
636 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
637 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
638 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
639 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
640 --gc-sections option.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
641
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
642 <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
643 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
644 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
645 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
646 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
647 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
648
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
649 <h4>Optflags format string</h4>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
650
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
651 <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
652 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
653
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
654 <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
655 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
656
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
657 <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
658 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
659 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
660 "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
661 available to command_main():
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 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
664 <li><p>In <b>struct toys</b>:
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
665 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
666 <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
667 <li>toys.optargs[0] = "walrus"; // leftover argument</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
668 <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
669 <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
670 <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
671 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
672 <p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
673
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
674 <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
675 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
676 <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
677 <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
678 <li>this[2] = 42; // argument to -a</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
679 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
680 </p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
681 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
682
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
683 <p>If the command's globals are:</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 <blockquote><pre>
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
686 GLOBALS(
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
687 char *c;
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
688 char *b;
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
689 long a;
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
690 )
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
691 </pre></blockquote>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
692 <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
693 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
694 with the array position. Right to left in the optflags string corresponds to
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
695 top to bottom in GLOBALS().</p>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
696
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
697 <p><b>long toys.optflags</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
698
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
699 <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
700 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
701 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
702 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
703
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
704 <p>For example,
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
705 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
706 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
707 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
708
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
709 <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
710 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
711 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
712
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
713 <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
714 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
715 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
716 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
717 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
718
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
719 <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
720
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
721 <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
722 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
723
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
724 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
725 <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
726 <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
727 <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
728 <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
729 <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
730 <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
731 <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
732 <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
733 <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
734 </ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
735 <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
736 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
737 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
738 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
739 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
740 "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
741 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
742
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
743 <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
744 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
745 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
746 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
747 "c" as the argument to -b.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
748
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
749 <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
750 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
751 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
752 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
753 the corresponding argument is not encountered.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
754
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
755 <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
756 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
757 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
758 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
759 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
760
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
761 <p><b>char *toys.optargs[]</b></p>
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>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
764 (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
765 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
766 (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
767 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
768 terminated by a NULL entry.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
769
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
770 <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
771 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
772 start of the optflags string.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
773
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
774 <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
775 arguments in optargs. The "--" itself is consumed.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
776
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
777 <p><b>Other optflags control characters</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
778
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
779 <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
780 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
781
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
782 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
783 <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
784 <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
785 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
786 <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
787 <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
788 <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
789 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
790
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
791 <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
792 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
793 (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
794 optflag, but letters are never control characters.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
795
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
796 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
797 <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
798 <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
799 <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
800 <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
801 <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
802 <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
803 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
804
415
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
805 <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
806
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
807 <ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
808 <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
809 <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
810 <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
811 </ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
812
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
813 <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
814 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
815 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
816 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
817 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
818
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
819 <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
820
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
821 <p><b>--longopts</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
822
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
823 <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
824 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
825 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
826 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
827
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
828 <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
829 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
830 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
831 --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
832 and would assign this[1] = 42;</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
833
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
834 <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
835 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
836 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
837
625
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
838 <a name="lib_dirtree"><h3>lib/dirtree.c</h3>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
839
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
840 <p>The directory tree traversal code should be sufficiently generic
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
841 that commands never need to use readdir(), scandir(), or the fts.h family
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
842 of functions.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
843
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
844 <p>These functions do not call chdir() or rely on PATH_MAX. Instead they
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
845 use openat() and friends, using one filehandle per directory level to
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
846 recurseinto subdirectories. (I.E. they can descend 1000 directories deep
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
847 if setrlimit(RLIMIT_NOFILE) allows enough open filehandles, and the default
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
848 in /proc/self/limits is generally 1024.)</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
849
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
850 <p>The basic dirtree functions are:</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
851
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
852 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
853 <li><p><b>dirtree_read(char *path, int (*callback)(struct dirtree node))</b> -
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
854 recursively read directories, either applying callback() or returning
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
855 a tree of struct dirtree if callback is NULL.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
856
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
857 <li><p><b>dirtree_path(struct dirtree *node, int *plen)</b> - malloc() a
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
858 string containing the path from the root of this tree to this node. If
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
859 plen isn't NULL then *plen is how many extra bytes to malloc at the end
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
860 of string.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
861
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
862 <li><p><b>dirtree_parentfd(struct dirtree *node)</b> - return fd of
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
863 containing directory, for use with openat() and such.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
864 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
865
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
866 <p>The <b>dirtree_read()</b> function takes two arguments, a starting path for
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
867 the root of the tree, and a callback function. The callback takes a
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
868 <b>struct dirtree *</b> (from lib/lib.h) as its argument. If the callback is
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
869 NULL, the traversal uses a default callback (dirtree_notdotdot()) which
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
870 recursively assembles a tree of struct dirtree nodes for all files under
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
871 this directory and subdirectories (filtering out "." and ".." entries),
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
872 after which dirtree_read() returns the pointer to the root node of this
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
873 snapshot tree.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
874
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
875 <p>Otherwise the callback() is called on each entry in the directory,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
876 with struct dirtree * as its argument. This includes the initial
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
877 node created by dirtree_read() at the top of the tree.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
878
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
879 <p><b>struct dirtree</b></p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
880
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
881 <p>Each struct dirtree node contains <b>char name[]</b> and <b>struct stat
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
882 st</b> entries describing a file, plus a <b>char *symlink</b>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
883 which is NULL for non-symlinks.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
884
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
885 <p>During a callback function, the <b>int data</b> field of directory nodes
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
886 contains a dirfd (for use with the openat() family of functions). This is
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
887 generally used by calling dirtree_parentfd() on the callback's node argument.
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
888 For symlinks, data contains the length of the symlink string. On the second
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
889 callback from DIRTREE_COMEAGAIN (depth-first traversal) data = -1 for
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
890 all nodes (that's how you can tell it's the second callback).</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
891
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
892 <p>Users of this code may put anything they like into the <b>long extra</b>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
893 field. For example, "cp" and "mv" use this to store a dirfd for the destination
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
894 directory (and use DIRTREE_COMEAGAIN to get the second callback so they can
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
895 close(node->extra) to avoid running out of filehandles).
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
896 This field is not directly used by the dirtree code, and
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
897 thanks to LP64 it's large enough to store a typecast pointer to an
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
898 arbitrary struct.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
899
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
900 <p>The return value of the callback combines flags (with boolean or) to tell
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
901 the traversal infrastructure how to behave:</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
902
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
903 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
904 <li><p><b>DIRTREE_SAVE</b> - Save this node, assembling a tree. (Without
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
905 this the struct dirtree is freed after the callback returns. Filtering out
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
906 siblings is fine, but discarding a parent while keeping its child leaks
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
907 memory.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
908 <li><p><b>DIRTREE_ABORT</b> - Do not examine any more entries in this
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
909 directory. (Does not propagate up tree: to abort entire traversal,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
910 return DIRTREE_ABORT from parent callbacks too.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
911 <li><p><b>DIRTREE_RECURSE</b> - Examine directory contents. Ignored for
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
912 non-directory entries. The remaining flags only take effect when
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
913 recursing into the children of a directory.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
914 <li><p><b>DIRTREE_COMEAGAIN</b> - Call the callback a second time after
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
915 examining all directory contents, allowing depth-first traversal.
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
916 On the second call, dirtree->data = -1.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
917 <li><p><b>DIRTREE_SYMFOLLOW</b> - follow symlinks when populating children's
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
918 <b>struct stat st</b> (by feeding a nonzero value to the symfollow argument of
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
919 dirtree_add_node()), which means DIRTREE_RECURSE treats symlinks to
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
920 directories as directories. (Avoiding infinite recursion is the callback's
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
921 problem: the non-NULL dirtree->symlink can still distinguish between
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
922 them.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
923 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
924
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
925 <p>Each struct dirtree contains three pointers (next, parent, and child)
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
926 to other struct dirtree.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
927
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
928 <p>The <b>parent</b> pointer indicates the directory
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
929 containing this entry; even when not assembling a persistent tree of
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
930 nodes the parent entries remain live up to the root of the tree while
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
931 child nodes are active. At the top of the tree the parent pointer is
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
932 NULL, meaning the node's name[] is either an absolute path or relative
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
933 to cwd. The function dirtree_parentfd() gets the directory file descriptor
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
934 for use with openat() and friends, returning AT_FDCWD at the top of tree.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
935
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
936 <p>The <b>child</b> pointer points to the first node of the list of contents of
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
937 this directory. If the directory contains no files, or the entry isn't
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
938 a directory, child is NULL.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
939
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
940 <p>The <b>next</b> pointer indicates sibling nodes in the same directory as this
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
941 node, and since it's the first entry in the struct the llist.c traversal
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
942 mechanisms work to iterate over sibling nodes. Each dirtree node is a
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
943 single malloc() (even char *symlink points to memory at the end of the node),
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
944 so llist_free() works but its callback must descend into child nodes (freeing
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
945 a tree, not just a linked list), plus whatever the user stored in extra.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
946
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
947 <p>The <b>dirtree_read</b>() function is a simple wrapper, calling <b>dirtree_add_node</b>()
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
948 to create a root node relative to the current directory, then calling
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
949 <b>handle_callback</b>() on that node (which recurses as instructed by the callback
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
950 return flags). Some commands (such as chgrp) bypass this wrapper, for example
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
951 to control whether or not to follow symlinks to the root node; symlinks
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
952 listed on the command line are often treated differently than symlinks
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
953 encountered during recursive directory traversal).
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
954
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
955 <p>The ls command not only bypasses the wrapper, but never returns
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
956 <b>DIRTREE_RECURSE</b> from the callback, instead calling <b>dirtree_recurse</b>() manually
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
957 from elsewhere in the program. This gives ls -lR manual control
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
958 of traversal order, which is neither depth first nor breadth first but
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
959 instead a sort of FIFO order requried by the ls standard.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
960
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
961 <a name="#toys">
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
962 <h2>Directory toys/</h2>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
963
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
964 <p>This directory contains command implementations. Each command is a single
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
965 self-contained file. Adding a new command involves adding a single
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
966 file, and removing a command involves removing that file. Commands use
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
967 shared infrastructure from the lib/ and generated/ directories.</p>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
968
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
969 <p>Currently there are three subdirectories under "toys/" containing commands
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
970 described in POSIX-2008, the Linux Standard Base 4.1, or "other". The only
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
971 difference this makes is which menu the command shows up in during "make
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
972 menuconfig", the directories are otherwise identical. Note that they commands
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
973 exist within a single namespace at runtime, so you can't have the same
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
974 command in multiple subdirectories.</p>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
975
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
976 <p>(There are actually four sub-menus in "make menuconfig", the fourth
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
977 contains global configuration options for toybox, and lives in Config.in at
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
978 the top level.)</p>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
979
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
980 <p>See <a href="#adding">adding a new command</a> for details on the
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
981 layout of a command file.</p>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
982
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
983 <h2>Directory scripts/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
984
677
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
985 <p>Build infrastructure. The makefile calls scripts/make.sh for "make"
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
986 and scripts/install.sh for "make install".</p>
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
987
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
988 <p>There's also a test suite, "make test" calls make/test.sh, which runs all
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
989 the tests in make/test/*. You can run individual tests via
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
990 "scripts/test.sh command", or "TEST_HOST=1 scripts/test.sh command" to run
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
991 that test against the host implementation instead of the toybox one.</p>
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
992
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
993 <h3>scripts/cfg2files.sh</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
994
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
995 <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
996 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
997 Makefile.
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
998 </p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
999
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
1000 <h2>Directory kconfig/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1001
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1002 <p>Menuconfig infrastructure copied from the Linux kernel. See the
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1003 Linux kernel's Documentation/kbuild/kconfig-language.txt</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1004
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1005 <a name="generated">
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1006 <h2>Directory generated/</h2>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1007
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1008 <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
1009 build. (See scripts/make.sh)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1010
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1011 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1012 <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
1013
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1014 <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
1015
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1016 <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
1017 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
1018 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
1019
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1020 <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
1021 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
1022 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
1023 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
1024 calling it.</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1025 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1026
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1027 <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
1028 else. The entire directory is deleted by "make distclean".</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1029 <!--#include file="footer.html" -->