annotate www/code.html @ 1172:db517206d752 draft

Cosmetic tweak.
author Rob Landley <rob@landley.net>
date Sat, 28 Dec 2013 17:06:55 -0600
parents 17387db4d979
children 94eb7b9127d2
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
1015
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
3 <p><h1><a name="style" /><a href="#style">Code style</a></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
694
786841fdb1e0 Reindent to two spaces per level. Remove vi: directives that haven't worked right in years (ubuntu broke its' vim implementation). Remove trailing spaces. Add/remove blank lines. Re-wordwrap in places. Update documentation with new coding style.
Rob Landley <rob@landley.net>
parents: 677
diff changeset
16 <p>Toybox source uses two spaces per indentation level, and wraps at 80
786841fdb1e0 Reindent to two spaces per level. Remove vi: directives that haven't worked right in years (ubuntu broke its' vim implementation). Remove trailing spaces. Add/remove blank lines. Re-wordwrap in places. Update documentation with new coding style.
Rob Landley <rob@landley.net>
parents: 677
diff changeset
17 columns.</p>
217
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
18
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
19 <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
20 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
21 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
22 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
23 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
24 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
25
1015
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
26 <p><h1><a name="building" /><a href="#building">Building Toybox</a></h1></p>
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
27
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
28 <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
29 kernel, and adopted by many other projects (uClibc, OpenEmbedded, etc).
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
30 This generates a ".config" file containing the selected options, which
694
786841fdb1e0 Reindent to two spaces per level. Remove vi: directives that haven't worked right in years (ubuntu broke its' vim implementation). Remove trailing spaces. Add/remove blank lines. Re-wordwrap in places. Update documentation with new coding style.
Rob Landley <rob@landley.net>
parents: 677
diff changeset
31 controls which features are included when compiling toybox.</p>
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
32
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
33 <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
34 "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
35 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
36 code) that isn't intended for general purpose use.</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
37
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
38 <p>The standard build invocation is:</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
39
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
40 <ul>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
41 <li>make defconfig #(or menuconfig)</li>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
42 <li>make</li>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
43 <li>make install</li>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
44 </ul>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
45
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
46 <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
47
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
48 <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
49 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
50 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
51 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
52 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
53 to the environment will take precedence.</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
54
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
55 <p>(To clarify: "configure" describes the build and installation environment,
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
56 ".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
57
1015
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
58 <p><h1><a name="running"><a href="#running">Running a command</a></h1></p>
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
59
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
60 <h2>main</h2>
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
61
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
62 <p>The toybox main() function is at the end of main.c at the top level. It has
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
63 two possible codepaths, only one of which is configured into any given build
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
64 of toybox.</p>
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
65
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
66 <p>If CONFIG_SINGLE is selected, toybox is configured to contain only a single
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
67 command, so most of the normal setup can be skipped. In this case the
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
68 multiplexer isn't used, instead main() calls toy_singleinit() (also in main.c)
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
69 to set up global state and parse command line arguments, calls the command's
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
70 main function out of toy_list (in the CONFIG_SINGLE case the array has a single entry, no need to search), and if the function returns instead of exiting
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
71 it flushes stdout (detecting error) and returns toys.exitval.</p>
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
72
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
73 <p>When CONFIG_SINGLE is not selected, main() uses basename() to find the
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
74 name it was run as, shifts its argument list one to the right so it lines up
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
75 with where the multiplexer function expects it, and calls toybox_main(). This
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
76 leverages the multiplexer command's infrastructure to find and run the
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
77 appropriate command. (A command name starting with "toybox" will
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
78 recursively call toybox_main(); you can go "./toybox toybox toybox toybox ls"
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
79 if you want to...)</p>
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
80
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
81 <h2>toybox_main</h2>
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
82
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
83 <p>The toybox_main() function is also in main,c. It handles a possible
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
84 --help option ("toybox --help ls"), prints the list of available commands if no
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
85 arguments were provided to the multiplexer (or with full path names if any
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
86 other option is provided before a command name, ala "toybox --list").
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
87 Otherwise it calls toy_exec() on its argument list.</p>
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
88
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
89 <p>Note that the multiplexer is the first entry in toy_list (the rest of the
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
90 list is sorted alphabetically to allow binary search), so toybox_main can
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
91 cheat and just grab the first entry to quickly set up its context without
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
92 searching. Since all command names go through the multiplexer at least once
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
93 in the non-TOYBOX_SINGLE case, this avoids a redundant search of
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
94 the list.</p>
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
95
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
96 <p>The toy_exec() function is also in main.c. It performs toy_find() to
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
97 perform a binary search on the toy_list array to look up the command's
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
98 entry by name and saves it in the global variable which, calls toy_init()
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
99 to parse command line arguments and set up global state (using which->options),
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
100 and calls the appropriate command's main() function (which->toy_main). On
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
101 return it flushes all pending ansi FILE * I/O, detects if stdout had an
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
102 error, and then calls xexit() (which uses toys.exitval).</p>
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
103
27275d0d97e9 Document the toybox entry path from main() into a command.
Rob Landley <rob@landley.net>
parents: 694
diff changeset
104 <p><h1><a name="infrastructure" /><a href="#infrastructure">Infrastructure</a></h1></p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
105
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
106 <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
107 <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
108 <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
109 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
110 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
111 <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
112 multiple commands:</li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
113 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
114 <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
115 <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
116 <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
117 <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
118 </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
119 <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
120 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
121 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
122 <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
123 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
124 <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
125 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
126 <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
127 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
128 </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
129
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
130 <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
131 <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
132 <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
133 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
134 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
135 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
136 <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
137
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
138 <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
139 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
140 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
141 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
142
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
143 <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
144 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
145 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
146 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
147 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
148 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
149 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
150 (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
151 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
152
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
153 <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
154
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
155 <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
156 <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
157 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
158 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
159
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
160 <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
161 "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
162
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
163 <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
164 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
165
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
166 <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
167 (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
168 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
169
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
170 <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
171 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
172 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
173
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
174 <ol>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
175 <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
176 <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
177 <li><p>a bitfield of TOYFLAG values
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
178 (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
179 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
180 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
181 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
182 </ol>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
183 </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
184
4f1ca01db000 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 <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
186 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
187 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
188 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
189 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
190 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
191 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
192 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
193 "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
194
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
195 <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
196 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
197 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
198 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
199 options when producing generated/help.h.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
200 </li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
201
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
202 <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
203 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
204 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
205 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
206 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
207
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
208 <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
209 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
210
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
211 <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
212 <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
213 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
214 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
215 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
216 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
217 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
218 (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
219
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
220 <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
221 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
222 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
223 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
224 <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
225 </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
226
1167
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
227 <a name="headers" /><h2>Headers.</h2>
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
228
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
229 <p>Commands generally don't have their own headers. If it's common code
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
230 it can live in lib/, if it isn't put it in the command's .c file. (The line
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
231 between implementing multiple commands in a C file via OLDTOY() to share
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
232 infrastructure and moving that shared infrastructure to lib/ is a judgement
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
233 call. Try to figure out which is simplest.)</p>
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
234
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
235 <p>The top level toys.h should #include all the standard (posix) headers
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
236 that any command uses. (Partly this is friendly to ccache and partly this
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
237 makes the command implementations shorter.) Individual commands should only
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
238 need to include nonstandard headers that might prevent that command from
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
239 building in some context we'd care about (and thus requiring that command to
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
240 be disabled to avoid a build break).</p>
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
241
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
242 <p>Target-specific stuff (differences between compiler versions, libc versions,
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
243 or operating systems) should be confined to lib/portability.h and
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
244 lib/portability.c. (There's even some minimal compile-time environment probing
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
245 that writes data to generated/portability.h, see scripts/genconfig.sh.)</p>
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
246
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
247 <p>Only include linux/*.h headers from individual commands (not from other
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
248 headers), and only if you really need to. Data that varies per architecture
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
249 is a good reason to include a header. If you just need a couple constants
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
250 that haven't changed since the 1990's, it's ok to #define them yourself or
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
251 just use the constant inline with a comment explaining what it is. (A
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
252 #define that's only used once isn't really helping.)</p>
17387db4d979 New section on #including header files.
Rob Landley <rob@landley.net>
parents: 1073
diff changeset
253
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
254 <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
255
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
256 <p>This directory contains global infrastructure.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
257
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
258 <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
259 <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
260 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
261 specific to this command.</p>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
262
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
263 <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
264 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
265 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
266 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
267 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
268 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
269 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
270
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
271 <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
272 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
273 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
274
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
275 <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
276 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
277 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
278 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
279 local variables.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
280
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
281 <h3>main.c</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
282 <p>Contains the main() function where execution starts, plus
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
283 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
284 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
285 only command defined outside of the toys directory.)</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
286
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
287 <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
288 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
289 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
290 toy_list[] (via toys.which->toy_main()).
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
291 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
292 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
293 directory.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
294
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
295 <p>The following global variables are defined in main.c:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
296 <ul>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
297 <a name="toy_list" />
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
298 <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
299 commands currently configured into toybox. The first entry (toy_list[0]) is
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
300 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
301 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
302 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
303 The remaining entries are the commands in alphabetical order (for efficient
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
304 binary search).</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
305
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
306 <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
307 defining macros and #including generated/newtoys.h.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
308
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
309 <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
310 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
311 <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
312 <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
313 command.</p></li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
314 <li><p>char *<b>options</b> - command line option string (used by
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
315 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
316 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
317 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
318 <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
319
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
320 <ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
321 <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
322 <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
323 <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
324 <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
325 <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
326 <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
327 <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
328 </ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
329 <br>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
330
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
331 <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
332 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
333 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
334 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
335
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
336 <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
337 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
338 Members of this structure include:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
339 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
340 <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
341 structure. Mostly used to grab the name of the running command
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
342 (toys->which.name).</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
343 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
344 <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
345 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
346 return this value.</p></li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
347 <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
348 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
349 "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
350 entry indicates the end of the array.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
351 <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
352 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
353 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
354 <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
355 <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
356 toys->which.options occurred this time.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
357
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
358 <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
359 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
360 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
361 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
362 "-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
363
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
364 <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
365 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
366 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
367 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
368
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
369 <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
370 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
371 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
372 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
373 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
374
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
375 <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
376
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
377 </li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
378 <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
379 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
380 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
381 name.</p></li>
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
382 <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
383 optargs[].<p></li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
384 <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
385 via help_main() before exiting. (True during option parsing, defaults to
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
386 false afterwards.)</p></li>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
387 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
388
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
389 <a name="toy_union" />
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
390 <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
391 command's global variables.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
392
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
393 <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
394 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
395 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
396 can also initialize global variables with its results.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
397
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
398 <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
399 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
400 running would be wasteful.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
401
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
402 <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
403 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
404 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
405 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
406 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
407 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
408 #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
409 "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
410
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
411 <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
412 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
413 declare global variables outside of this, because such global variables would
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
414 allocate memory when running other commands that don't use those global
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
415 variables.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
416
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
417 <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
418 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
419 the get_optargs() description in lib/args.c for details.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
420 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
421
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
422 <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
423 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
424 and it should never be directly referenced by functions in lib/ (although
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
425 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
426 </ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
427
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
428 <p>The following functions are defined in main.c:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
429 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
430 <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
431 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
432 <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
433 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
434 <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
435 arguments.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
436 <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
437 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
438 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
439
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
440 <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
441 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
442 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
443 never match an internal command.</li>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
444
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
445 <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
446 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
447 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
448 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
449 install path prepended.</p></li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
450
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
451 </ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
452
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
453 <h3>Config.in</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
454
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
455 <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
456 <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
457
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
458 <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
459 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
460 scripts/config2help.py to create generated/help.h.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
461
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
462 <h3>Temporary files:</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
463
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
464 <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
465 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
466 <li><p><b>.config</b> - Configuration file generated by kconfig, indicating
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
467 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
468 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
469
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
470 <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
471 <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
472 instructions</a>.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
473 </li>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
474 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
475
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
476 <a name="generated" />
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
477 <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
478 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
479 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
480 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
481 system).</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
482
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
483 <ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
484 <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
485 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
486
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
487 <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
488 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
489 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
490 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
491 cluttering the code with #ifdefs or leading to configuration dependent build
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
492 breaks. (See the 1992 Usenix paper
415
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
493 <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
494 Considered Harmful</a> for more information.)</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
495
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
496 <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
497 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
498 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
499 eliminated by a simple test on CFG_SYMBOL. Note that
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
500 (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
501 still result in configuration dependent build breaks. Use with caution.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
502 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
503 </ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
504
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
505 <p><h2>Directory toys/</h2></p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
506
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
507 <h3>toys/Config.in</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
508
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
509 <p>Included from the top level Config.in, contains one or more
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
510 configuration entries for each command.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
511
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
512 <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
513 configuration symbols are uppercase and command names are lower case).
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
514 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
515 the option name. Global options are attached to the "toybox" command,
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
516 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
517 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
518 .config.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
519
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
520 <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
521 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
522 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
523 have config symbols they're options (symbols with an underscore and suffix)
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
524 to the NEWTOY() name. (See toys/toylist.h)</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
525
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
526 <h3>toys/toylist.h</h3>
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
527 <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
528 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
529 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
530 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
531 prototypes).</p>
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
532
213
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
533 <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
534 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
535 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
536 are enabled wind up in the list.</p>
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
537
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
538 <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
539 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
540
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
541
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
542 <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
543 prototypes.
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
544 This
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
545 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
546 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
547 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
548
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
549 <h3>toys/help.h</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
550
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
551 <p>#defines two help text strings for each command: a single line
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
552 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
553 in toys/help.c to display help for commands.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
554
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
555 <p>Although this file is generated from Config.in help entries by
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
556 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
557 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
558 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
559
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
560 <p>This file contains help for all commands, regardless of current
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
561 configuration, but only the currently enabled ones are entered into help_data[]
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
562 in toys/help.c.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
563
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
564 <a name="lib">
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
565 <h2>Directory lib/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
566
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
567 <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
568
625
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
569 <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
570 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
571 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
572
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
573 <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
574
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
575 <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
576 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
577 operating systems, etc).</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
578
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
579 <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
580
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
581 <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
582 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
583 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
584 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
585
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
586 <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
587 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
588 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
589 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
590
625
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
591 <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
592
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
593 <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
594 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
595
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
596 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
597 <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
598 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
599 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
600 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
601
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
602 <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
603 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
604 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
605 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
606 length array.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
607 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
608
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
609 <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
610 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
611 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
612 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
613 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
614
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
615 <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
616 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
617 <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
618 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
619 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
620
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
621 <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
622 (<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
623
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
624 <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
625 *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
626 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
627
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
628 <b>List Functions</b>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
629
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
630 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
631 <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
632 <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
633 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
634 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
635
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
636 <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
637 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
638
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
639 <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
640 - 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
641 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
642 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
643 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
644 new node.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
645 <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
646 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
647 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
648 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
649
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
650 <b>Trivia questions:</b>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
651
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
652 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
653 <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
654 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
655 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
656 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
657 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
658 </li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
659
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
660 <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
661 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
662 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
663
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
664 <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
665 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
666 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
667 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
668 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
669 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
670 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
671 that case.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
672
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
673 <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
674 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
675 <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
676 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
677
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
678 <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
679
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
680 <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
681 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
682 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
683
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
684 <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
685 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
686 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
687 ("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
688 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
689 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
690 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
691 parsed are retained unmodified in toys.argv[].</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
692
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
693 <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
694 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
695 Toybox does not use the getopt()
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
696 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
697 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
698 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
699 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
700 as normal options).</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
701
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
702 <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
703 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
704 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
705 If a command has no option
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
706 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
707 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
708 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
709 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
710 --gc-sections option.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
711
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
712 <p>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
713 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
714 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
715 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
716 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
717 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
718
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
719 <h4>Optflags format string</h4>
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>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
722 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
723
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
724 <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
725 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
726
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
727 <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
728 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
729 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
730 "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
731 available to command_main():
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
732
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
733 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
734 <li><p>In <b>struct toys</b>:
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
735 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
736 <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
737 <li>toys.optargs[0] = "walrus"; // leftover argument</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
738 <li>toys.optargs[1] = NULL; // end of list</li>
1073
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
739 <li>toys.optc = 1; // there was 1 leftover argument</li>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
740 <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
741 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
742 <p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
743
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
744 <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
745 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
746 <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
747 <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
748 <li>this[2] = 42; // argument to -a</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
749 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
750 </p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
751 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
752
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
753 <p>If the command's globals are:</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 <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
756 GLOBALS(
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
757 char *c;
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
758 char *b;
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
759 long a;
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 </pre></blockquote>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
762 <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
763 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
764 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
765 top to bottom in GLOBALS().</p>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
766
1073
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
767 <p>Put globals not filled out by the option parsing logic at the end of the
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
768 GLOBALS block. Common practice is to list the options one per line (to
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
769 make the ordering explicit, first to last in globals corresponds to right
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
770 to left in the option string), then leave a blank line before any non-option
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
771 globals.</p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
772
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
773 <p><b>long toys.optflags</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
774
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
775 <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
776 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
777 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
778 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
779
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
780 <p>For example,
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
781 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
782 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
783 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
784
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
785 <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
786 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
787 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
788
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
789 <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
790 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
791 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
792 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
793 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
794
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
795 <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
796
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
797 <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
798 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
799
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
800 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
801 <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
802 <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
803 <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
804 <li><b>#</b> - plus a signed long argument.
1073
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
805 <li><b>-</b> - plus a signed long argument defaulting to negative (start argument with + to force a positive value).</li>
415
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
806 <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
807 <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
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>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
812 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
813
1073
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
814 <p>A note about "." and CFG_TOYBOX_FLOAT: option parsing only understands <>=
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
815 after . when CFG_TOYBOX_FLOAT
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
816 is enabled. (Otherwise the code to determine where floating point constants
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
817 end drops out; it requires floating point). When disabled, it can reserve a
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
818 global data slot for the argument (so offsets won't change in your
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
819 GLOBALS[] block), but will never fill it out. You can handle
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
820 this by using the USE_BLAH() macros with C string concatenation, ala:
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
821 "abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
822
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
823 <p><b>GLOBALS</b></p>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
824
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
825 <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
826 union "this" (see generated/globals.h), treating it as an array of longs
1073
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
827 with the rightmost saved in this[0]. As described above, using "a*b:c#d",
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
828 "-c 42" would set this[0] = 42; and "-b 42" would set this[1] = "42"; each
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
829 slot is left NULL if the corresponding argument is not encountered.</p>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
830
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
831 <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
832 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
833 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
834 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
835 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
836
1073
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
837 <p>See toys/other/hello.c for a longer example of parsing options into the
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
838 GLOBALS block.</p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
839
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
840 <p><b>char *toys.optargs[]</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
841
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
842 <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
843 (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
844 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
845 (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
846 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
847 terminated by a NULL entry.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
848
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
849 <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
850 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
851 start of the optflags string.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
852
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
853 <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
854 arguments in optargs. The "--" itself is consumed.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
855
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
856 <p><b>Other optflags control characters</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
857
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
858 <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
859 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
860
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
861 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
862 <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
863 <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
864 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
865 <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
866 <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
867 <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
868 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
869
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
870 <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
871 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
872 (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
873 optflag, but letters are never control characters.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
874
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
875 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
876 <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
877 <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
878 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
879
415
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
880 <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
881
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
882 <ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
883 <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
884 <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
885 <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
886 </ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
887
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
888 <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
889 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
890 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
891 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
892 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
893
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
894 <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
895
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
896 <p><b>--longopts</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
897
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
898 <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
899 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
900 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
901 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
902
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
903 <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
904 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
905 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
906 --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
907 and would assign this[1] = 42;</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
908
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
909 <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
910 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
911 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
912
1073
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
913 <p><b>[groups]</b></p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
914
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
915 <p>At the end of the option string, square bracket groups can define
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
916 relationships between existing options. (This only applies to short
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
917 options, bare --longopts can't participate.)</p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
918
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
919 <p>The first character of the group defines the type, the remaining
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
920 characters are options it applies to:</p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
921
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
922 <ul>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
923 <li><b>-</b> - Exclusive, switch off all others in this group.</li>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
924 <li><b>+</b> - Inclusive, switch on all others in this group.</li>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
925 <li><b>!</b> - Error, fail if more than one defined.</li>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
926 </ul>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
927
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
928 <p>So "abc[-abc]" means -ab = -b, -ba = -a, -abc = -c. "abc[+abc]"
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
929 means -ab=-abc, -c=-abc, and "abc[!abc] means -ab calls error_exit("no -b
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
930 with -a"). Note that [-] groups clear the GLOBALS option slot of
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
931 options they're switching back off, but [+] won't set options it didn't see
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
932 (just the optflags).</p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
933
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
934 <p><b>whitespace</b></p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
935
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
936 <p>Arguments may occur with or without a space (I.E. "-a 42" or "-a42").
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
937 The command line argument "-abc" may be interepreted many different ways:
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
938 the optflags string "cba" sets toys.optflags = 7, "c:ba" sets toys.optflags=4
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
939 and saves "ba" as the argument to -c, and "cb:a" sets optflags to 6 and saves
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
940 "c" as the argument to -b.</p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
941
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
942 <p>Note that &amp; changes whitespace handling, so that the command line
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
943 "tar cvfCj outfile.tar.bz2 topdir filename" is parsed the same as
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
944 "tar filename -c -v -j -f outfile.tar.bz2 -C topdir". Note that "tar -cvfCj
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
945 one two three" would equal "tar -c -v -f Cj one two three". (This matches
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
946 historical usage.)</p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
947
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
948 <p>Appending a space to the option in the option string ("a: b") makes it
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
949 require a space, I.E. "-ab" is interpreted as "-a" "-b". That way "kill -stop"
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
950 differs from "kill -s top".</p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
951
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
952 <p>Appending ; to a longopt in the option string makes its argument optional,
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
953 and only settable with =, so in ls "(color):;" can accept "ls --color" and
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
954 "ls --color=auto" without complaining that the first has no argument.</p>
3c0e653070d8 Update lib/args.c docs.
Rob Landley <rob@landley.net>
parents: 1015
diff changeset
955
625
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
956 <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
957
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
958 <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
959 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
960 of functions.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
961
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
962 <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
963 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
964 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
965 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
966 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
967
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
968 <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
969
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
970 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
971 <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
972 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
973 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
974
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
975 <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
976 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
977 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
978 of string.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
979
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
980 <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
981 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
982 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
983
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
984 <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
985 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
986 <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
987 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
988 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
989 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
990 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
991 snapshot tree.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
992
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
993 <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
994 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
995 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
996
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
997 <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
998
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
999 <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
1000 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
1001 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
1002
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1003 <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
1004 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
1005 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
1006 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
1007 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
1008 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
1009
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1010 <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
1011 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
1012 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
1013 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
1014 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
1015 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
1016 arbitrary struct.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1017
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1018 <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
1019 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
1020
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1021 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1022 <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
1023 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
1024 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
1025 memory.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1026 <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
1027 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
1028 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
1029 <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
1030 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
1031 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
1032 <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
1033 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
1034 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
1035 <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
1036 <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
1037 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
1038 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
1039 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
1040 them.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1041 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1042
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1043 <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
1044 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
1045
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1046 <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
1047 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
1048 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
1049 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
1050 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
1051 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
1052 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
1053
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1054 <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
1055 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
1056 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
1057
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1058 <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
1059 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
1060 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
1061 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
1062 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
1063 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
1064
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1065 <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
1066 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
1067 <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
1068 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
1069 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
1070 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
1071 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
1072
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
1073 <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
1074 <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
1075 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
1076 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
1077 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
1078
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
1079 <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
1080 <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
1081
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
1082 <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
1083 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
1084 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
1085 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
1086
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
1087 <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
1088 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
1089 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
1090 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
1091 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
1092 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
1093
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
1094 <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
1095 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
1096 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
1097
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
1098 <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
1099 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
1100
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
1101 <h2>Directory scripts/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1102
677
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
1103 <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
1104 and scripts/install.sh for "make install".</p>
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
1105
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
1106 <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
1107 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
1108 "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
1109 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
1110
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1111 <h3>scripts/cfg2files.sh</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1112
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1113 <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
1114 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
1115 Makefile.
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1116 </p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1117
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
1118 <h2>Directory kconfig/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1119
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1120 <p>Menuconfig infrastructure copied from the Linux kernel. See the
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1121 Linux kernel's Documentation/kbuild/kconfig-language.txt</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1122
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1123 <a name="generated">
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1124 <h2>Directory generated/</h2>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1125
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1126 <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
1127 build. (See scripts/make.sh)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1128
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1129 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1130 <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
1131
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1132 <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
1133
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1134 <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
1135 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
1136 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
1137
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1138 <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
1139 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
1140 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
1141 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
1142 calling it.</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1143 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1144
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1145 <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
1146 else. The entire directory is deleted by "make distclean".</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1147 <!--#include file="footer.html" -->