annotate www/code.html @ 1215:4eaac3e63fa7 draft

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