annotate www/code.html @ 984:422696039640

ls --color should depend on LS in menuconfig.
author Rob Landley <rob@landley.net>
date Thu, 01 Aug 2013 18:10:47 -0500
parents 786841fdb1e0
children 27275d0d97e9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1 <!--#include file="header.html" -->
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
2
529
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
3 <p><h1>Code style</h1></p>
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
4
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
5 <p>The primary goal of toybox is _simple_ code. Keeping the code small is
529
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
6 second, with speed and lots of features coming in somewhere after that.
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
7 (For more on that, see the <a href=design.html>design</a> page.)</p>
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
8
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
9 <p>A simple implementation usually takes up fewer lines of source code,
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
10 meaning more code can fit on the screen at once, meaning the programmer can
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
11 see more of it on the screen and thus keep more if in their head at once.
529
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
12 This helps code auditing and thus reduces bugs. That said, sometimes being
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
13 more explicit is preferable to being clever enough to outsmart yourself:
b93517f238d1 Web page updates.
Rob Landley <rob@landley.net>
parents: 505
diff changeset
14 don't be so terse your code is unreadable.</p>
217
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
15
694
786841fdb1e0 Reindent to two spaces per level. Remove vi: directives that haven't worked right in years (ubuntu broke its' vim implementation). Remove trailing spaces. Add/remove blank lines. Re-wordwrap in places. Update documentation with new coding style.
Rob Landley <rob@landley.net>
parents: 677
diff changeset
16 <p>Toybox source uses two spaces per indentation level, and wraps at 80
786841fdb1e0 Reindent to two spaces per level. Remove vi: directives that haven't worked right in years (ubuntu broke its' vim implementation). Remove trailing spaces. Add/remove blank lines. Re-wordwrap in places. Update documentation with new coding style.
Rob Landley <rob@landley.net>
parents: 677
diff changeset
17 columns.</p>
217
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
18
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
19 <p>Gotos are allowed for error handling, and for breaking out of
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
20 nested loops. In general, a goto should only jump forward (not back), and
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
21 should either jump to the end of an outer loop, or to error handling code
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
22 at the end of the function. Goto labels are never indented: they override the
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
23 block structure of the file. Putting them at the left edge makes them easy
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
24 to spot as overrides to the normal flow of control, which they are.</p>
ca48a878255d Brief note about code style.
Rob Landley <rob@landley.net>
parents: 213
diff changeset
25
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
26 <p><h1>Building Toybox:</h1></p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
27
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
28 <p>Toybox is configured using the Kconfig language pioneered by the Linux
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
29 kernel, and adopted by many other projects (uClibc, OpenEmbedded, etc).
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
30 This generates a ".config" file containing the selected options, which
694
786841fdb1e0 Reindent to two spaces per level. Remove vi: directives that haven't worked right in years (ubuntu broke its' vim implementation). Remove trailing spaces. Add/remove blank lines. Re-wordwrap in places. Update documentation with new coding style.
Rob Landley <rob@landley.net>
parents: 677
diff changeset
31 controls which features are included when compiling toybox.</p>
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
32
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
33 <p>Each configuration option has a default value. The defaults indicate the
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
34 "maximum sane configuration", I.E. if the feature defaults to "n" then it
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
35 either isn't complete or is a special-purpose option (such as debugging
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
36 code) that isn't intended for general purpose use.</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
37
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
38 <p>The standard build invocation is:</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
39
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
40 <ul>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
41 <li>make defconfig #(or menuconfig)</li>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
42 <li>make</li>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
43 <li>make install</li>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
44 </ul>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
45
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
46 <p>Type "make help" to see all available build options.</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
47
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
48 <p>The file "configure" contains a number of environment variable definitions
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
49 which influence the build, such as specifying which compiler to use or where
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
50 to install the resulting binaries. This file is included by the build, but
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
51 accepts existing definitions of the environment variables, so it may be sourced
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
52 or modified by the developer before building and the definitions exported
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
53 to the environment will take precedence.</p>
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
54
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
55 <p>(To clarify: "configure" describes the build and installation environment,
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
56 ".config" lists the features selected by defconfig/menuconfig.)</p>
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
57
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
58 <p><h1>Infrastructure:</h1></p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
59
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
60 <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
61 <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
62 <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
63 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
64 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
65 <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
66 multiple commands:</li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
67 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
68 <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
69 <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
70 <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
71 <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
72 </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
73 <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
74 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
75 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
76 <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
77 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
78 <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
79 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
80 <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
81 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
82 </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
83
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
84 <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
85 <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
86 <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
87 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
88 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
89 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
90 <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
91
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
92 <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
93 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
94 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
95 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
96
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
97 <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
98 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
99 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
100 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
101 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
102 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
103 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
104 (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
105 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
106
4f1ca01db000 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>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
108
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
109 <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
110 <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
111 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
112 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
113
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
114 <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
115 "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
116
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
117 <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
118 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
119
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
120 <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
121 (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
122 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
123
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
124 <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
125 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
126 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
127
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
128 <ol>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
129 <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
130 <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
131 <li><p>a bitfield of TOYFLAG values
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
132 (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
133 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
134 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
135 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
136 </ol>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
137 </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
138
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
139 <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
140 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
141 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
142 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
143 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
144 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
145 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
146 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
147 "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
148
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
149 <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
150 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
151 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
152 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
153 options when producing generated/help.h.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
154 </li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
155
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
156 <li><p>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
157 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
158 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
159 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
160 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
161
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
162 <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
163 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
164
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
165 <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
166 <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
167 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
168 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
169 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
170 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
171 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
172 (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
173
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
174 <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
175 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
176 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
177 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
178 <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
179 </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
180
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents: 217
diff changeset
181 <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
182
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
183 <p>This directory contains global infrastructure.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
184
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
185 <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
186 <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
187 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
188 specific to this command.</p>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
189
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
190 <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
191 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
192 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
193 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
194 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
195 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
196 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
197
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
198 <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
199 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
200 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
201
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
202 <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
203 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
204 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
205 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
206 local variables.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
207
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
208 <h3>main.c</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
209 <p>Contains the main() function where execution starts, plus
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
210 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
211 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
212 only command defined outside of the toys directory.)</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
213
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
214 <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
215 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
216 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
217 toy_list[] (via toys.which->toy_main()).
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
218 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
219 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
220 directory.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
221
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
222 <p>The following global variables are defined in main.c:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
223 <ul>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
224 <a name="toy_list" />
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
225 <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
226 commands currently configured into toybox. The first entry (toy_list[0]) is
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
227 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
228 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
229 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
230 The remaining entries are the commands in alphabetical order (for efficient
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
231 binary search).</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
232
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
233 <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
234 defining macros and #including generated/newtoys.h.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
235
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
236 <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
237 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
238 <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
239 <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
240 command.</p></li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
241 <li><p>char *<b>options</b> - command line option string (used by
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
242 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
243 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
244 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
245 <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
246
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
247 <ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
248 <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
249 <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
250 <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
251 <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
252 <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
253 <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
254 <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
255 </ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
256 <br>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
257
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
258 <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
259 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
260 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
261 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
262
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
263 <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
264 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
265 Members of this structure include:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
266 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
267 <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
268 structure. Mostly used to grab the name of the running command
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
269 (toys->which.name).</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
270 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
271 <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
272 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
273 return this value.</p></li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
274 <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
275 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
276 "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
277 entry indicates the end of the array.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
278 <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
279 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
280 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
281 <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
282 <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
283 toys->which.options occurred this time.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
284
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
285 <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
286 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
287 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
288 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
289 "-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
290
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
291 <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
292 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
293 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
294 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
295
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
296 <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
297 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
298 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
299 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
300 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
301
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
302 <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
303
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
304 </li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
305 <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
306 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
307 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
308 name.</p></li>
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
309 <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
310 optargs[].<p></li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
311 <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
312 via help_main() before exiting. (True during option parsing, defaults to
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
313 false afterwards.)</p></li>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
314 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
315
674
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
316 <a name="toy_union" />
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
317 <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
318 command's global variables.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
319
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
320 <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
321 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
322 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
323 can also initialize global variables with its results.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
324
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
325 <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
326 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
327 running would be wasteful.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
328
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
329 <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
330 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
331 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
332 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
333 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
334 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
335 #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
336 "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
337
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
338 <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
339 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
340 declare global variables outside of this, because such global variables would
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
341 allocate memory when running other commands that don't use those global
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
342 variables.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
343
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
344 <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
345 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
346 the get_optargs() description in lib/args.c for details.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
347 </li>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
348
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
349 <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
350 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
351 and it should never be directly referenced by functions in lib/ (although
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
352 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
353 </ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
354
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
355 <p>The following functions are defined in main.c:</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
356 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
357 <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
358 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
359 <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
360 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
361 <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
362 arguments.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
363 <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
364 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
365 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
366
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
367 <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
368 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
369 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
370 never match an internal command.</li>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
371
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
372 <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
373 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
374 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
375 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
376 install path prepended.</p></li>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
377
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
378 </ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
379
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
380 <h3>Config.in</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
381
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
382 <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
383 <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
384
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
385 <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
386 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
387 scripts/config2help.py to create generated/help.h.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
388
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
389 <h3>Temporary files:</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
390
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
391 <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
392 <ul>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
393 <li><p><b>.config</b> - Configuration file generated by kconfig, indicating
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
394 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
395 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
396
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
397 <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
398 <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
399 instructions</a>.</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
400 </li>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
401 </ul>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
402
505
c08cd17224c0 Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents: 501
diff changeset
403 <a name="generated" />
256
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
404 <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
405 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
406 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
407 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
408 system).</p>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
409
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
410 <ul>
20f1e3da0492 Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents: 239
diff changeset
411 <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
412 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
413
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
414 <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
415 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
416 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
417 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
418 cluttering the code with #ifdefs or leading to configuration dependent build
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
419 breaks. (See the 1992 Usenix paper
415
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
420 <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
421 Considered Harmful</a> for more information.)</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
422
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
423 <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
424 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
425 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
426 eliminated by a simple test on CFG_SYMBOL. Note that
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
427 (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
428 still result in configuration dependent build breaks. Use with caution.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
429 </li>
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
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
432 <p><h2>Directory toys/</h2></p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
433
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
434 <h3>toys/Config.in</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
435
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
436 <p>Included from the top level Config.in, contains one or more
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
437 configuration entries for each command.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
438
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
439 <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
440 configuration symbols are uppercase and command names are lower case).
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
441 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
442 the option name. Global options are attached to the "toybox" command,
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
443 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
444 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
445 .config.</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
446
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
447 <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
448 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
449 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
450 have config symbols they're options (symbols with an underscore and suffix)
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
451 to the NEWTOY() name. (See toys/toylist.h)</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
452
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
453 <h3>toys/toylist.h</h3>
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
454 <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
455 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
456 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
457 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
458 prototypes).</p>
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
459
213
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
460 <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
461 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
462 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
463 are enabled wind up in the list.</p>
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
464
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
465 <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
466 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
467
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
468
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
469 <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
470 prototypes.
db91356e3c43 More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents: 210
diff changeset
471 This
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
472 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
473 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
474 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
475
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
476 <h3>toys/help.h</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
477
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
478 <p>#defines two help text strings for each command: a single line
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
479 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
480 in toys/help.c to display help for commands.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
481
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
482 <p>Although this file is generated from Config.in help entries by
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
483 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
484 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
485 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
486
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
487 <p>This file contains help for all commands, regardless of current
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
488 configuration, but only the currently enabled ones are entered into help_data[]
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
489 in toys/help.c.</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
490
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
491 <a name="lib">
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
492 <h2>Directory lib/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
493
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
494 <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
495
625
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
496 <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
497 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
498 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
499
536
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
500 <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
501
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
502 <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
503 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
504 operating systems, etc).</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
505
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
506 <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
507
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
508 <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
509 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
510 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
511 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
512
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents: 529
diff changeset
513 <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
514 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
515 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
516 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
517
625
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
518 <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
519
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
520 <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
521 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
522
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
523 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
524 <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
525 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
526 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
527 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
528
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
529 <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
530 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
531 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
532 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
533 length array.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
534 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
535
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
536 <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
537 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
538 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
539 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
540 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
541
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
542 <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
543 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
544 <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
545 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
546 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
547
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
548 <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
549 (<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
550
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
551 <li><p><b>struct 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
552 *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
553 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
554
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
555 <b>List Functions</b>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
556
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
557 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
558 <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
559 <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
560 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
561 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
562
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
563 <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
564 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
565
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
566 <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
567 - 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
568 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
569 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
570 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
571 new node.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
572 <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
573 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
574 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
575 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
576
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
577 <b>Trivia questions:</b>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
578
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
579 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
580 <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
581 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
582 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
583 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
584 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
585 </li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
586
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
587 <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
588 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
589 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
590
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
591 <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
592 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
593 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
594 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
595 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
596 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
597 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
598 that case.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
599
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
600 <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
601 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
602 <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
603 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
604
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
605 <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
606
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
607 <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
608 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
609 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
610
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
611 <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
612 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
613 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
614 ("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
615 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
616 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
617 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
618 parsed are retained unmodified in toys.argv[].</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
619
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
620 <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
621 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
622 Toybox does not use the getopt()
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
623 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
624 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
625 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
626 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
627 as normal options).</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
628
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
629 <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
630 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
631 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
632 If a command has no option
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
633 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
634 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
635 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
636 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
637 --gc-sections option.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
638
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
639 <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
640 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
641 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
642 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
643 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
644 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
645
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
646 <h4>Optflags format string</h4>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
647
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
648 <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
649 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
650
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
651 <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
652 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
653
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
654 <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
655 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
656 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
657 "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
658 available to command_main():
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
659
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
660 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
661 <li><p>In <b>struct toys</b>:
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
662 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
663 <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
664 <li>toys.optargs[0] = "walrus"; // leftover argument</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
665 <li>toys.optargs[1] = NULL; // end of list</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
666 <li>toys.optc=1; // there was 1 leftover argument</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
667 <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
668 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
669 <p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
670
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
671 <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
672 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
673 <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
674 <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
675 <li>this[2] = 42; // argument to -a</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
676 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
677 </p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
678 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
679
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
680 <p>If the command's globals are:</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
681
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
682 <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
683 GLOBALS(
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
684 char *c;
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
685 char *b;
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
686 long a;
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
687 )
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
688 </pre></blockquote>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
689 <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
690 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
691 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
692 top to bottom in GLOBALS().</p>
403
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><b>long toys.optflags</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
695
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
696 <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
697 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
698 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
699 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
700
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
701 <p>For example,
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
702 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
703 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
704 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
705
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
706 <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
707 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
708 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
709
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
710 <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
711 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
712 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
713 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
714 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
715
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
716 <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
717
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
718 <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
719 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
720
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
721 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
722 <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
723 <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
724 <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
725 <li><b>#</b> - plus a signed long argument.
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
726 <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
727 <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
728 <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
729 <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
730 <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
731 </ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
732 <ul><li>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
733 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
734 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
735 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
736 this by using the USE_BLAH() macros with C string concatenation, ala:
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
737 "abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</li></ul>
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
738 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
739
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
740 <p>Arguments may occur with or without a space (I.E. "-a 42" or "-a42").
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
741 The command line argument "-abc" may be interepreted many different ways:
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
742 the optflags string "cba" sets toys.optflags = 7, "c:ba" sets toys.optflags=4
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
743 and saves "ba" as the argument to -c, and "cb:a" sets optflags to 6 and saves
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
744 "c" as the argument to -b.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
745
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
746 <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
747 union "this" (see generated/globals.h), treating it as an array of longs
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
748 with the rightmost saved in this[0]. Again using "a*b:c#d", "-c 42" would set
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
749 this[0]=42; and "-b 42" would set this[1]="42"; each slot is left NULL if
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
750 the corresponding argument is not encountered.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
751
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
752 <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
753 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
754 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
755 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
756 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
757
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
758 <p><b>char *toys.optargs[]</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
759
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
760 <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
761 (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
762 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
763 (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
764 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
765 terminated by a NULL entry.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
766
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
767 <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
768 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
769 start of the optflags string.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
770
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
771 <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
772 arguments in optargs. The "--" itself is consumed.</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
773
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
774 <p><b>Other optflags control characters</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>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
777 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
778
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
779 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
780 <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
781 <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
782 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
783 <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
784 <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
785 <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
786 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
787
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
788 <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
789 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
790 (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
791 optflag, but letters are never control characters.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
792
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
793 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
794 <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
795 <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
796 <li><b>+X</b> enabling this option also enables option X (switch bit on).</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
797 <li><b>~X</b> enabling this option disables option X (switch bit off).</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
798 <li><b>!X</b> this option cannot be used in combination with X (die with error).</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
799 <li><b>[yz]</b> this option requires at least one of y or z to also be enabled.</li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
800 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
801
415
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
802 <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
803
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
804 <ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
805 <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
806 <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
807 <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
808 </ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
809
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
810 <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
811 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
812 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
813 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
814 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
815
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents: 403
diff changeset
816 <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
817
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
818 <p><b>--longopts</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
819
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
820 <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
821 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
822 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
823 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
824
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
825 <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
826 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
827 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
828 --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
829 and would assign this[1] = 42;</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
830
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
831 <p>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
832 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
833 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
834
625
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
835 <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
836
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
837 <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
838 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
839 of functions.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
840
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
841 <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
842 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
843 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
844 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
845 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
846
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
847 <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
848
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
849 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
850 <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
851 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
852 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
853
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
854 <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
855 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
856 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
857 of string.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
858
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
859 <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
860 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
861 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
862
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
863 <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
864 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
865 <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
866 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
867 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
868 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
869 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
870 snapshot tree.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
871
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
872 <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
873 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
874 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
875
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
876 <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
877
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
878 <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
879 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
880 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
881
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
882 <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
883 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
884 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
885 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
886 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
887 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
888
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
889 <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
890 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
891 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
892 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
893 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
894 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
895 arbitrary struct.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
896
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
897 <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
898 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
899
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
900 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
901 <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
902 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
903 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
904 memory.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
905 <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
906 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
907 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
908 <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
909 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
910 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
911 <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
912 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
913 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
914 <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
915 <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
916 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
917 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
918 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
919 them.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
920 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
921
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
922 <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
923 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
924
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
925 <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
926 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
927 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
928 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
929 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
930 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
931 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
932
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
933 <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
934 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
935 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
936
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
937 <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
938 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
939 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
940 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
941 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
942 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
943
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
944 <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
945 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
946 <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
947 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
948 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
949 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
950 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
951
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents: 536
diff changeset
952 <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
953 <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
954 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
955 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
956 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
957
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
958 <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
959 <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
960
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
961 <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
962 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
963 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
964 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
965
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
966 <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
967 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
968 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
969 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
970 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
971 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
972
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
973 <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
974 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
975 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
976
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate.
Rob Landley <rob@landley.net>
parents: 625
diff changeset
977 <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
978 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
979
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
980 <h2>Directory scripts/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
981
677
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
982 <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
983 and scripts/install.sh for "make install".</p>
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
984
43c4f709b9ff Doc tweak about test suite.
Rob Landley <rob@landley.net>
parents: 674
diff changeset
985 <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
986 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
987 "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
988 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
989
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
990 <h3>scripts/cfg2files.sh</h3>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
991
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
992 <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
993 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
994 Makefile.
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
995 </p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
996
210
a71c502a028c Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents: 200
diff changeset
997 <h2>Directory kconfig/</h2>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
998
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
999 <p>Menuconfig infrastructure copied from the Linux kernel. See the
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1000 Linux kernel's Documentation/kbuild/kconfig-language.txt</p>
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1001
403
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1002 <a name="generated">
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1003 <h2>Directory generated/</h2>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1004
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1005 <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
1006 build. (See scripts/make.sh)</p>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1007
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1008 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1009 <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
1010
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1011 <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
1012
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1013 <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
1014 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
1015 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
1016
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1017 <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
1018 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
1019 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
1020 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
1021 calling it.</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1022 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1023
f6ffc6685a9e Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents: 256
diff changeset
1024 <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
1025 else. The entire directory is deleted by "make distclean".</p>
200
f868f933bd3b Update web pages.
Rob Landley <rob@landley.net>
parents:
diff changeset
1026 <!--#include file="footer.html" -->