diff options
Diffstat (limited to 'docs')
46 files changed, 6802 insertions, 0 deletions
diff --git a/docs/autodocifier.pl b/docs/autodocifier.pl new file mode 100755 index 000000000..3aa838eb4 --- /dev/null +++ b/docs/autodocifier.pl | |||
| @@ -0,0 +1,304 @@ | |||
| 1 | #!/usr/bin/perl -w | ||
| 2 | |||
| 3 | use strict; | ||
| 4 | use Getopt::Long; | ||
| 5 | |||
| 6 | # collect lines continued with a '\' into an array | ||
| 7 | sub continuation { | ||
| 8 | my $fh = shift; | ||
| 9 | my @line; | ||
| 10 | |||
| 11 | while (<$fh>) { | ||
| 12 | my $s = $_; | ||
| 13 | $s =~ s/\\\s*$//; | ||
| 14 | #$s =~ s/#.*$//; | ||
| 15 | push @line, $s; | ||
| 16 | last unless (/\\\s*$/); | ||
| 17 | } | ||
| 18 | return @line; | ||
| 19 | } | ||
| 20 | |||
| 21 | # regex && eval away unwanted strings from documentation | ||
| 22 | sub beautify { | ||
| 23 | my $text = shift; | ||
| 24 | for (;;) { | ||
| 25 | my $text2 = $text; | ||
| 26 | $text =~ s/SKIP_\w+\(.*?"\s*\)//sxg; | ||
| 27 | $text =~ s/USE_\w+\(\s*?(.*?)"\s*\)/$1"/sxg; | ||
| 28 | $text =~ s/USAGE_\w+\(\s*?(.*?)"\s*\)/$1"/sxg; | ||
| 29 | last if ( $text2 eq $text ); | ||
| 30 | } | ||
| 31 | $text =~ s/"\s*"//sg; | ||
| 32 | my @line = split("\n", $text); | ||
| 33 | $text = join('', | ||
| 34 | map { | ||
| 35 | s/^\s*"//; | ||
| 36 | s/"\s*$//; | ||
| 37 | s/%/%%/g; | ||
| 38 | s/\$/\\\$/g; | ||
| 39 | eval qq[ sprintf(qq{$_}) ] | ||
| 40 | } @line | ||
| 41 | ); | ||
| 42 | return $text; | ||
| 43 | } | ||
| 44 | |||
| 45 | # generate POD for an applet | ||
| 46 | sub pod_for_usage { | ||
| 47 | my $name = shift; | ||
| 48 | my $usage = shift; | ||
| 49 | |||
| 50 | # Sigh. Fixup the known odd-name applets. | ||
| 51 | $name =~ s/dpkg_deb/dpkg-deb/g; | ||
| 52 | $name =~ s/fsck_minix/fsck.minix/g; | ||
| 53 | $name =~ s/mkfs_minix/mkfs.minix/g; | ||
| 54 | $name =~ s/run_parts/run-parts/g; | ||
| 55 | $name =~ s/start_stop_daemon/start-stop-daemon/g; | ||
| 56 | |||
| 57 | # make options bold | ||
| 58 | my $trivial = $usage->{trivial}; | ||
| 59 | if (!defined $usage->{trivial}) { | ||
| 60 | $trivial = ""; | ||
| 61 | } else { | ||
| 62 | $trivial =~ s/(?<!\w)(-\w+)/B<$1>/sxg; | ||
| 63 | } | ||
| 64 | my @f0 = | ||
| 65 | map { $_ !~ /^\s/ && s/(?<!\w)(-\w+)/B<$1>/g; $_ } | ||
| 66 | split("\n", (defined $usage->{full} ? $usage->{full} : "")); | ||
| 67 | |||
| 68 | # add "\n" prior to certain lines to make indented | ||
| 69 | # lines look right | ||
| 70 | my @f1; | ||
| 71 | my $len = @f0; | ||
| 72 | for (my $i = 0; $i < $len; $i++) { | ||
| 73 | push @f1, $f0[$i]; | ||
| 74 | if (($i+1) != $len && $f0[$i] !~ /^\s/ && $f0[$i+1] =~ /^\s/) { | ||
| 75 | next if ($f0[$i] =~ /^$/); | ||
| 76 | push(@f1, "") unless ($f0[$i+1] =~ /^\s*$/s); | ||
| 77 | } | ||
| 78 | } | ||
| 79 | my $full = join("\n", @f1); | ||
| 80 | |||
| 81 | # prepare notes if they exist | ||
| 82 | my $notes = (defined $usage->{notes}) | ||
| 83 | ? "$usage->{notes}\n\n" | ||
| 84 | : ""; | ||
| 85 | |||
| 86 | # prepare examples if they exist | ||
| 87 | my $example = (defined $usage->{example}) | ||
| 88 | ? | ||
| 89 | "Example:\n\n" . | ||
| 90 | join ("\n", | ||
| 91 | map { "\t$_" } | ||
| 92 | split("\n", $usage->{example})) . "\n\n" | ||
| 93 | : ""; | ||
| 94 | |||
| 95 | # Pad the name so that the applet name gets a line | ||
| 96 | # by itself in BusyBox.txt | ||
| 97 | my $spaces = 10 - length($name); | ||
| 98 | if ($spaces > 0) { | ||
| 99 | $name .= " " x $spaces; | ||
| 100 | } | ||
| 101 | |||
| 102 | return | ||
| 103 | "=item B<$name>". | ||
| 104 | "\n\n$name $trivial\n\n". | ||
| 105 | "$full\n\n" . | ||
| 106 | "$notes" . | ||
| 107 | "$example" . | ||
| 108 | "\n\n" | ||
| 109 | ; | ||
| 110 | } | ||
| 111 | |||
| 112 | # the keys are applet names, and | ||
| 113 | # the values will contain hashrefs of the form: | ||
| 114 | # | ||
| 115 | # { | ||
| 116 | # trivial => "...", | ||
| 117 | # full => "...", | ||
| 118 | # notes => "...", | ||
| 119 | # example => "...", | ||
| 120 | # } | ||
| 121 | my %docs; | ||
| 122 | |||
| 123 | |||
| 124 | # get command-line options | ||
| 125 | |||
| 126 | my %opt; | ||
| 127 | |||
| 128 | GetOptions( | ||
| 129 | \%opt, | ||
| 130 | "help|h", | ||
| 131 | "pod|p", | ||
| 132 | "verbose|v", | ||
| 133 | ); | ||
| 134 | |||
| 135 | if (defined $opt{help}) { | ||
| 136 | |||
| 137 | "$0 [OPTION]... [FILE]...\n", | ||
| 138 | "\t--help\n", | ||
| 139 | "\t--pod\n", | ||
| 140 | "\t--verbose\n", | ||
| 141 | ; | ||
| 142 | exit 1; | ||
| 143 | } | ||
| 144 | |||
| 145 | |||
| 146 | # collect documenation into %docs | ||
| 147 | |||
| 148 | foreach (@ARGV) { | ||
| 149 | open(USAGE, $_) || die("$0: $_: $!"); | ||
| 150 | my $fh = *USAGE; | ||
| 151 | my ($applet, $type, @line); | ||
| 152 | while (<$fh>) { | ||
| 153 | if (/^#define (\w+)_(\w+)_usage/) { | ||
| 154 | $applet = $1; | ||
| 155 | $type = $2; | ||
| 156 | @line = continuation($fh); | ||
| 157 | my $doc = $docs{$applet} ||= { }; | ||
| 158 | my $text = join("\n", @line); | ||
| 159 | $doc->{$type} = beautify($text); | ||
| 160 | } | ||
| 161 | } | ||
| 162 | } | ||
| 163 | |||
| 164 | |||
| 165 | # generate structured documentation | ||
| 166 | |||
| 167 | my $generator = \&pod_for_usage; | ||
| 168 | |||
| 169 | my @names = sort keys %docs; | ||
| 170 | my $line = "\t[, [[, "; | ||
| 171 | for (my $i = 0; $i < $#names; $i++) { | ||
| 172 | if (length ($line.$names[$i]) >= 65) { | ||
| 173 | print "$line\n\t"; | ||
| 174 | $line = ""; | ||
| 175 | } | ||
| 176 | $line .= "$names[$i], "; | ||
| 177 | } | ||
| 178 | print $line . $names[-1]; | ||
| 179 | |||
| 180 | print "\n\n=head1 COMMAND DESCRIPTIONS\n"; | ||
| 181 | print "\n=over 4\n\n"; | ||
| 182 | |||
| 183 | foreach my $applet (@names) { | ||
| 184 | print $generator->($applet, $docs{$applet}); | ||
| 185 | } | ||
| 186 | |||
| 187 | exit 0; | ||
| 188 | |||
| 189 | __END__ | ||
| 190 | |||
| 191 | =head1 NAME | ||
| 192 | |||
| 193 | autodocifier.pl - generate docs for busybox based on usage.h | ||
| 194 | |||
| 195 | =head1 SYNOPSIS | ||
| 196 | |||
| 197 | autodocifier.pl [OPTION]... [FILE]... | ||
| 198 | |||
| 199 | Example: | ||
| 200 | |||
| 201 | ( cat docs/busybox_header.pod; \ | ||
| 202 | docs/autodocifier.pl usage.h; \ | ||
| 203 | cat docs/busybox_footer.pod ) > docs/busybox.pod | ||
| 204 | |||
| 205 | =head1 DESCRIPTION | ||
| 206 | |||
| 207 | The purpose of this script is to automagically generate | ||
| 208 | documentation for busybox using its usage.h as the original source | ||
| 209 | for content. It used to be that same content has to be duplicated | ||
| 210 | in 3 places in slightly different formats -- F<usage.h>, | ||
| 211 | F<docs/busybox.pod>. This was tedious and error-prone, so it was | ||
| 212 | decided that F<usage.h> would contain all the text in a | ||
| 213 | machine-readable form, and scripts could be used to transform this | ||
| 214 | text into other forms if necessary. | ||
| 215 | |||
| 216 | F<autodocifier.pl> is one such script. It is based on a script by | ||
| 217 | Erik Andersen <andersen@codepoet.org> which was in turn based on a | ||
| 218 | script by Mark Whitley <markw@codepoet.org> | ||
| 219 | |||
| 220 | =head1 OPTIONS | ||
| 221 | |||
| 222 | =over 4 | ||
| 223 | |||
| 224 | =item B<--help> | ||
| 225 | |||
| 226 | This displays the help message. | ||
| 227 | |||
| 228 | =item B<--pod> | ||
| 229 | |||
| 230 | Generate POD (this is the default) | ||
| 231 | |||
| 232 | =item B<--verbose> | ||
| 233 | |||
| 234 | Be verbose (not implemented) | ||
| 235 | |||
| 236 | =back | ||
| 237 | |||
| 238 | =head1 FORMAT | ||
| 239 | |||
| 240 | The following is an example of some data this script might parse. | ||
| 241 | |||
| 242 | #define length_trivial_usage \ | ||
| 243 | "STRING" | ||
| 244 | #define length_full_usage \ | ||
| 245 | "Prints out the length of the specified STRING." | ||
| 246 | #define length_example_usage \ | ||
| 247 | "$ length Hello\n" \ | ||
| 248 | "5\n" | ||
| 249 | |||
| 250 | Each entry is a cpp macro that defines a string. The macros are | ||
| 251 | named systematically in the form: | ||
| 252 | |||
| 253 | $name_$type_usage | ||
| 254 | |||
| 255 | $name is the name of the applet. $type can be "trivial", "full", "notes", | ||
| 256 | or "example". Every documentation macro must end with "_usage". | ||
| 257 | |||
| 258 | The definition of the types is as follows: | ||
| 259 | |||
| 260 | =over 4 | ||
| 261 | |||
| 262 | =item B<trivial> | ||
| 263 | |||
| 264 | This should be a brief, one-line description of parameters that | ||
| 265 | the command expects. This will be displayed when B<-h> is issued to | ||
| 266 | a command. I<REQUIRED> | ||
| 267 | |||
| 268 | =item B<full> | ||
| 269 | |||
| 270 | This should contain descriptions of each option. This will also | ||
| 271 | be displayed along with the trivial help if CONFIG_FEATURE_TRIVIAL_HELP | ||
| 272 | is disabled. I<REQUIRED> | ||
| 273 | |||
| 274 | =item B<notes> | ||
| 275 | |||
| 276 | This is documentation that is intended to go in the POD or SGML, but | ||
| 277 | not be printed when a B<-h> is given to a command. To see an example | ||
| 278 | of notes being used, see init_notes_usage in F<usage.h>. I<OPTIONAL> | ||
| 279 | |||
| 280 | =item B<example> | ||
| 281 | |||
| 282 | This should be an example of how the command is actually used. | ||
| 283 | This will not be printed when a B<-h> is given to a command -- it | ||
| 284 | will only be included in the POD or SGML documentation. I<OPTIONAL> | ||
| 285 | |||
| 286 | =back | ||
| 287 | |||
| 288 | =head1 FILES | ||
| 289 | |||
| 290 | F<usage.h> | ||
| 291 | |||
| 292 | =head1 COPYRIGHT | ||
| 293 | |||
| 294 | Copyright (c) 2001 John BEPPU. All rights reserved. This program is | ||
| 295 | free software; you can redistribute it and/or modify it under the same | ||
| 296 | terms as Perl itself. | ||
| 297 | |||
| 298 | =head1 AUTHOR | ||
| 299 | |||
| 300 | John BEPPU <b@ax9.org> | ||
| 301 | |||
| 302 | =cut | ||
| 303 | |||
| 304 | # $Id: autodocifier.pl,v 1.26 2004/04/06 15:26:25 andersen Exp $ | ||
diff --git a/docs/busybox.net/FAQ.html b/docs/busybox.net/FAQ.html new file mode 100644 index 000000000..c751f7521 --- /dev/null +++ b/docs/busybox.net/FAQ.html | |||
| @@ -0,0 +1,1108 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | <h3>Frequently Asked Questions</h3> | ||
| 4 | |||
| 5 | This is a collection of some of the more frequently asked questions | ||
| 6 | about BusyBox. Some of the questions even have answers. If you | ||
| 7 | have additions to this FAQ document, we would love to add them, | ||
| 8 | |||
| 9 | <h2>General questions</h2> | ||
| 10 | <ol> | ||
| 11 | <li><a href="#getting_started">How can I get started using BusyBox?</a></li> | ||
| 12 | <li><a href="#configure">How do I configure busybox?</a></li> | ||
| 13 | <li><a href="#build_system">How do I build a BusyBox-based system?</a></li> | ||
| 14 | <li><a href="#kernel">Which Linux kernel versions are supported?</a></li> | ||
| 15 | <li><a href="#arch">Which architectures does BusyBox run on?</a></li> | ||
| 16 | <li><a href="#libc">Which C libraries are supported?</a></li> | ||
| 17 | <li><a href="#commercial">Can I include BusyBox as part of the software on my device?</a></li> | ||
| 18 | <li><a href="#external">Where can I find other small utilities since busybox does not include the features I want?</a></li></li> | ||
| 19 | <li><a href="#demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a></li> | ||
| 20 | <li><a href="#helpme">I need help with BusyBox! What should I do?</a></li> | ||
| 21 | <li><a href="#contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a></li> | ||
| 22 | </ol> | ||
| 23 | |||
| 24 | <h2>Troubleshooting</h2> | ||
| 25 | <ol> | ||
| 26 | <li><a href="#bugs">I think I found a bug in BusyBox! What should I do?!</a></li> | ||
| 27 | <li><a href="#backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</a></li> | ||
| 28 | <li><a href="#init">Busybox init isn't working!</a></li> | ||
| 29 | <li><a href="#sed">I can't configure busybox on my system.</a></li> | ||
| 30 | <li><a href="#job_control">Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?</a></li> | ||
| 31 | </ol> | ||
| 32 | |||
| 33 | <h2>Programming questions</h2> | ||
| 34 | <ol> | ||
| 35 | <li><a href="#goals">What are the goals of busybox?</a></li> | ||
| 36 | <li><a href="#design">What is the design of busybox?</a></li> | ||
| 37 | <li><a href="#source">How is the source code organized?</a></li> | ||
| 38 | <ul> | ||
| 39 | <li><a href="#source_applets">The applet directories.</a></li> | ||
| 40 | <li><a href="#source_libbb">The busybox shared library (libbb)</a></li> | ||
| 41 | </ul> | ||
| 42 | <li><a href="#optimize">I want to make busybox even smaller, how do I go about it?</a></li> | ||
| 43 | <li><a href="#adding">Adding an applet to busybox</a></li> | ||
| 44 | <li><a href="#standards">What standards does busybox adhere to?</a></li> | ||
| 45 | <li><a href="#portability">Portability.</a></li> | ||
| 46 | <li><a href="#tips">Tips and tricks.</a></li> | ||
| 47 | <ul> | ||
| 48 | <li><a href="#tips_encrypted_passwords">Encrypted Passwords</a></li> | ||
| 49 | <li><a href="#tips_vfork">Fork and vfork</a></li> | ||
| 50 | <li><a href="#tips_short_read">Short reads and writes</a></li> | ||
| 51 | <li><a href="#tips_memory">Memory used by relocatable code, PIC, and static linking.</a></li> | ||
| 52 | <li><a href="#tips_kernel_headers">Including Linux kernel headers.</a></li> | ||
| 53 | </ul> | ||
| 54 | <li><a href="#who">Who are the BusyBox developers?</a></li> | ||
| 55 | </ul> | ||
| 56 | |||
| 57 | |||
| 58 | </ol> | ||
| 59 | |||
| 60 | <h1>General questions</h1> | ||
| 61 | |||
| 62 | <hr /> | ||
| 63 | <p> | ||
| 64 | <h2><a name="getting_started">How can I get started using BusyBox?</a></h2> | ||
| 65 | <p> If you just want to try out busybox without installing it, download the | ||
| 66 | tarball, extract it, run "make defconfig", and then run "make". | ||
| 67 | </p> | ||
| 68 | <p> | ||
| 69 | This will create a busybox binary with almost all features enabled. To try | ||
| 70 | out a busybox applet, type "./busybox [appletname] [options]", for | ||
| 71 | example "./busybox ls -l" or "./busybox cat LICENSE". Type "./busybox" | ||
| 72 | to see a command list, and "busybox appletname --help" to see a brief | ||
| 73 | usage message for a given applet. | ||
| 74 | </p> | ||
| 75 | <p> | ||
| 76 | BusyBox uses the name it was invoked under to determine which applet is | ||
| 77 | being invoked. (Try "mv busybox ls" and then "./ls -l".) Installing | ||
| 78 | busybox consists of creating symlinks (or hardlinks) to the busybox | ||
| 79 | binary for each applet in busybox, and making sure these links are in | ||
| 80 | the shell's command $PATH. The special applet name "busybox" (or with | ||
| 81 | any optional suffix, such as "busybox-static") uses the first argument | ||
| 82 | to determine which applet to run, as shown above. | ||
| 83 | </p> | ||
| 84 | <p> | ||
| 85 | BusyBox also has a feature called the | ||
| 86 | <a name="standalone_shell">"standalone shell"</a>, where the busybox | ||
| 87 | shell runs any built-in applets before checking the command path. This | ||
| 88 | feature is also enabled by "make allyesconfig", and to try it out run | ||
| 89 | the command line "PATH= ./busybox ash". This will blank your command path | ||
| 90 | and run busybox as your command shell, so the only commands it can find | ||
| 91 | (without an explicit path such as /bin/ls) are the built-in busybox ones. | ||
| 92 | This is another good way to see what's built into busybox. | ||
| 93 | Note that the standalone shell requires CONFIG_BUSYBOX_EXEC_PATH | ||
| 94 | to be set appropriately, depending on whether or not /proc/self/exe is | ||
| 95 | available or not. If you do not have /proc, then point that config option | ||
| 96 | to the location of your busybox binary, usually /bin/busybox. | ||
| 97 | (So if you set it to /proc/self/exe, and happen to be able to chroot into | ||
| 98 | your rootfs, you must mount /proc beforehand.) | ||
| 99 | </p> | ||
| 100 | <p> | ||
| 101 | A typical indication that you set CONFIG_BUSYBOX_EXEC_PATH to proc but | ||
| 102 | forgot to mount proc is: | ||
| 103 | <pre> | ||
| 104 | $ /bin/echo $PATH | ||
| 105 | /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11 | ||
| 106 | $ echo $PATH | ||
| 107 | /bin/sh: echo: not found | ||
| 108 | </pre> | ||
| 109 | <hr /> | ||
| 110 | <p> | ||
| 111 | <h2><a name="configure">How do I configure busybox?</a></h2> | ||
| 112 | <p> Busybox is configured similarly to the linux kernel. Create a default | ||
| 113 | configuration and then run "make menuconfig" to modify it. The end | ||
| 114 | result is a .config file that tells the busybox build process what features | ||
| 115 | to include. So instead of "./configure; make; make install" the equivalent | ||
| 116 | busybox build would be "make defconfig; make; make install". | ||
| 117 | </p> | ||
| 118 | |||
| 119 | <p> Busybox configured with all features enabled is a little under a megabyte | ||
| 120 | dynamically linked on x86. To create a smaller busybox, configure it with | ||
| 121 | fewer features. Individual busybox applets cost anywhere from a few | ||
| 122 | hundred bytes to tens of kilobytes. Disable unneeded applets to save, | ||
| 123 | space, using menuconfig. | ||
| 124 | </p> | ||
| 125 | |||
| 126 | <p>The most important busybox configurators are:</p> | ||
| 127 | |||
| 128 | <ul> | ||
| 129 | <li><p>make <b>defconfig</b> - Create the maximum "sane" configuration. This | ||
| 130 | enables almost all features, minus things like debugging options and features | ||
| 131 | that require changes to the rest of the system to work (such as selinux or | ||
| 132 | devfs device names). Use this if you want to start from a full-featured | ||
| 133 | busybox and remove features until it's small enough.</p></li> | ||
| 134 | <li><p>make <b>allnoconfig</b> - Disable everything. This creates a tiny version | ||
| 135 | of busybox that doesn't do anything. Start here if you know exactly what | ||
| 136 | you want and would like to select only those features.</p></li> | ||
| 137 | <li><p>make <b>menuconfig</b> - Interactively modify a .config file through a | ||
| 138 | multi-level menu interface. Use this after one of the previous two.</p></li> | ||
| 139 | </ul> | ||
| 140 | |||
| 141 | <p>Some other configuration options are:</p> | ||
| 142 | <ul> | ||
| 143 | <li><p>make <b>oldconfig</b> - Update an old .config file for a newer version | ||
| 144 | of busybox.</p></li> | ||
| 145 | <li><p>make <b>allyesconfig</b> - Select absolutely everything. This creates | ||
| 146 | a statically linked version of busybox full of debug code, with dependencies on | ||
| 147 | selinux, using devfs names... This makes sure everything compiles. Whether | ||
| 148 | or not the result would do anything useful is an open question.</p></li> | ||
| 149 | <li><p>make <b>allbareconfig</b> - Select all applets but disable all sub-features | ||
| 150 | within each applet. More build coverage testing.</p></li> | ||
| 151 | <li><p>make <b>randconfig</b> - Create a random configuration for test purposes.</p></li> | ||
| 152 | </ul> | ||
| 153 | |||
| 154 | <p> Menuconfig modifies your .config file through an interactive menu where you can enable or disable | ||
| 155 | busybox features, and get help about each feature. | ||
| 156 | |||
| 157 | |||
| 158 | |||
| 159 | <p> | ||
| 160 | To build a smaller busybox binary, run "make menuconfig" and disable the | ||
| 161 | features you don't need. (Or run "make allnoconfig" and then use | ||
| 162 | menuconfig to add just the features you need. Don't forget to recompile | ||
| 163 | with "make" once you've finished configuring.) | ||
| 164 | </p> | ||
| 165 | <hr/> | ||
| 166 | <p/> | ||
| 167 | <h2><a name="build_system">How do I build a BusyBox-based system?</a></h2> | ||
| 168 | <p> | ||
| 169 | BusyBox is a package that replaces a dozen standard packages, but it is | ||
| 170 | not by itself a complete bootable system. Building an entire Linux | ||
| 171 | distribution from source is a bit beyond the scope of this FAQ, but it | ||
| 172 | understandably keeps cropping up on the mailing list, so here are some | ||
| 173 | pointers. | ||
| 174 | </p> | ||
| 175 | <p> | ||
| 176 | Start by learning how to strip a working system down to the bare essentials | ||
| 177 | needed to run one or two commands, so you know what it is you actually | ||
| 178 | need. An excellent practical place to do | ||
| 179 | this is the <a href="http://www.tldp.org/HOWTO/Bootdisk-HOWTO/">Linux | ||
| 180 | BootDisk Howto</a>, or for a more theoretical approach try | ||
| 181 | <a href="http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html">From | ||
| 182 | PowerUp to Bash Prompt</a>. | ||
| 183 | </p> | ||
| 184 | <p> | ||
| 185 | To learn how to build a working Linux system entirely from source code, | ||
| 186 | the place to go is the <a href="http://www.linuxfromscratch.org">Linux | ||
| 187 | From Scratch</a> project. They have an entire book of step-by-step | ||
| 188 | instructions you can | ||
| 189 | <a href="http://www.linuxfromscratch.org/lfs/view/stable/">read online</a> | ||
| 190 | or | ||
| 191 | <a href="http://www.linuxfromscratch.org/lfs/downloads/stable/">download</a>. | ||
| 192 | Be sure to check out the other sections of their main page, including | ||
| 193 | Beyond Linux From Scratch, Hardened Linux From Scratch, their Hints | ||
| 194 | directory, and their LiveCD project. (They also have mailing lists which | ||
| 195 | are better sources of answers to Linux-system building questions than | ||
| 196 | the busybox list.) | ||
| 197 | </p> | ||
| 198 | <p> | ||
| 199 | If you want an automated yet customizable system builder which produces | ||
| 200 | a BusyBox and uClibc based system, try | ||
| 201 | <a href="http://buildroot.uclibc.org">buildroot</a>, which is | ||
| 202 | another project by the maintainer of the uClibc (Erik Andersen). | ||
| 203 | Download the tarball, extract it, unset CC, make. | ||
| 204 | For more instructions, see the website. | ||
| 205 | </p> | ||
| 206 | |||
| 207 | <hr /> | ||
| 208 | <p> | ||
| 209 | <h2><a name="kernel">Which Linux kernel versions are supported?</a></h2> | ||
| 210 | <p> | ||
| 211 | Full functionality requires Linux 2.4.x or better. (Earlier versions may | ||
| 212 | still work, but are no longer regularly tested.) A large fraction of the | ||
| 213 | code should run on just about anything. While the current code is fairly | ||
| 214 | Linux specific, it should be fairly easy to port the majority of the code | ||
| 215 | to support, say, FreeBSD or Solaris, or Mac OS X, or even Windows (if you | ||
| 216 | are into that sort of thing). | ||
| 217 | </p> | ||
| 218 | <hr /> | ||
| 219 | <p> | ||
| 220 | <h2><a name="arch">Which architectures does BusyBox run on?</a></h2> | ||
| 221 | <p> | ||
| 222 | BusyBox in general will build on any architecture supported by gcc. | ||
| 223 | Kernel module loading for 2.4 Linux kernels is currently | ||
| 224 | limited to ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC, | ||
| 225 | S390, SH3/4/5, Sparc, v850e, and x86_64 for 2.4.x kernels. | ||
| 226 | </p> | ||
| 227 | <p> | ||
| 228 | With 2.6.x kernels, module loading support should work on all architectures. | ||
| 229 | </p> | ||
| 230 | <hr /> | ||
| 231 | <p> | ||
| 232 | <h2><a name="libc">Which C libraries are supported?</a></h2> | ||
| 233 | <p> | ||
| 234 | On Linux, BusyBox releases are tested against uClibc (0.9.27 or later) and | ||
| 235 | glibc (2.2 or later). Both should provide full functionality with busybox, | ||
| 236 | and if you find a bug we want to hear about it. | ||
| 237 | </p> | ||
| 238 | <p> | ||
| 239 | Linux-libc5 is no longer maintained (and has no known advantages over | ||
| 240 | uClibc), dietlibc is known to have numerous unfixed bugs, and klibc is | ||
| 241 | missing too many features to build BusyBox. If you require a small C | ||
| 242 | library for Linux, the busybox developers recommend uClibc. | ||
| 243 | </p> | ||
| 244 | <p> | ||
| 245 | Some BusyBox applets have been built and run under a combination | ||
| 246 | of newlib and libgloss (see | ||
| 247 | <a href="http://www.busybox.net/lists/busybox/2005-March/013759.html">this thread</a>). | ||
| 248 | This is still experimental, but may be supported in a future release. | ||
| 249 | </p> | ||
| 250 | |||
| 251 | <hr /> | ||
| 252 | <p> | ||
| 253 | <h2><a name="commercial">Can I include BusyBox as part of the software on my device?</a></h2> | ||
| 254 | <p> | ||
| 255 | |||
| 256 | <p> | ||
| 257 | Yes. As long as you <a href="http://busybox.net/license.html">fully comply | ||
| 258 | with the generous terms of the GPL BusyBox license</a> you can ship BusyBox | ||
| 259 | as part of the software on your device. | ||
| 260 | </p> | ||
| 261 | |||
| 262 | <hr /> | ||
| 263 | <p> | ||
| 264 | <h2><a name="external">where can i find other small utilities since busybox | ||
| 265 | does not include the features i want?</a></h2> | ||
| 266 | <p> | ||
| 267 | we maintain such a <a href="tinyutils.html">list</a> on this site! | ||
| 268 | </p> | ||
| 269 | |||
| 270 | <hr /> | ||
| 271 | <p> | ||
| 272 | <h2><a name="demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a></h2> | ||
| 273 | <p> | ||
| 274 | |||
| 275 | You have not paid us a single cent and yet you still have the product of | ||
| 276 | many years of our work. We are not your slaves! We work on BusyBox | ||
| 277 | because we find it useful and interesting. If you go off flaming us, we | ||
| 278 | will ignore you. | ||
| 279 | |||
| 280 | |||
| 281 | <hr /> | ||
| 282 | <p> | ||
| 283 | <h2><a name="helpme">I need help with BusyBox! What should I do?</a></h2> | ||
| 284 | <p> | ||
| 285 | |||
| 286 | If you find that you need help with BusyBox, you can ask for help on the | ||
| 287 | BusyBox mailing list at busybox@busybox.net.</p> | ||
| 288 | |||
| 289 | <p> In addition to the mailing list, Erik Andersen (andersee), Manuel Nova | ||
| 290 | (mjn3), Rob Landley (landley), Mike Frysinger (SpanKY), Bernhard Fischer | ||
| 291 | (blindvt), and other long-time BusyBox developers are known to hang out | ||
| 292 | on the uClibc IRC channel: #uclibc on irc.freenode.net. There is a | ||
| 293 | <a href="http://ibot.Rikers.org/%23uclibc/">web archive of | ||
| 294 | daily logs of the #uclibc IRC channel</a> going back to 2002. | ||
| 295 | </p> | ||
| 296 | |||
| 297 | <p> | ||
| 298 | <b>Please do not send private email to Rob, Erik, Manuel, or the other | ||
| 299 | BusyBox contributors asking for private help unless you are planning on | ||
| 300 | paying for consulting services.</b> | ||
| 301 | </p> | ||
| 302 | |||
| 303 | <p> | ||
| 304 | When we answer questions on the BusyBox mailing list, it helps everyone | ||
| 305 | since people with similar problems in the future will be able to get help | ||
| 306 | by searching the mailing list archives. Private help is reserved as a paid | ||
| 307 | service. If you need to use private communication, or if you are serious | ||
| 308 | about getting timely assistance with BusyBox, you should seriously consider | ||
| 309 | paying for consulting services. | ||
| 310 | </p> | ||
| 311 | |||
| 312 | <hr /> | ||
| 313 | <p> | ||
| 314 | <h2><a name="contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a></h2> | ||
| 315 | </p> | ||
| 316 | |||
| 317 | <p> | ||
| 318 | Yes we are. The easy way to sponsor a new feature is to post an offer on | ||
| 319 | the mailing list to see who's interested. You can also email the project's | ||
| 320 | maintainer and ask them to recommend someone. | ||
| 321 | </p> | ||
| 322 | |||
| 323 | <p> If you prefer to deal with an organization rather than an individual, Rob | ||
| 324 | Landley (the current BusyBox maintainer) works for | ||
| 325 | <a http://www.timesys.com>TimeSys</a>, and Eric Andersen (the previous | ||
| 326 | busybox maintainer and current uClibc maintainer) owns | ||
| 327 | <a href="http://codepoet-consulting.com/">CodePoet Consulting</a>. Both | ||
| 328 | companies offer support contracts and handle new development, and there | ||
| 329 | are plenty of other companies that do the same. | ||
| 330 | </p> | ||
| 331 | |||
| 332 | |||
| 333 | |||
| 334 | |||
| 335 | <h1>Troubleshooting</h1> | ||
| 336 | |||
| 337 | <hr /> | ||
| 338 | <p></p> | ||
| 339 | <h2><a name="bugs">I think I found a bug in BusyBox! What should I do?</a></h2> | ||
| 340 | <p></p> | ||
| 341 | |||
| 342 | <p> | ||
| 343 | If you simply need help with using or configuring BusyBox, please submit a | ||
| 344 | detailed description of your problem to the BusyBox mailing list at <a | ||
| 345 | href="mailto:busybox@busybox.net"> busybox@busybox.net</a>. | ||
| 346 | Please do not send email to individual developers asking | ||
| 347 | for private help unless you are planning on paying for consulting services. | ||
| 348 | When we answer questions on the BusyBox mailing list, it helps everyone, | ||
| 349 | while private answers help only you... | ||
| 350 | </p> | ||
| 351 | |||
| 352 | <p> | ||
| 353 | Bug reports and new feature patches sometimes get lost when posted to the | ||
| 354 | mailing list, because the developers of BusyBox are busy people and have | ||
| 355 | only so much they can keep in their brains at a time. You can post a | ||
| 356 | polite reminder after 2-3 days without offending anybody. If that doesn't | ||
| 357 | result in a solution, please use the | ||
| 358 | <a href="http://bugs.busybox.net/">BusyBox Bug | ||
| 359 | and Patch Tracking System</a> to submit a detailed explanation and we'll | ||
| 360 | get to it as soon as we can. | ||
| 361 | </p> | ||
| 362 | |||
| 363 | <p> | ||
| 364 | Note that bugs entered into the bug system without being mentioned on the | ||
| 365 | mailing list first may languish there for months before anyone even notices | ||
| 366 | them. We generally go through the bug system when preparing for new | ||
| 367 | development releases, to see what fell through the cracks while we were | ||
| 368 | off writing new features. (It's a fast/unreliable vs slow/reliable thing. | ||
| 369 | Saves retransits, but the latency sucks.) | ||
| 370 | </p> | ||
| 371 | |||
| 372 | <hr /> | ||
| 373 | <p></p> | ||
| 374 | <h2><a name="backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</h2> | ||
| 375 | |||
| 376 | <p>Variants of this one get asked a lot.</p> | ||
| 377 | |||
| 378 | <p>The purpose of the BusyBox mailing list is to develop and improve BusyBox, | ||
| 379 | and we're happy to respond to our users' needs. But if you're coming to the | ||
| 380 | list for free tech support we're going to ask you to upgrade to a current | ||
| 381 | version before we try to diagnose your problem.</p> | ||
| 382 | |||
| 383 | <p>If you're building BusyBox 0.50 with uClibc 0.9.19 and gcc 0.9.26 there's a | ||
| 384 | fairly large chance that whatever problem you're seeing has already been fixed. | ||
| 385 | To get that fix, all you have to do is upgrade to a newer version. If you | ||
| 386 | don't at least _try_ that, you're wasting our time.</p> | ||
| 387 | |||
| 388 | <p>The volunteers are happy to fix any bugs you point out in the current | ||
| 389 | versions because doing so helps everybody and makes the project better. We | ||
| 390 | want to make the current version work for you. But diagnosing, debugging, and | ||
| 391 | backporting fixes to old versions isn't something we do for free, because it | ||
| 392 | doesn't help anybody but you. The cost of volunteer tech support is using a | ||
| 393 | reasonably current version of the project.</p> | ||
| 394 | |||
| 395 | <p>If you don't want to upgrade, you have the complete source code and thus | ||
| 396 | the ability to fix it yourself, or hire a consultant to do it for you. If you | ||
| 397 | got your version from a vendor who still supports the older version, they can | ||
| 398 | help you. But there are limits as to what the volunteers will feel obliged to | ||
| 399 | do for you.</p> | ||
| 400 | |||
| 401 | <p>As a rule of thumb, volunteers will generally answer polite questions about | ||
| 402 | a given version for about three years after its release before it's so old | ||
| 403 | we don't remember the answer off the top of our head. And if you want us to | ||
| 404 | put any _effort_ into tracking it down, we want you to put in a little effort | ||
| 405 | of your own by confirming it's still a problem with the current version. It's | ||
| 406 | also hard for us to fix a problem of yours if we can't reproduce it because | ||
| 407 | we don't have any systems running an environment that old.</p> | ||
| 408 | |||
| 409 | <p>A consultant will happily set up a special environment just to reproduce | ||
| 410 | your problem, and you can always ask on the list if any of the developers | ||
| 411 | have consulting rates.</p> | ||
| 412 | |||
| 413 | <hr /> | ||
| 414 | <p> | ||
| 415 | <h2><a name="init">Busybox init isn't working!</a></h2> | ||
| 416 | <p> | ||
| 417 | Init is the first program that runs, so it might be that no programs are | ||
| 418 | working on your new system because of a problem with your cross-compiler, | ||
| 419 | kernel, console settings, shared libraries, root filesystem... To rule all | ||
| 420 | that out, first build a statically linked version of the following "hello | ||
| 421 | world" program with your cross compiler toolchain: | ||
| 422 | </p> | ||
| 423 | <pre> | ||
| 424 | #include <stdio.h> | ||
| 425 | |||
| 426 | int main(int argc, char *argv) | ||
| 427 | { | ||
| 428 | printf("Hello world!\n"); | ||
| 429 | sleep(999999999); | ||
| 430 | } | ||
| 431 | </pre> | ||
| 432 | |||
| 433 | <p> | ||
| 434 | Now try to boot your device with an "init=" argument pointing to your | ||
| 435 | hello world program. Did you see the hello world message? Until you | ||
| 436 | do, don't bother messing with busybox init. | ||
| 437 | </p> | ||
| 438 | |||
| 439 | <p> | ||
| 440 | Once you've got it working statically linked, try getting it to work | ||
| 441 | dynamically linked. Then read the FAQ entry <a href="#build_system">How | ||
| 442 | do I build a BusyBox-based system?</a>, and the | ||
| 443 | <a href="/downloads/BusyBox.html#item_init">documentation for BusyBox | ||
| 444 | init</a>. | ||
| 445 | </p> | ||
| 446 | |||
| 447 | <hr /> | ||
| 448 | <p> | ||
| 449 | <h2><a name="sed">I can't configure busybox on my system.</a></h2> | ||
| 450 | <p> | ||
| 451 | Configuring Busybox depends on a recent version of sed. Older | ||
| 452 | distributions (Red Hat 7.2, Debian 3.0) may not come with a | ||
| 453 | usable version. Luckily BusyBox can use its own sed to configure itself, | ||
| 454 | although this leads to a bit of a chicken and egg problem. | ||
| 455 | You can work around this by hand-configuring busybox to build with just | ||
| 456 | sed, then putting that sed in your path to configure the rest of busybox | ||
| 457 | with, like so: | ||
| 458 | </p> | ||
| 459 | |||
| 460 | <pre> | ||
| 461 | tar xvjf sources/busybox-x.x.x.tar.bz2 | ||
| 462 | cd busybox-x.x.x | ||
| 463 | make allnoconfig | ||
| 464 | make include/bb_config.h | ||
| 465 | echo "CONFIG_SED=y" >> .config | ||
| 466 | echo "#undef ENABLE_SED" >> include/bb_config.h | ||
| 467 | echo "#define ENABLE_SED 1" >> include/bb_config.h | ||
| 468 | make | ||
| 469 | mv busybox sed | ||
| 470 | export PATH=`pwd`:"$PATH" | ||
| 471 | </pre> | ||
| 472 | |||
| 473 | <p>Then you can run "make defconfig" or "make menuconfig" normally.</p> | ||
| 474 | |||
| 475 | <hr /> | ||
| 476 | <p> | ||
| 477 | <h2><a name="job_control">Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?</a></h2> | ||
| 478 | <p> | ||
| 479 | |||
| 480 | Job control will be turned off since your shell can not obtain a controlling | ||
| 481 | terminal. This typically happens when you run your shell on /dev/console. | ||
| 482 | The kernel will not provide a controlling terminal on the /dev/console | ||
| 483 | device. Your should run your shell on a normal tty such as tty1 or ttyS0 | ||
| 484 | and everything will work perfectly. If you <em>REALLY</em> want your shell | ||
| 485 | to run on /dev/console, then you can hack your kernel (if you are into that | ||
| 486 | sortof thing) by changing drivers/char/tty_io.c to change the lines where | ||
| 487 | it sets "noctty = 1;" to instead set it to "0". I recommend you instead | ||
| 488 | run your shell on a real console... | ||
| 489 | </p> | ||
| 490 | |||
| 491 | <h1>Development</h1> | ||
| 492 | |||
| 493 | <h2><b><a name="goals">What are the goals of busybox?</a></b></h2> | ||
| 494 | |||
| 495 | <p>Busybox aims to be the smallest and simplest correct implementation of the | ||
| 496 | standard Linux command line tools. First and foremost, this means the | ||
| 497 | smallest executable size we can manage. We also want to have the simplest | ||
| 498 | and cleanest implementation we can manage, be <a href="#standards">standards | ||
| 499 | compliant</a>, minimize run-time memory usage (heap and stack), run fast, and | ||
| 500 | take over the world.</p> | ||
| 501 | |||
| 502 | <h2><b><a name="design">What is the design of busybox?</a></b></h2> | ||
| 503 | |||
| 504 | <p>Busybox is like a swiss army knife: one thing with many functions. | ||
| 505 | The busybox executable can act like many different programs depending on | ||
| 506 | the name used to invoke it. Normal practice is to create a bunch of symlinks | ||
| 507 | pointing to the busybox binary, each of which triggers a different busybox | ||
| 508 | function. (See <a href="FAQ.html#getting_started">getting started</a> in the | ||
| 509 | FAQ for more information on usage, and <a href="BusyBox.html">the | ||
| 510 | busybox documentation</a> for a list of symlink names and what they do.) | ||
| 511 | |||
| 512 | <p>The "one binary to rule them all" approach is primarily for size reasons: a | ||
| 513 | single multi-purpose executable is smaller then many small files could be. | ||
| 514 | This way busybox only has one set of ELF headers, it can easily share code | ||
| 515 | between different apps even when statically linked, it has better packing | ||
| 516 | efficiency by avoding gaps between files or compression dictionary resets, | ||
| 517 | and so on.</p> | ||
| 518 | |||
| 519 | <p>Work is underway on new options such as "make standalone" to build separate | ||
| 520 | binaries for each applet, and a "libbb.so" to make the busybox common code | ||
| 521 | available as a shared library. Neither is ready yet at the time of this | ||
| 522 | writing.</p> | ||
| 523 | |||
| 524 | <a name="source"></a> | ||
| 525 | |||
| 526 | <h2><a name="source_applets"><b>The applet directories</b></a></h2> | ||
| 527 | |||
| 528 | <p>The directory "applets" contains the busybox startup code (applets.c and | ||
| 529 | busybox.c), and several subdirectories containing the code for the individual | ||
| 530 | applets.</p> | ||
| 531 | |||
| 532 | <p>Busybox execution starts with the main() function in applets/busybox.c, | ||
| 533 | which sets the global variable applet_name to argv[0] and calls | ||
| 534 | run_applet_by_name() in applets/applets.c. That uses the applets[] array | ||
| 535 | (defined in include/busybox.h and filled out in include/applets.h) to | ||
| 536 | transfer control to the appropriate APPLET_main() function (such as | ||
| 537 | cat_main() or sed_main()). The individual applet takes it from there.</p> | ||
| 538 | |||
| 539 | <p>This is why calling busybox under a different name triggers different | ||
| 540 | functionality: main() looks up argv[0] in applets[] to get a function pointer | ||
| 541 | to APPLET_main().</p> | ||
| 542 | |||
| 543 | <p>Busybox applets may also be invoked through the multiplexor applet | ||
| 544 | "busybox" (see busybox_main() in applets/busybox.c), and through the | ||
| 545 | standalone shell (grep for STANDALONE_SHELL in applets/shell/*.c). | ||
| 546 | See <a href="FAQ.html#getting_started">getting started</a> in the | ||
| 547 | FAQ for more information on these alternate usage mechanisms, which are | ||
| 548 | just different ways to reach the relevant APPLET_main() function.</p> | ||
| 549 | |||
| 550 | <p>The applet subdirectories (archival, console-tools, coreutils, | ||
| 551 | debianutils, e2fsprogs, editors, findutils, init, loginutils, miscutils, | ||
| 552 | modutils, networking, procps, shell, sysklogd, and util-linux) correspond | ||
| 553 | to the configuration sub-menus in menuconfig. Each subdirectory contains the | ||
| 554 | code to implement the applets in that sub-menu, as well as a Config.in | ||
| 555 | file defining that configuration sub-menu (with dependencies and help text | ||
| 556 | for each applet), and the makefile segment (Makefile.in) for that | ||
| 557 | subdirectory.</p> | ||
| 558 | |||
| 559 | <p>The run-time --help is stored in usage_messages[], which is initialized at | ||
| 560 | the start of applets/applets.c and gets its help text from usage.h. During the | ||
| 561 | build this help text is also used to generate the BusyBox documentation (in | ||
| 562 | html, txt, and man page formats) in the docs directory. See | ||
| 563 | <a href="#adding">adding an applet to busybox</a> for more | ||
| 564 | information.</p> | ||
| 565 | |||
| 566 | <h2><a name="source_libbb"><b>libbb</b></a></h2> | ||
| 567 | |||
| 568 | <p>Most non-setup code shared between busybox applets lives in the libbb | ||
| 569 | directory. It's a mess that evolved over the years without much auditing | ||
| 570 | or cleanup. For anybody looking for a great project to break into busybox | ||
| 571 | development with, documenting libbb would be both incredibly useful and good | ||
| 572 | experience.</p> | ||
| 573 | |||
| 574 | <p>Common themes in libbb include allocation functions that test | ||
| 575 | for failure and abort the program with an error message so the caller doesn't | ||
| 576 | have to test the return value (xmalloc(), xstrdup(), etc), wrapped versions | ||
| 577 | of open(), close(), read(), and write() that test for their own failures | ||
| 578 | and/or retry automatically, linked list management functions (llist.c), | ||
| 579 | command line argument parsing (getopt32.c), and a whole lot more.</p> | ||
| 580 | |||
| 581 | <hr /> | ||
| 582 | <p> | ||
| 583 | <h2><a name="optimize">I want to make busybox even smaller, how do I go about it?</a></h2> | ||
| 584 | <p> | ||
| 585 | To conserve bytes it's good to know where they're being used, and the | ||
| 586 | size of the final executable isn't always a reliable indicator of | ||
| 587 | the size of the components (since various structures are rounded up, | ||
| 588 | so a small change may not even be visible by itself, but many small | ||
| 589 | savings add up). | ||
| 590 | </p> | ||
| 591 | |||
| 592 | <p> The busybox Makefile builds two versions of busybox, one of which | ||
| 593 | (busybox_unstripped) has extra information that various analysis tools | ||
| 594 | can use. (This has nothing to do with CONFIG_DEBUG, leave that off | ||
| 595 | when trying to optimize for size.) | ||
| 596 | </p> | ||
| 597 | |||
| 598 | <p> The <b>"make bloatcheck"</b> option uses Matt Mackall's bloat-o-meter | ||
| 599 | script to compare two versions of busybox (busybox_unstripped vs | ||
| 600 | busybox_old), and report which symbols changed size and by how much. | ||
| 601 | To use it, first build a base version with <b>"make baseline"</b>. | ||
| 602 | (This creates busybox_old, which should have the original sizes for | ||
| 603 | comparison purposes.) Then build the new version with your changes | ||
| 604 | and run "make bloatcheck" to see the size differences from the old | ||
| 605 | version. | ||
| 606 | </p> | ||
| 607 | <p> | ||
| 608 | The first line of output has totals: how many symbols were added or | ||
| 609 | removed, how many symbols grew or shrank, the number of bytes added | ||
| 610 | and number of bytes removed by these changes, and finally the total | ||
| 611 | number of bytes difference between the two files. The remaining | ||
| 612 | lines show each individual symbol, the old and new sizes, and the | ||
| 613 | increase or decrease in size (which results are sorted by). | ||
| 614 | </p> | ||
| 615 | <p> | ||
| 616 | The <b>"make sizes"</b> option produces raw symbol size information for | ||
| 617 | busybox_unstripped. This is the output from the "nm --size-sort" | ||
| 618 | command (see "man nm" for more information), and is the information | ||
| 619 | bloat-o-meter parses to produce the comparison report above. For | ||
| 620 | defconfig, this is a good way to find the largest symbols in the tree | ||
| 621 | (which is a good place to start when trying to shrink the code). To | ||
| 622 | take a closer look at individual applets, configure busybox with just | ||
| 623 | one applet (run "make allnoconfig" and then switch on a single applet | ||
| 624 | with menuconfig), and then use "make sizes" to see the size of that | ||
| 625 | applet's components. | ||
| 626 | </p> | ||
| 627 | <p> | ||
| 628 | The "showasm" command (in the scripts directory) produces an assembly | ||
| 629 | dump of a function, providing a closer look at what changed. Try | ||
| 630 | "scripts/showasm busybox_unstripped" to list available symbols, and | ||
| 631 | "scripts/showasm busybox_unstripped symbolname" to see the assembly | ||
| 632 | for a sepecific symbol. | ||
| 633 | </p> | ||
| 634 | <hr /> | ||
| 635 | |||
| 636 | |||
| 637 | |||
| 638 | <h2><a name="adding"><b>Adding an applet to busybox</b></a></h2> | ||
| 639 | |||
| 640 | <p>To add a new applet to busybox, first pick a name for the applet and | ||
| 641 | a corresponding CONFIG_NAME. Then do this:</p> | ||
| 642 | |||
| 643 | <ul> | ||
| 644 | <li>Figure out where in the busybox source tree your applet best fits, | ||
| 645 | and put your source code there. Be sure to use APPLET_main() instead | ||
| 646 | of main(), where APPLET is the name of your applet.</li> | ||
| 647 | |||
| 648 | <li>Add your applet to the relevant Config.in file (which file you add | ||
| 649 | it to determines where it shows up in "make menuconfig"). This uses | ||
| 650 | the same general format as the linux kernel's configuration system.</li> | ||
| 651 | |||
| 652 | <li>Add your applet to the relevant Makefile.in file (in the same | ||
| 653 | directory as the Config.in you chose), using the existing entries as a | ||
| 654 | template and the same CONFIG symbol as you used for Config.in. (Don't | ||
| 655 | forget "needlibm" or "needcrypt" if your applet needs libm or | ||
| 656 | libcrypt.)</li> | ||
| 657 | |||
| 658 | <li>Add your applet to "include/applets.h", using one of the existing | ||
| 659 | entries as a template. (Note: this is in alphabetical order. Applets | ||
| 660 | are found via binary search, and if you add an applet out of order it | ||
| 661 | won't work.)</li> | ||
| 662 | |||
| 663 | <li>Add your applet's runtime help text to "include/usage.h". You need | ||
| 664 | at least appname_trivial_usage (the minimal help text, always included | ||
| 665 | in the busybox binary when this applet is enabled) and appname_full_usage | ||
| 666 | (extra help text included in the busybox binary with | ||
| 667 | CONFIG_FEATURE_VERBOSE_USAGE is enabled), or it won't compile. | ||
| 668 | The other two help entry types (appname_example_usage and | ||
| 669 | appname_notes_usage) are optional. They don't take up space in the binary, | ||
| 670 | but instead show up in the generated documentation (BusyBox.html, | ||
| 671 | BusyBox.txt, and the man page BusyBox.1).</li> | ||
| 672 | |||
| 673 | <li>Run menuconfig, switch your applet on, compile, test, and fix the | ||
| 674 | bugs. Be sure to try both "allyesconfig" and "allnoconfig" (and | ||
| 675 | "allbareconfig" if relevant).</li> | ||
| 676 | |||
| 677 | </ul> | ||
| 678 | |||
| 679 | <h2><a name="standards">What standards does busybox adhere to?</a></h2> | ||
| 680 | |||
| 681 | <p>The standard we're paying attention to is the "Shell and Utilities" | ||
| 682 | portion of the <a href="http://www.opengroup.org/onlinepubs/009695399/">Open | ||
| 683 | Group Base Standards</a> (also known as the Single Unix Specification version | ||
| 684 | 3 or SUSv3). Note that paying attention isn't necessarily the same thing as | ||
| 685 | following it.</p> | ||
| 686 | |||
| 687 | <p>SUSv3 doesn't even mention things like init, mount, tar, or losetup, nor | ||
| 688 | commonly used options like echo's '-e' and '-n', or sed's '-i'. Busybox is | ||
| 689 | driven by what real users actually need, not the fact the standard believes | ||
| 690 | we should implement ed or sccs. For size reasons, we're unlikely to include | ||
| 691 | much internationalization support beyond UTF-8, and on top of all that, our | ||
| 692 | configuration menu lets developers chop out features to produce smaller but | ||
| 693 | very non-standard utilities.</p> | ||
| 694 | |||
| 695 | <p>Also, Busybox is aimed primarily at Linux. Unix standards are interesting | ||
| 696 | because Linux tries to adhere to them, but portability to dozens of platforms | ||
| 697 | is only interesting in terms of offering a restricted feature set that works | ||
| 698 | everywhere, not growing dozens of platform-specific extensions. Busybox | ||
| 699 | should be portable to all hardware platforms Linux supports, and any other | ||
| 700 | similar operating systems that are easy to do and won't require much | ||
| 701 | maintenance.</p> | ||
| 702 | |||
| 703 | <p>In practice, standards compliance tends to be a clean-up step once an | ||
| 704 | applet is otherwise finished. When polishing and testing a busybox applet, | ||
| 705 | we ensure we have at least the option of full standards compliance, or else | ||
| 706 | document where we (intentionally) fall short.</p> | ||
| 707 | |||
| 708 | <h2><a name="portability">Portability.</a></h2> | ||
| 709 | |||
| 710 | <p>Busybox is a Linux project, but that doesn't mean we don't have to worry | ||
| 711 | about portability. First of all, there are different hardware platforms, | ||
| 712 | different C library implementations, different versions of the kernel and | ||
| 713 | build toolchain... The file "include/platform.h" exists to centralize and | ||
| 714 | encapsulate various platform-specific things in one place, so most busybox | ||
| 715 | code doesn't have to care where it's running.</p> | ||
| 716 | |||
| 717 | <p>To start with, Linux runs on dozens of hardware platforms. We try to test | ||
| 718 | each release on x86, x86-64, arm, power pc, and mips. (Since qemu can handle | ||
| 719 | all of these, this isn't that hard.) This means we have to care about a number | ||
| 720 | of portability issues like endianness, word size, and alignment, all of which | ||
| 721 | belong in platform.h. That header handles conditional #includes and gives | ||
| 722 | us macros we can use in the rest of our code. At some point in the future | ||
| 723 | we might grow a platform.c, possibly even a platform subdirectory. As long | ||
| 724 | as the applets themselves don't have to care.</p> | ||
| 725 | |||
| 726 | <p>On a related note, we made the "default signedness of char varies" problem | ||
| 727 | go away by feeding the compiler -funsigned-char. This gives us consistent | ||
| 728 | behavior on all platforms, and defaults to 8-bit clean text processing (which | ||
| 729 | gets us halfway to UTF-8 support). NOMMU support is less easily separated | ||
| 730 | (see the tips section later in this document), but we're working on it.</p> | ||
| 731 | |||
| 732 | <p>Another type of portability is build environments: we unapologetically use | ||
| 733 | a number of gcc and glibc extensions (as does the Linux kernel), but these have | ||
| 734 | been picked up by packages like uClibc, TCC, and Intel's C Compiler. As for | ||
| 735 | gcc, we take advantage of newer compiler optimizations to get the smallest | ||
| 736 | possible size, but we also regression test against an older build environment | ||
| 737 | using the Red Hat 9 image at "http://busybox.net/downloads/qemu". This has a | ||
| 738 | 2.4 kernel, gcc 3.2, make 3.79.1, and glibc 2.3, and is the oldest | ||
| 739 | build/deployment environment we still put any effort into maintaining. (If | ||
| 740 | anyone takes an interest in older kernels you're welcome to submit patches, | ||
| 741 | but the effort would probably be better spent | ||
| 742 | <a href="http://www.selenic.com/linux-tiny/">trimming | ||
| 743 | down the 2.6 kernel</a>.) Older gcc versions than that are uninteresting since | ||
| 744 | we now use c99 features, although | ||
| 745 | <a href="http://fabrice.bellard.free.fr/tcc/">tcc</a> might be worth a | ||
| 746 | look.</p> | ||
| 747 | |||
| 748 | <p>We also test busybox against the current release of uClibc. Older versions | ||
| 749 | of uClibc aren't very interesting (they were buggy, and uClibc wasn't really | ||
| 750 | usable as a general-purpose C library before version 0.9.26 anyway).</p> | ||
| 751 | |||
| 752 | <p>Other unix implementations are mostly uninteresting, since Linux binaries | ||
| 753 | have become the new standard for portable Unix programs. Specifically, | ||
| 754 | the ubiquity of Linux was cited as the main reason the Intel Binary | ||
| 755 | Compatability Standard 2 died, by the standards group organized to name a | ||
| 756 | successor to ibcs2: <a href="http://www.telly.org/86open/">the 86open | ||
| 757 | project</a>. That project disbanded in 1999 with the endorsement of an | ||
| 758 | existing standard: Linux ELF binaries. Since then, the major players at the | ||
| 759 | time (such as <a | ||
| 760 | href=http://www-03.ibm.com/servers/aix/products/aixos/linux/index.html>AIX</a>, <a | ||
| 761 | href=http://www.sun.com/software/solaris/ds/linux_interop.jsp#3>Solaris</a>, and | ||
| 762 | <a href=http://www.onlamp.com/pub/a/bsd/2000/03/17/linuxapps.html>FreeBSD</a>) | ||
| 763 | have all either grown Linux support or folded.</p> | ||
| 764 | |||
| 765 | <p>The major exceptions are newcomer MacOS X, some embedded environments | ||
| 766 | (such as newlib+libgloss) which provide a posix environment but not a full | ||
| 767 | Linux environment, and environments like Cygwin that provide only partial Linux | ||
| 768 | emulation. Also, some embedded Linux systems run a Linux kernel but amputate | ||
| 769 | things like the /proc directory to save space.</p> | ||
| 770 | |||
| 771 | <p>Supporting these systems is largely a question of providing a clean subset | ||
| 772 | of BusyBox's functionality -- whichever applets can easily be made to | ||
| 773 | work in that environment. Annotating the configuration system to | ||
| 774 | indicate which applets require which prerequisites (such as procfs) is | ||
| 775 | also welcome. Other efforts to support these systems (swapping #include | ||
| 776 | files to build in different environments, adding adapter code to platform.h, | ||
| 777 | adding more extensive special-case supporting infrastructure such as mount's | ||
| 778 | legacy mtab support) are handled on a case-by-case basis. Support that can be | ||
| 779 | cleanly hidden in platform.h is reasonably attractive, and failing that | ||
| 780 | support that can be cleanly separated into a separate conditionally compiled | ||
| 781 | file is at least worth a look. Special-case code in the body of an applet is | ||
| 782 | something we're trying to avoid.</p> | ||
| 783 | |||
| 784 | <h2><a name="tips" />Programming tips and tricks.</a></h2> | ||
| 785 | |||
| 786 | <p>Various things busybox uses that aren't particularly well documented | ||
| 787 | elsewhere.</p> | ||
| 788 | |||
| 789 | <h2><a name="tips_encrypted_passwords">Encrypted Passwords</a></h2> | ||
| 790 | |||
| 791 | <p>Password fields in /etc/passwd and /etc/shadow are in a special format. | ||
| 792 | If the first character isn't '$', then it's an old DES style password. If | ||
| 793 | the first character is '$' then the password is actually three fields | ||
| 794 | separated by '$' characters:</p> | ||
| 795 | <pre> | ||
| 796 | <b>$type$salt$encrypted_password</b> | ||
| 797 | </pre> | ||
| 798 | |||
| 799 | <p>The "type" indicates which encryption algorithm to use: 1 for MD5 and 2 for SHA1.</p> | ||
| 800 | |||
| 801 | <p>The "salt" is a bunch of ramdom characters (generally 8) the encryption | ||
| 802 | algorithm uses to perturb the password in a known and reproducible way (such | ||
| 803 | as by appending the random data to the unencrypted password, or combining | ||
| 804 | them with exclusive or). Salt is randomly generated when setting a password, | ||
| 805 | and then the same salt value is re-used when checking the password. (Salt is | ||
| 806 | thus stored unencrypted.)</p> | ||
| 807 | |||
| 808 | <p>The advantage of using salt is that the same cleartext password encrypted | ||
| 809 | with a different salt value produces a different encrypted value. | ||
| 810 | If each encrypted password uses a different salt value, an attacker is forced | ||
| 811 | to do the cryptographic math all over again for each password they want to | ||
| 812 | check. Without salt, they could simply produce a big dictionary of commonly | ||
| 813 | used passwords ahead of time, and look up each password in a stolen password | ||
| 814 | file to see if it's a known value. (Even if there are billions of possible | ||
| 815 | passwords in the dictionary, checking each one is just a binary search against | ||
| 816 | a file only a few gigabytes long.) With salt they can't even tell if two | ||
| 817 | different users share the same password without guessing what that password | ||
| 818 | is and decrypting it. They also can't precompute the attack dictionary for | ||
| 819 | a specific password until they know what the salt value is.</p> | ||
| 820 | |||
| 821 | <p>The third field is the encrypted password (plus the salt). For md5 this | ||
| 822 | is 22 bytes.</p> | ||
| 823 | |||
| 824 | <p>The busybox function to handle all this is pw_encrypt(clear, salt) in | ||
| 825 | "libbb/pw_encrypt.c". The first argument is the clear text password to be | ||
| 826 | encrypted, and the second is a string in "$type$salt$password" format, from | ||
| 827 | which the "type" and "salt" fields will be extracted to produce an encrypted | ||
| 828 | value. (Only the first two fields are needed, the third $ is equivalent to | ||
| 829 | the end of the string.) The return value is an encrypted password in | ||
| 830 | /etc/passwd format, with all three $ separated fields. It's stored in | ||
| 831 | a static buffer, 128 bytes long.</p> | ||
| 832 | |||
| 833 | <p>So when checking an existing password, if pw_encrypt(text, | ||
| 834 | old_encrypted_password) returns a string that compares identical to | ||
| 835 | old_encrypted_password, you've got the right password. When setting a new | ||
| 836 | password, generate a random 8 character salt string, put it in the right | ||
| 837 | format with sprintf(buffer, "$%c$%s", type, salt), and feed buffer as the | ||
| 838 | second argument to pw_encrypt(text,buffer).</p> | ||
| 839 | |||
| 840 | <h2><a name="tips_vfork">Fork and vfork</a></h2> | ||
| 841 | |||
| 842 | <p>On systems that haven't got a Memory Management Unit, fork() is unreasonably | ||
| 843 | expensive to implement (and sometimes even impossible), so a less capable | ||
| 844 | function called vfork() is used instead. (Using vfork() on a system with an | ||
| 845 | MMU is like pounding a nail with a wrench. Not the best tool for the job, but | ||
| 846 | it works.)</p> | ||
| 847 | |||
| 848 | <p>Busybox hides the difference between fork() and vfork() in | ||
| 849 | libbb/bb_fork_exec.c. If you ever want to fork and exec, use bb_fork_exec() | ||
| 850 | (which returns a pid and takes the same arguments as execve(), although in | ||
| 851 | this case envp can be NULL) and don't worry about it. This description is | ||
| 852 | here in case you want to know why that does what it does.</p> | ||
| 853 | |||
| 854 | <p>Implementing fork() depends on having a Memory Management Unit. With an | ||
| 855 | MMU then you can simply set up a second set of page tables and share the | ||
| 856 | physical memory via copy-on-write. So a fork() followed quickly by exec() | ||
| 857 | only copies a few pages of the parent's memory, just the ones it changes | ||
| 858 | before freeing them.</p> | ||
| 859 | |||
| 860 | <p>With a very primitive MMU (using a base pointer plus length instead of page | ||
| 861 | tables, which can provide virtual addresses and protect processes from each | ||
| 862 | other, but no copy on write) you can still implement fork. But it's | ||
| 863 | unreasonably expensive, because you have to copy all the parent process' | ||
| 864 | memory into the new process (which could easily be several megabytes per fork). | ||
| 865 | And you have to do this even though that memory gets freed again as soon as the | ||
| 866 | exec happens. (This is not just slow and a waste of space but causes memory | ||
| 867 | usage spikes that can easily cause the system to run out of memory.)</p> | ||
| 868 | |||
| 869 | <p>Without even a primitive MMU, you have no virtual addresses. Every process | ||
| 870 | can reach out and touch any other process' memory, because all pointers are to | ||
| 871 | physical addresses with no protection. Even if you copy a process' memory to | ||
| 872 | new physical addresses, all of its pointers point to the old objects in the | ||
| 873 | old process. (Searching through the new copy's memory for pointers and | ||
| 874 | redirect them to the new locations is not an easy problem.)</p> | ||
| 875 | |||
| 876 | <p>So with a primitive or missing MMU, fork() is just not a good idea.</p> | ||
| 877 | |||
| 878 | <p>In theory, vfork() is just a fork() that writeably shares the heap and stack | ||
| 879 | rather than copying it (so what one process writes the other one sees). In | ||
| 880 | practice, vfork() has to suspend the parent process until the child does exec, | ||
| 881 | at which point the parent wakes up and resumes by returning from the call to | ||
| 882 | vfork(). All modern kernel/libc combinations implement vfork() to put the | ||
| 883 | parent to sleep until the child does its exec. There's just no other way to | ||
| 884 | make it work: the parent has to know the child has done its exec() or exit() | ||
| 885 | before it's safe to return from the function it's in, so it has to block | ||
| 886 | until that happens. In fact without suspending the parent there's no way to | ||
| 887 | even store separate copies of the return value (the pid) from the vfork() call | ||
| 888 | itself: both assignments write into the same memory location.</p> | ||
| 889 | |||
| 890 | <p>One way to understand (and in fact implement) vfork() is this: imagine | ||
| 891 | the parent does a setjmp and then continues on (pretending to be the child) | ||
| 892 | until the exec() comes around, then the _exec_ does the actual fork, and the | ||
| 893 | parent does a longjmp back to the original vfork call and continues on from | ||
| 894 | there. (It thus becomes obvious why the child can't return, or modify | ||
| 895 | local variables it doesn't want the parent to see changed when it resumes.) | ||
| 896 | |||
| 897 | <p>Note a common mistake: the need for vfork doesn't mean you can't have two | ||
| 898 | processes running at the same time. It means you can't have two processes | ||
| 899 | sharing the same memory without stomping all over each other. As soon as | ||
| 900 | the child calls exec(), the parent resumes.</p> | ||
| 901 | |||
| 902 | <p>If the child's attempt to call exec() fails, the child should call _exit() | ||
| 903 | rather than a normal exit(). This avoids any atexit() code that might confuse | ||
| 904 | the parent. (The parent should never call _exit(), only a vforked child that | ||
| 905 | failed to exec.)</p> | ||
| 906 | |||
| 907 | <p>(Now in theory, a nommu system could just copy the _stack_ when it forks | ||
| 908 | (which presumably is much shorter than the heap), and leave the heap shared. | ||
| 909 | Even with no MMU at all | ||
| 910 | In practice, you've just wound up in a multi-threaded situation and you can't | ||
| 911 | do a malloc() or free() on your heap without freeing the other process' memory | ||
| 912 | (and if you don't have the proper locking for being threaded, corrupting the | ||
| 913 | heap if both of you try to do it at the same time and wind up stomping on | ||
| 914 | each other while traversing the free memory lists). The thing about vfork is | ||
| 915 | that it's a big red flag warning "there be dragons here" rather than | ||
| 916 | something subtle and thus even more dangerous.)</p> | ||
| 917 | |||
| 918 | <h2><a name="tips_sort_read">Short reads and writes</a></h2> | ||
| 919 | |||
| 920 | <p>Busybox has special functions, bb_full_read() and bb_full_write(), to | ||
| 921 | check that all the data we asked for got read or written. Is this a real | ||
| 922 | world consideration? Try the following:</p> | ||
| 923 | |||
| 924 | <pre>while true; do echo hello; sleep 1; done | tee out.txt</pre> | ||
| 925 | |||
| 926 | <p>If tee is implemented with bb_full_read(), tee doesn't display output | ||
| 927 | in real time but blocks until its entire input buffer (generally a couple | ||
| 928 | kilobytes) is read, then displays it all at once. In that case, we _want_ | ||
| 929 | the short read, for user interface reasons. (Note that read() should never | ||
| 930 | return 0 unless it has hit the end of input, and an attempt to write 0 | ||
| 931 | bytes should be ignored by the OS.)</p> | ||
| 932 | |||
| 933 | <p>As for short writes, play around with two processes piping data to each | ||
| 934 | other on the command line (cat bigfile | gzip > out.gz) and suspend and | ||
| 935 | resume a few times (ctrl-z to suspend, "fg" to resume). The writer can | ||
| 936 | experience short writes, which are especially dangerous because if you don't | ||
| 937 | notice them you'll discard data. They can also happen when a system is under | ||
| 938 | load and a fast process is piping to a slower one. (Such as an xterm waiting | ||
| 939 | on x11 when the scheduler decides X is being a CPU hog with all that | ||
| 940 | text console scrolling...)</p> | ||
| 941 | |||
| 942 | <p>So will data always be read from the far end of a pipe at the | ||
| 943 | same chunk sizes it was written in? Nope. Don't rely on that. For one | ||
| 944 | counterexample, see <a href="http://www.faqs.org/rfcs/rfc896.html">rfc 896 | ||
| 945 | for Nagle's algorithm</a>, which waits a fraction of a second or so before | ||
| 946 | sending out small amounts of data through a TCP/IP connection in case more | ||
| 947 | data comes in that can be merged into the same packet. (In case you were | ||
| 948 | wondering why action games that use TCP/IP set TCP_NODELAY to lower the latency | ||
| 949 | on their their sockets, now you know.)</p> | ||
| 950 | |||
| 951 | <h2><a name="tips_memory">Memory used by relocatable code, PIC, and static linking.</a></h2> | ||
| 952 | |||
| 953 | <p>The downside of standard dynamic linking is that it results in self-modifying | ||
| 954 | code. Although each executable's pages are mmaped() into a process' address | ||
| 955 | space from the executable file and are thus naturally shared between processes | ||
| 956 | out of the page cache, the library loader (ld-linux.so.2 or ld-uClibc.so.0) | ||
| 957 | writes to these pages to supply addresses for relocatable symbols. This | ||
| 958 | dirties the pages, triggering copy-on-write allocation of new memory for each | ||
| 959 | processes' dirtied pages.</p> | ||
| 960 | |||
| 961 | <p>One solution to this is Position Independent Code (PIC), a way of linking | ||
| 962 | a file so all the relocations are grouped together. This dirties fewer | ||
| 963 | pages (often just a single page) for each process' relocations. The down | ||
| 964 | side is this results in larger executables, which take up more space on disk | ||
| 965 | (and a correspondingly larger space in memory). But when many copies of the | ||
| 966 | same program are running, PIC dynamic linking trades a larger disk footprint | ||
| 967 | for a smaller memory footprint, by sharing more pages.</p> | ||
| 968 | |||
| 969 | <p>A third solution is static linking. A statically linked program has no | ||
| 970 | relocations, and thus the entire executable is shared between all running | ||
| 971 | instances. This tends to have a significantly larger disk footprint, but | ||
| 972 | on a system with only one or two executables, shared libraries aren't much | ||
| 973 | of a win anyway.</p> | ||
| 974 | |||
| 975 | <p>You can tell the glibc linker to display debugging information about its | ||
| 976 | relocations with the environment variable "LD_DEBUG". Try | ||
| 977 | "LD_DEBUG=help /bin/true" for a list of commands. Learning to interpret | ||
| 978 | "LD_DEBUG=statistics cat /proc/self/statm" could be interesting.</p> | ||
| 979 | |||
| 980 | <p>For more on this topic, here's Rich Felker:</p> | ||
| 981 | <blockquote> | ||
| 982 | <p>Dynamic linking (without fixed load addresses) fundamentally requires | ||
| 983 | at least one dirty page per dso that uses symbols. Making calls (but | ||
| 984 | never taking the address explicitly) to functions within the same dso | ||
| 985 | does not require a dirty page by itself, but will with ELF unless you | ||
| 986 | use -Bsymbolic or hidden symbols when linking.</p> | ||
| 987 | |||
| 988 | <p>ELF uses significant additional stack space for the kernel to pass all | ||
| 989 | the ELF data structures to the newly created process image. These are | ||
| 990 | located above the argument list and environment. This normally adds 1 | ||
| 991 | dirty page to the process size.</p> | ||
| 992 | |||
| 993 | <p>The ELF dynamic linker has its own data segment, adding one or more | ||
| 994 | dirty pages. I believe it also performs relocations on itself.</p> | ||
| 995 | |||
| 996 | <p>The ELF dynamic linker makes significant dynamic allocations to manage | ||
| 997 | the global symbol table and the loaded dso's. This data is never | ||
| 998 | freed. It will be needed again if libdl is used, so unconditionally | ||
| 999 | freeing it is not possible, but normal programs do not use libdl. Of | ||
| 1000 | course with glibc all programs use libdl (due to nsswitch) so the | ||
| 1001 | issue was never addressed.</p> | ||
| 1002 | |||
| 1003 | <p>ELF also has the issue that segments are not page-aligned on disk. | ||
| 1004 | This saves up to 4k on disk, but at the expense of using an additional | ||
| 1005 | dirty page in most cases, due to a large portion of the first data | ||
| 1006 | page being filled with a duplicate copy of the last text page.</p> | ||
| 1007 | |||
| 1008 | <p>The above is just a partial list of the tiny memory penalties of ELF | ||
| 1009 | dynamic linking, which eventually add up to quite a bit. The smallest | ||
| 1010 | I've been able to get a process down to is 8 dirty pages, and the | ||
| 1011 | above factors seem to mostly account for it (but some were difficult | ||
| 1012 | to measure).</p> | ||
| 1013 | </blockquote> | ||
| 1014 | |||
| 1015 | <h2><a name="tips_kernel_headers"></a>Including kernel headers</h2> | ||
| 1016 | |||
| 1017 | <p>The "linux" or "asm" directories of /usr/include contain Linux kernel | ||
| 1018 | headers, so that the C library can talk directly to the Linux kernel. In | ||
| 1019 | a perfect world, applications shouldn't include these headers directly, but | ||
| 1020 | we don't live in a perfect world.</p> | ||
| 1021 | |||
| 1022 | <p>For example, Busybox's losetup code wants linux/loop.c because nothing else | ||
| 1023 | #defines the structures to call the kernel's loopback device setup ioctls. | ||
| 1024 | Attempts to cut and paste the information into a local busybox header file | ||
| 1025 | proved incredibly painful, because portions of the loop_info structure vary by | ||
| 1026 | architecture, namely the type __kernel_dev_t has different sizes on alpha, | ||
| 1027 | arm, x86, and so on. Meaning we either #include <linux/posix_types.h> or | ||
| 1028 | we hardwire #ifdefs to check what platform we're building on and define this | ||
| 1029 | type appropriately for every single hardware architecture supported by | ||
| 1030 | Linux, which is simply unworkable.</p> | ||
| 1031 | |||
| 1032 | <p>This is aside from the fact that the relevant type defined in | ||
| 1033 | posix_types.h was renamed to __kernel_old_dev_t during the 2.5 series, so | ||
| 1034 | to cut and paste the structure into our header we have to #include | ||
| 1035 | <linux/version.h> to figure out which name to use. (What we actually do is | ||
| 1036 | check if we're building on 2.6, and if so just use the new 64 bit structure | ||
| 1037 | instead to avoid the rename entirely.) But we still need the version | ||
| 1038 | check, since 2.4 didn't have the 64 bit structure.</p> | ||
| 1039 | |||
| 1040 | <p>The BusyBox developers spent <u>two years</u> trying to figure | ||
| 1041 | out a clean way to do all this. There isn't one. The losetup in the | ||
| 1042 | util-linux package from kernel.org isn't doing it cleanly either, they just | ||
| 1043 | hide the ugliness by nesting #include files. Their mount/loop.h | ||
| 1044 | #includes "my_dev_t.h", which #includes <linux/posix_types.h> and | ||
| 1045 | <linux/version.h> just like we do. There simply is no alternative.</p> | ||
| 1046 | |||
| 1047 | <p>Just because directly #including kernel headers is sometimes | ||
| 1048 | unavoidable doesn't me we should include them when there's a better | ||
| 1049 | way to do it. However, block copying information out of the kernel headers | ||
| 1050 | is not a better way.</p> | ||
| 1051 | |||
| 1052 | <h2><a name="who">Who are the BusyBox developers?</a></h2> | ||
| 1053 | |||
| 1054 | <p>The following login accounts currently exist on busybox.net. (I.E. these | ||
| 1055 | people can commit <a href="http://busybox.net/downloads/patches">patches</a> | ||
| 1056 | into subversion for the BusyBox, uClibc, and buildroot projects.)</p> | ||
| 1057 | |||
| 1058 | <pre> | ||
| 1059 | aldot :Bernhard Fischer | ||
| 1060 | andersen :Erik Andersen - uClibc and BuildRoot maintainer. | ||
| 1061 | bug1 :Glenn McGrath | ||
| 1062 | davidm :David McCullough | ||
| 1063 | gkajmowi :Garrett Kajmowicz - uClibc++ maintainer | ||
| 1064 | jbglaw :Jan-Benedict Glaw | ||
| 1065 | jocke :Joakim Tjernlund | ||
| 1066 | landley :Rob Landley - BusyBox maintainer | ||
| 1067 | lethal :Paul Mundt | ||
| 1068 | mjn3 :Manuel Novoa III | ||
| 1069 | osuadmin :osuadmin | ||
| 1070 | pgf :Paul Fox | ||
| 1071 | pkj :Peter Kjellerstedt | ||
| 1072 | prpplague :David Anders | ||
| 1073 | psm :Peter S. Mazinger | ||
| 1074 | russ :Russ Dill | ||
| 1075 | sandman :Robert Griebl | ||
| 1076 | sjhill :Steven J. Hill | ||
| 1077 | solar :Ned Ludd | ||
| 1078 | timr :Tim Riker | ||
| 1079 | tobiasa :Tobias Anderberg | ||
| 1080 | vapier :Mike Frysinger | ||
| 1081 | </pre> | ||
| 1082 | |||
| 1083 | <p>The following accounts used to exist on busybox.net, but don't anymore so | ||
| 1084 | I can't ask /etc/passwd for their names. Rob Wentworth <robwen@gmail.com> | ||
| 1085 | asked Google and recovered the names:</p> | ||
| 1086 | |||
| 1087 | <pre> | ||
| 1088 | aaronl :Aaron Lehmann | ||
| 1089 | beppu :John Beppu | ||
| 1090 | dwhedon :David Whedon | ||
| 1091 | erik :Erik Andersen | ||
| 1092 | gfeldman :Gennady Feldman | ||
| 1093 | jimg :Jim Gleason | ||
| 1094 | kraai :Matt Kraai | ||
| 1095 | markw :Mark Whitley | ||
| 1096 | miles :Miles Bader | ||
| 1097 | proski :Pavel Roskin | ||
| 1098 | rjune :Richard June | ||
| 1099 | tausq :Randolph Chung | ||
| 1100 | vodz :Vladimir N. Oleynik | ||
| 1101 | </pre> | ||
| 1102 | |||
| 1103 | |||
| 1104 | <br> | ||
| 1105 | <br> | ||
| 1106 | <br> | ||
| 1107 | |||
| 1108 | <!--#include file="footer.html" --> | ||
diff --git a/docs/busybox.net/about.html b/docs/busybox.net/about.html new file mode 100644 index 000000000..5272ee63c --- /dev/null +++ b/docs/busybox.net/about.html | |||
| @@ -0,0 +1,23 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | <h3>BusyBox: The Swiss Army Knife of Embedded Linux</h3> | ||
| 4 | |||
| 5 | <p>BusyBox combines tiny versions of many common UNIX utilities into a single | ||
| 6 | small executable. It provides replacements for most of the utilities you | ||
| 7 | usually find in GNU fileutils, shellutils, etc. The utilities in BusyBox | ||
| 8 | generally have fewer options than their full-featured GNU cousins; however, | ||
| 9 | the options that are included provide the expected functionality and behave | ||
| 10 | very much like their GNU counterparts. BusyBox provides a fairly complete | ||
| 11 | environment for any small or embedded system.</p> | ||
| 12 | |||
| 13 | <p>BusyBox has been written with size-optimization and limited resources in | ||
| 14 | mind. It is also extremely modular so you can easily include or exclude | ||
| 15 | commands (or features) at compile time. This makes it easy to customize | ||
| 16 | your embedded systems. To create a working system, just add some device | ||
| 17 | nodes in /dev, a few configuration files in /etc, and a Linux kernel.</p> | ||
| 18 | |||
| 19 | <p>BusyBox is maintained by <a href="http://www.landley.net/">Rob Landley</a>, | ||
| 20 | and licensed under the <a href="/license.html">GNU GENERAL PUBLIC LICENSE</a> | ||
| 21 | version 2 or later.</p> | ||
| 22 | |||
| 23 | <!--#include file="footer.html" --> | ||
diff --git a/docs/busybox.net/busybox-growth.ps b/docs/busybox.net/busybox-growth.ps new file mode 100644 index 000000000..2379defa4 --- /dev/null +++ b/docs/busybox.net/busybox-growth.ps | |||
| @@ -0,0 +1,404 @@ | |||
| 1 | %!PS-Adobe-2.0 | ||
| 2 | %%Title: busybox-growth.ps | ||
| 3 | %%Creator: gnuplot 3.5 (pre 3.6) patchlevel beta 347 | ||
| 4 | %%CreationDate: Tue Apr 10 14:03:36 2001 | ||
| 5 | %%DocumentFonts: (atend) | ||
| 6 | %%BoundingBox: 50 40 554 770 | ||
| 7 | %%Orientation: Landscape | ||
| 8 | %%Pages: (atend) | ||
| 9 | %%EndComments | ||
| 10 | /gnudict 120 dict def | ||
| 11 | gnudict begin | ||
| 12 | /Color true def | ||
| 13 | /Solid true def | ||
| 14 | /gnulinewidth 5.000 def | ||
| 15 | /userlinewidth gnulinewidth def | ||
| 16 | /vshift -46 def | ||
| 17 | /dl {10 mul} def | ||
| 18 | /hpt_ 31.5 def | ||
| 19 | /vpt_ 31.5 def | ||
| 20 | /hpt hpt_ def | ||
| 21 | /vpt vpt_ def | ||
| 22 | /M {moveto} bind def | ||
| 23 | /L {lineto} bind def | ||
| 24 | /R {rmoveto} bind def | ||
| 25 | /V {rlineto} bind def | ||
| 26 | /vpt2 vpt 2 mul def | ||
| 27 | /hpt2 hpt 2 mul def | ||
| 28 | /Lshow { currentpoint stroke M | ||
| 29 | 0 vshift R show } def | ||
| 30 | /Rshow { currentpoint stroke M | ||
| 31 | dup stringwidth pop neg vshift R show } def | ||
| 32 | /Cshow { currentpoint stroke M | ||
| 33 | dup stringwidth pop -2 div vshift R show } def | ||
| 34 | /UP { dup vpt_ mul /vpt exch def hpt_ mul /hpt exch def | ||
| 35 | /hpt2 hpt 2 mul def /vpt2 vpt 2 mul def } def | ||
| 36 | /DL { Color {setrgbcolor Solid {pop []} if 0 setdash } | ||
| 37 | {pop pop pop Solid {pop []} if 0 setdash} ifelse } def | ||
| 38 | /BL { stroke gnulinewidth 2 mul setlinewidth } def | ||
| 39 | /AL { stroke gnulinewidth 2 div setlinewidth } def | ||
| 40 | /UL { gnulinewidth mul /userlinewidth exch def } def | ||
| 41 | /PL { stroke userlinewidth setlinewidth } def | ||
| 42 | /LTb { BL [] 0 0 0 DL } def | ||
| 43 | /LTa { AL [1 dl 2 dl] 0 setdash 0 0 0 setrgbcolor } def | ||
| 44 | /LT0 { PL [] 1 0 0 DL } def | ||
| 45 | /LT1 { PL [4 dl 2 dl] 0 1 0 DL } def | ||
| 46 | /LT2 { PL [2 dl 3 dl] 0 0 1 DL } def | ||
| 47 | /LT3 { PL [1 dl 1.5 dl] 1 0 1 DL } def | ||
| 48 | /LT4 { PL [5 dl 2 dl 1 dl 2 dl] 0 1 1 DL } def | ||
| 49 | /LT5 { PL [4 dl 3 dl 1 dl 3 dl] 1 1 0 DL } def | ||
| 50 | /LT6 { PL [2 dl 2 dl 2 dl 4 dl] 0 0 0 DL } def | ||
| 51 | /LT7 { PL [2 dl 2 dl 2 dl 2 dl 2 dl 4 dl] 1 0.3 0 DL } def | ||
| 52 | /LT8 { PL [2 dl 2 dl 2 dl 2 dl 2 dl 2 dl 2 dl 4 dl] 0.5 0.5 0.5 DL } def | ||
| 53 | /Pnt { stroke [] 0 setdash | ||
| 54 | gsave 1 setlinecap M 0 0 V stroke grestore } def | ||
| 55 | /Dia { stroke [] 0 setdash 2 copy vpt add M | ||
| 56 | hpt neg vpt neg V hpt vpt neg V | ||
| 57 | hpt vpt V hpt neg vpt V closepath stroke | ||
| 58 | Pnt } def | ||
| 59 | /Pls { stroke [] 0 setdash vpt sub M 0 vpt2 V | ||
| 60 | currentpoint stroke M | ||
| 61 | hpt neg vpt neg R hpt2 0 V stroke | ||
| 62 | } def | ||
| 63 | /Box { stroke [] 0 setdash 2 copy exch hpt sub exch vpt add M | ||
| 64 | 0 vpt2 neg V hpt2 0 V 0 vpt2 V | ||
| 65 | hpt2 neg 0 V closepath stroke | ||
| 66 | Pnt } def | ||
| 67 | /Crs { stroke [] 0 setdash exch hpt sub exch vpt add M | ||
| 68 | hpt2 vpt2 neg V currentpoint stroke M | ||
| 69 | hpt2 neg 0 R hpt2 vpt2 V stroke } def | ||
| 70 | /TriU { stroke [] 0 setdash 2 copy vpt 1.12 mul add M | ||
| 71 | hpt neg vpt -1.62 mul V | ||
| 72 | hpt 2 mul 0 V | ||
| 73 | hpt neg vpt 1.62 mul V closepath stroke | ||
| 74 | Pnt } def | ||
| 75 | /Star { 2 copy Pls Crs } def | ||
| 76 | /BoxF { stroke [] 0 setdash exch hpt sub exch vpt add M | ||
| 77 | 0 vpt2 neg V hpt2 0 V 0 vpt2 V | ||
| 78 | hpt2 neg 0 V closepath fill } def | ||
| 79 | /TriUF { stroke [] 0 setdash vpt 1.12 mul add M | ||
| 80 | hpt neg vpt -1.62 mul V | ||
| 81 | hpt 2 mul 0 V | ||
| 82 | hpt neg vpt 1.62 mul V closepath fill } def | ||
| 83 | /TriD { stroke [] 0 setdash 2 copy vpt 1.12 mul sub M | ||
| 84 | hpt neg vpt 1.62 mul V | ||
| 85 | hpt 2 mul 0 V | ||
| 86 | hpt neg vpt -1.62 mul V closepath stroke | ||
| 87 | Pnt } def | ||
| 88 | /TriDF { stroke [] 0 setdash vpt 1.12 mul sub M | ||
| 89 | hpt neg vpt 1.62 mul V | ||
| 90 | hpt 2 mul 0 V | ||
| 91 | hpt neg vpt -1.62 mul V closepath fill} def | ||
| 92 | /DiaF { stroke [] 0 setdash vpt add M | ||
| 93 | hpt neg vpt neg V hpt vpt neg V | ||
| 94 | hpt vpt V hpt neg vpt V closepath fill } def | ||
| 95 | /Pent { stroke [] 0 setdash 2 copy gsave | ||
| 96 | translate 0 hpt M 4 {72 rotate 0 hpt L} repeat | ||
| 97 | closepath stroke grestore Pnt } def | ||
| 98 | /PentF { stroke [] 0 setdash gsave | ||
| 99 | translate 0 hpt M 4 {72 rotate 0 hpt L} repeat | ||
| 100 | closepath fill grestore } def | ||
| 101 | /Circle { stroke [] 0 setdash 2 copy | ||
| 102 | hpt 0 360 arc stroke Pnt } def | ||
| 103 | /CircleF { stroke [] 0 setdash hpt 0 360 arc fill } def | ||
| 104 | /C0 { BL [] 0 setdash 2 copy moveto vpt 90 450 arc } bind def | ||
| 105 | /C1 { BL [] 0 setdash 2 copy moveto | ||
| 106 | 2 copy vpt 0 90 arc closepath fill | ||
| 107 | vpt 0 360 arc closepath } bind def | ||
| 108 | /C2 { BL [] 0 setdash 2 copy moveto | ||
| 109 | 2 copy vpt 90 180 arc closepath fill | ||
| 110 | vpt 0 360 arc closepath } bind def | ||
| 111 | /C3 { BL [] 0 setdash 2 copy moveto | ||
| 112 | 2 copy vpt 0 180 arc closepath fill | ||
| 113 | vpt 0 360 arc closepath } bind def | ||
| 114 | /C4 { BL [] 0 setdash 2 copy moveto | ||
| 115 | 2 copy vpt 180 270 arc closepath fill | ||
| 116 | vpt 0 360 arc closepath } bind def | ||
| 117 | /C5 { BL [] 0 setdash 2 copy moveto | ||
| 118 | 2 copy vpt 0 90 arc | ||
| 119 | 2 copy moveto | ||
| 120 | 2 copy vpt 180 270 arc closepath fill | ||
| 121 | vpt 0 360 arc } bind def | ||
| 122 | /C6 { BL [] 0 setdash 2 copy moveto | ||
| 123 | 2 copy vpt 90 270 arc closepath fill | ||
| 124 | vpt 0 360 arc closepath } bind def | ||
| 125 | /C7 { BL [] 0 setdash 2 copy moveto | ||
| 126 | 2 copy vpt 0 270 arc closepath fill | ||
| 127 | vpt 0 360 arc closepath } bind def | ||
| 128 | /C8 { BL [] 0 setdash 2 copy moveto | ||
| 129 | 2 copy vpt 270 360 arc closepath fill | ||
| 130 | vpt 0 360 arc closepath } bind def | ||
| 131 | /C9 { BL [] 0 setdash 2 copy moveto | ||
| 132 | 2 copy vpt 270 450 arc closepath fill | ||
| 133 | vpt 0 360 arc closepath } bind def | ||
| 134 | /C10 { BL [] 0 setdash 2 copy 2 copy moveto vpt 270 360 arc closepath fill | ||
| 135 | 2 copy moveto | ||
| 136 | 2 copy vpt 90 180 arc closepath fill | ||
| 137 | vpt 0 360 arc closepath } bind def | ||
| 138 | /C11 { BL [] 0 setdash 2 copy moveto | ||
| 139 | 2 copy vpt 0 180 arc closepath fill | ||
| 140 | 2 copy moveto | ||
| 141 | 2 copy vpt 270 360 arc closepath fill | ||
| 142 | vpt 0 360 arc closepath } bind def | ||
| 143 | /C12 { BL [] 0 setdash 2 copy moveto | ||
| 144 | 2 copy vpt 180 360 arc closepath fill | ||
| 145 | vpt 0 360 arc closepath } bind def | ||
| 146 | /C13 { BL [] 0 setdash 2 copy moveto | ||
| 147 | 2 copy vpt 0 90 arc closepath fill | ||
| 148 | 2 copy moveto | ||
| 149 | 2 copy vpt 180 360 arc closepath fill | ||
| 150 | vpt 0 360 arc closepath } bind def | ||
| 151 | /C14 { BL [] 0 setdash 2 copy moveto | ||
| 152 | 2 copy vpt 90 360 arc closepath fill | ||
| 153 | vpt 0 360 arc } bind def | ||
| 154 | /C15 { BL [] 0 setdash 2 copy vpt 0 360 arc closepath fill | ||
| 155 | vpt 0 360 arc closepath } bind def | ||
| 156 | /Rec { newpath 4 2 roll moveto 1 index 0 rlineto 0 exch rlineto | ||
| 157 | neg 0 rlineto closepath } bind def | ||
| 158 | /Square { dup Rec } bind def | ||
| 159 | /Bsquare { vpt sub exch vpt sub exch vpt2 Square } bind def | ||
| 160 | /S0 { BL [] 0 setdash 2 copy moveto 0 vpt rlineto BL Bsquare } bind def | ||
| 161 | /S1 { BL [] 0 setdash 2 copy vpt Square fill Bsquare } bind def | ||
| 162 | /S2 { BL [] 0 setdash 2 copy exch vpt sub exch vpt Square fill Bsquare } bind def | ||
| 163 | /S3 { BL [] 0 setdash 2 copy exch vpt sub exch vpt2 vpt Rec fill Bsquare } bind def | ||
| 164 | /S4 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt Square fill Bsquare } bind def | ||
| 165 | /S5 { BL [] 0 setdash 2 copy 2 copy vpt Square fill | ||
| 166 | exch vpt sub exch vpt sub vpt Square fill Bsquare } bind def | ||
| 167 | /S6 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt vpt2 Rec fill Bsquare } bind def | ||
| 168 | /S7 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt vpt2 Rec fill | ||
| 169 | 2 copy vpt Square fill | ||
| 170 | Bsquare } bind def | ||
| 171 | /S8 { BL [] 0 setdash 2 copy vpt sub vpt Square fill Bsquare } bind def | ||
| 172 | /S9 { BL [] 0 setdash 2 copy vpt sub vpt vpt2 Rec fill Bsquare } bind def | ||
| 173 | /S10 { BL [] 0 setdash 2 copy vpt sub vpt Square fill 2 copy exch vpt sub exch vpt Square fill | ||
| 174 | Bsquare } bind def | ||
| 175 | /S11 { BL [] 0 setdash 2 copy vpt sub vpt Square fill 2 copy exch vpt sub exch vpt2 vpt Rec fill | ||
| 176 | Bsquare } bind def | ||
| 177 | /S12 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt2 vpt Rec fill Bsquare } bind def | ||
| 178 | /S13 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt2 vpt Rec fill | ||
| 179 | 2 copy vpt Square fill Bsquare } bind def | ||
| 180 | /S14 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt2 vpt Rec fill | ||
| 181 | 2 copy exch vpt sub exch vpt Square fill Bsquare } bind def | ||
| 182 | /S15 { BL [] 0 setdash 2 copy Bsquare fill Bsquare } bind def | ||
| 183 | /D0 { gsave translate 45 rotate 0 0 S0 stroke grestore } bind def | ||
| 184 | /D1 { gsave translate 45 rotate 0 0 S1 stroke grestore } bind def | ||
| 185 | /D2 { gsave translate 45 rotate 0 0 S2 stroke grestore } bind def | ||
| 186 | /D3 { gsave translate 45 rotate 0 0 S3 stroke grestore } bind def | ||
| 187 | /D4 { gsave translate 45 rotate 0 0 S4 stroke grestore } bind def | ||
| 188 | /D5 { gsave translate 45 rotate 0 0 S5 stroke grestore } bind def | ||
| 189 | /D6 { gsave translate 45 rotate 0 0 S6 stroke grestore } bind def | ||
| 190 | /D7 { gsave translate 45 rotate 0 0 S7 stroke grestore } bind def | ||
| 191 | /D8 { gsave translate 45 rotate 0 0 S8 stroke grestore } bind def | ||
| 192 | /D9 { gsave translate 45 rotate 0 0 S9 stroke grestore } bind def | ||
| 193 | /D10 { gsave translate 45 rotate 0 0 S10 stroke grestore } bind def | ||
| 194 | /D11 { gsave translate 45 rotate 0 0 S11 stroke grestore } bind def | ||
| 195 | /D12 { gsave translate 45 rotate 0 0 S12 stroke grestore } bind def | ||
| 196 | /D13 { gsave translate 45 rotate 0 0 S13 stroke grestore } bind def | ||
| 197 | /D14 { gsave translate 45 rotate 0 0 S14 stroke grestore } bind def | ||
| 198 | /D15 { gsave translate 45 rotate 0 0 S15 stroke grestore } bind def | ||
| 199 | /DiaE { stroke [] 0 setdash vpt add M | ||
| 200 | hpt neg vpt neg V hpt vpt neg V | ||
| 201 | hpt vpt V hpt neg vpt V closepath stroke } def | ||
| 202 | /BoxE { stroke [] 0 setdash exch hpt sub exch vpt add M | ||
| 203 | 0 vpt2 neg V hpt2 0 V 0 vpt2 V | ||
| 204 | hpt2 neg 0 V closepath stroke } def | ||
| 205 | /TriUE { stroke [] 0 setdash vpt 1.12 mul add M | ||
| 206 | hpt neg vpt -1.62 mul V | ||
| 207 | hpt 2 mul 0 V | ||
| 208 | hpt neg vpt 1.62 mul V closepath stroke } def | ||
| 209 | /TriDE { stroke [] 0 setdash vpt 1.12 mul sub M | ||
| 210 | hpt neg vpt 1.62 mul V | ||
| 211 | hpt 2 mul 0 V | ||
| 212 | hpt neg vpt -1.62 mul V closepath stroke } def | ||
| 213 | /PentE { stroke [] 0 setdash gsave | ||
| 214 | translate 0 hpt M 4 {72 rotate 0 hpt L} repeat | ||
| 215 | closepath stroke grestore } def | ||
| 216 | /CircE { stroke [] 0 setdash | ||
| 217 | hpt 0 360 arc stroke } def | ||
| 218 | /Opaque { gsave closepath 1 setgray fill grestore 0 setgray closepath } def | ||
| 219 | /DiaW { stroke [] 0 setdash vpt add M | ||
| 220 | hpt neg vpt neg V hpt vpt neg V | ||
| 221 | hpt vpt V hpt neg vpt V Opaque stroke } def | ||
| 222 | /BoxW { stroke [] 0 setdash exch hpt sub exch vpt add M | ||
| 223 | 0 vpt2 neg V hpt2 0 V 0 vpt2 V | ||
| 224 | hpt2 neg 0 V Opaque stroke } def | ||
| 225 | /TriUW { stroke [] 0 setdash vpt 1.12 mul add M | ||
| 226 | hpt neg vpt -1.62 mul V | ||
| 227 | hpt 2 mul 0 V | ||
| 228 | hpt neg vpt 1.62 mul V Opaque stroke } def | ||
| 229 | /TriDW { stroke [] 0 setdash vpt 1.12 mul sub M | ||
| 230 | hpt neg vpt 1.62 mul V | ||
| 231 | hpt 2 mul 0 V | ||
| 232 | hpt neg vpt -1.62 mul V Opaque stroke } def | ||
| 233 | /PentW { stroke [] 0 setdash gsave | ||
| 234 | translate 0 hpt M 4 {72 rotate 0 hpt L} repeat | ||
| 235 | Opaque stroke grestore } def | ||
| 236 | /CircW { stroke [] 0 setdash | ||
| 237 | hpt 0 360 arc Opaque stroke } def | ||
| 238 | /BoxFill { gsave Rec 1 setgray fill grestore } def | ||
| 239 | end | ||
| 240 | %%EndProlog | ||
| 241 | %%Page: 1 1 | ||
| 242 | gnudict begin | ||
| 243 | gsave | ||
| 244 | 50 50 translate | ||
| 245 | 0.100 0.100 scale | ||
| 246 | 90 rotate | ||
| 247 | 0 -5040 translate | ||
| 248 | 0 setgray | ||
| 249 | newpath | ||
| 250 | (Helvetica) findfont 140 scalefont setfont | ||
| 251 | 1.000 UL | ||
| 252 | LTb | ||
| 253 | 560 420 M | ||
| 254 | 63 0 V | ||
| 255 | 6409 0 R | ||
| 256 | -63 0 V | ||
| 257 | 476 420 M | ||
| 258 | (0) Rshow | ||
| 259 | 560 1056 M | ||
| 260 | 63 0 V | ||
| 261 | 6409 0 R | ||
| 262 | -63 0 V | ||
| 263 | -6493 0 R | ||
| 264 | (100) Rshow | ||
| 265 | 560 1692 M | ||
| 266 | 63 0 V | ||
| 267 | 6409 0 R | ||
| 268 | -63 0 V | ||
| 269 | -6493 0 R | ||
| 270 | (200) Rshow | ||
| 271 | 560 2328 M | ||
| 272 | 63 0 V | ||
| 273 | 6409 0 R | ||
| 274 | -63 0 V | ||
| 275 | -6493 0 R | ||
| 276 | (300) Rshow | ||
| 277 | 560 2964 M | ||
| 278 | 63 0 V | ||
| 279 | 6409 0 R | ||
| 280 | -63 0 V | ||
| 281 | -6493 0 R | ||
| 282 | (400) Rshow | ||
| 283 | 560 3600 M | ||
| 284 | 63 0 V | ||
| 285 | 6409 0 R | ||
| 286 | -63 0 V | ||
| 287 | -6493 0 R | ||
| 288 | (500) Rshow | ||
| 289 | 560 4236 M | ||
| 290 | 63 0 V | ||
| 291 | 6409 0 R | ||
| 292 | -63 0 V | ||
| 293 | -6493 0 R | ||
| 294 | (600) Rshow | ||
| 295 | 560 4872 M | ||
| 296 | 63 0 V | ||
| 297 | 6409 0 R | ||
| 298 | -63 0 V | ||
| 299 | -6493 0 R | ||
| 300 | (700) Rshow | ||
| 301 | 1531 420 M | ||
| 302 | 0 63 V | ||
| 303 | 0 4389 R | ||
| 304 | 0 -63 V | ||
| 305 | 0 -4529 R | ||
| 306 | (400) Cshow | ||
| 307 | 2825 420 M | ||
| 308 | 0 63 V | ||
| 309 | 0 4389 R | ||
| 310 | 0 -63 V | ||
| 311 | 0 -4529 R | ||
| 312 | (600) Cshow | ||
| 313 | 4120 420 M | ||
| 314 | 0 63 V | ||
| 315 | 0 4389 R | ||
| 316 | 0 -63 V | ||
| 317 | 0 -4529 R | ||
| 318 | (800) Cshow | ||
| 319 | 5414 420 M | ||
| 320 | 0 63 V | ||
| 321 | 0 4389 R | ||
| 322 | 0 -63 V | ||
| 323 | 0 -4529 R | ||
| 324 | (1000) Cshow | ||
| 325 | 6708 420 M | ||
| 326 | 0 63 V | ||
| 327 | 0 4389 R | ||
| 328 | 0 -63 V | ||
| 329 | 0 -4529 R | ||
| 330 | (1200) Cshow | ||
| 331 | 1.000 UL | ||
| 332 | LTb | ||
| 333 | 560 420 M | ||
| 334 | 6472 0 V | ||
| 335 | 0 4452 V | ||
| 336 | -6472 0 V | ||
| 337 | 560 420 L | ||
| 338 | 0 2646 M | ||
| 339 | currentpoint gsave translate 90 rotate 0 0 M | ||
| 340 | (tar.gz size \(Kb\)) Cshow | ||
| 341 | grestore | ||
| 342 | 3796 140 M | ||
| 343 | (time \(days since Jan 1, 1998\)) Cshow | ||
| 344 | 1.000 UL | ||
| 345 | LT0 | ||
| 346 | 696 420 M | ||
| 347 | 0 593 V | ||
| 348 | 1255 0 V | ||
| 349 | 0 15 V | ||
| 350 | 214 0 V | ||
| 351 | 0 6 V | ||
| 352 | 958 0 V | ||
| 353 | 0 1 V | ||
| 354 | -84 0 V | ||
| 355 | 0 37 V | ||
| 356 | 168 0 V | ||
| 357 | 0 262 V | ||
| 358 | 13 0 V | ||
| 359 | 0 56 V | ||
| 360 | 91 0 V | ||
| 361 | 0 33 V | ||
| 362 | 6 0 V | ||
| 363 | 0 1 V | ||
| 364 | 19 0 V | ||
| 365 | 0 11 V | ||
| 366 | 20 0 V | ||
| 367 | 0 13 V | ||
| 368 | 32 0 V | ||
| 369 | 0 104 V | ||
| 370 | 52 0 V | ||
| 371 | 0 27 V | ||
| 372 | 65 0 V | ||
| 373 | 0 15 V | ||
| 374 | 39 0 V | ||
| 375 | 0 126 V | ||
| 376 | 174 0 V | ||
| 377 | 0 103 V | ||
| 378 | 52 0 V | ||
| 379 | 0 49 V | ||
| 380 | 175 0 V | ||
| 381 | 0 56 V | ||
| 382 | 433 0 V | ||
| 383 | 0 661 V | ||
| 384 | 415 0 V | ||
| 385 | 0 857 V | ||
| 386 | 123 0 V | ||
| 387 | 0 -291 V | ||
| 388 | 498 0 V | ||
| 389 | 0 208 V | ||
| 390 | 505 0 V | ||
| 391 | 0 66 V | ||
| 392 | 291 0 V | ||
| 393 | 0 115 V | ||
| 394 | 311 0 V | ||
| 395 | 0 449 V | ||
| 396 | 162 0 V | ||
| 397 | 0 309 V | ||
| 398 | stroke | ||
| 399 | grestore | ||
| 400 | end | ||
| 401 | showpage | ||
| 402 | %%Trailer | ||
| 403 | %%DocumentFonts: Helvetica | ||
| 404 | %%Pages: 1 | ||
diff --git a/docs/busybox.net/copyright.txt b/docs/busybox.net/copyright.txt new file mode 100644 index 000000000..397475632 --- /dev/null +++ b/docs/busybox.net/copyright.txt | |||
| @@ -0,0 +1,30 @@ | |||
| 1 | |||
| 2 | The code and graphics on this website (and it's mirror sites, if any) are | ||
| 3 | Copyright (c) 1999-2004 by Erik Andersen. All rights reserved. | ||
| 4 | Copyright (c) 2005-2006 Rob Landley. | ||
| 5 | |||
| 6 | Documents on this Web site including their graphical elements, design, and | ||
| 7 | layout are protected by trade dress and other laws and MAY BE COPIED OR | ||
| 8 | IMITATED IN WHOLE OR IN PART. THIS WEBSITE IS LICENSED FREE OF CHARGE, THERE | ||
| 9 | IS NO WARRANTY FOR THE WEBSITE TO THE EXTENT PERMITTED BY APPLICABLE LAW. | ||
| 10 | SHOULD THIS WEBSITE PROVE DEFECTIVE, YOU MAY ASSUME THAT SOMEONE MIGHT GET | ||
| 11 | AROUND TO SERVICING, REPAIRING OR CORRECTING IT SOMETIME WHEN THEY HAVE NOTHING | ||
| 12 | BETTER TO DO. REGARDLESS, YOU GET TO KEEP BOTH PIECES. | ||
| 13 | |||
| 14 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY | ||
| 15 | COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THIS | ||
| 16 | WEBSITE AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY | ||
| 17 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR | ||
| 18 | INABILITY TO USE THIS WEBSITE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR | ||
| 19 | LOSS OF HAIR, LOSS OF LIFE, LOSS OF MEMORY, LOSS OF YOUR CARKEYS, MISPLACEMENT | ||
| 20 | OF YOUR PAYCHECK, OR COMMANDER DATA BEING RENDERED UNABLE TO ASSIST THE | ||
| 21 | STARFLEET OFFICERS ABORD THE STARSHIP ENTERPRISE TO RECALIBRATE THE MAIN | ||
| 22 | DEFLECTOR ARRAY, LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE | ||
| 23 | WEBSITE TO OPERATE WITH YOUR WEBBROWSER), EVEN IF SUCH HOLDER OR OTHER PARTY | ||
| 24 | HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. | ||
| 25 | |||
| 26 | You have been warned. | ||
| 27 | |||
| 28 | You can contact the webmaster at <rob@landley.net> if you have some sort | ||
| 29 | of problem with this. | ||
| 30 | |||
diff --git a/docs/busybox.net/developer.html b/docs/busybox.net/developer.html new file mode 100644 index 000000000..cdb68b78c --- /dev/null +++ b/docs/busybox.net/developer.html | |||
| @@ -0,0 +1,69 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | <h3>Morris Dancing</h3> | ||
| 4 | |||
| 5 | <p>Subversion commit access requires an account on Morris. The server | ||
| 6 | behind busybox.net and uclibc.org. If you want to be able to commit things to | ||
| 7 | Subversion, first contribute some stuff to show you are serious, can handle | ||
| 8 | some responsibility, and that your patches don't generally need a lot of | ||
| 9 | cleanup. Then, very nicely ask one of us (<a href="mailto:rob@landley.net">Rob | ||
| 10 | Landley</a> for BusyBox, or <a href="mailto:andersen@codepoet.org">Erik | ||
| 11 | Andersen</a> for uClibc) for an account.</p> | ||
| 12 | |||
| 13 | <p>If you're approved for an account, you'll need to send an email from your | ||
| 14 | preferred contact email address with the username you'd like to use when | ||
| 15 | committing changes to SVN, and attach a public ssh key to access your account | ||
| 16 | with.</p> | ||
| 17 | |||
| 18 | <p>If you don't currently have an ssh version 2 DSA key at least 1024 bits | ||
| 19 | long (the default), you can generate a key using the | ||
| 20 | command <b>ssh-keygen -t dsa</b> and hitting enter at the prompts. This | ||
| 21 | will create the files <b>~/.ssh/id_dsa</b> and <b>~/.ssh/id_dsa.pub</b> | ||
| 22 | You must then send the content of 'id_dsa.pub' to me so I can set up your | ||
| 23 | account. (The content of 'id_dsa' should of course be kept secret, anyone | ||
| 24 | who has that can access any account that's installed your public key in | ||
| 25 | its <b>.ssh/authorized_keys</b> file.)</p> | ||
| 26 | |||
| 27 | <p>Note that if you would prefer to keep your communications with us | ||
| 28 | private, you can encrypt your email using | ||
| 29 | <a href="http://landley.net/pubkey.gpg">Rob's public key</a> or | ||
| 30 | <a href="http://www.codepoet.org/andersen/erik/gpg.asc">Erik's public | ||
| 31 | key</a>.</p> | ||
| 32 | |||
| 33 | <p>Once you are setup with an account, you will need to use your account to | ||
| 34 | checkout a copy of BusyBox from Subversion:</p> | ||
| 35 | |||
| 36 | <p><b>svn checkout svn+ssh://username@busybox.net/svn/trunk/busybox</b></p> | ||
| 37 | <p>or</p> | ||
| 38 | <p><b>svn checkout svn+ssh://username@uclibc.org/svn/trunk/uclibc</b></p> | ||
| 39 | |||
| 40 | <p>You must change <em>username</em> to your own username, or omit | ||
| 41 | it if it's the same as your local username.</p> | ||
| 42 | |||
| 43 | <p>You can then enter the newly checked out project directory, make changes, | ||
| 44 | check your changes, diff your changes, revert your changes, and and commit your | ||
| 45 | changes using commands such as:</p> | ||
| 46 | |||
| 47 | <b><pre> | ||
| 48 | svn diff | ||
| 49 | svn status | ||
| 50 | svn revert | ||
| 51 | EDITOR=vi svn commit | ||
| 52 | svn log -v -r PREV:HEAD | ||
| 53 | svn help | ||
| 54 | </pre></b> | ||
| 55 | |||
| 56 | <p>For additional detail on how to use Subversion, please visit the | ||
| 57 | <a href="http://subversion.tigris.org/">the Subversion website</a>. | ||
| 58 | You might also want to read online or buy a copy of <a | ||
| 59 | href="http://svnbook.red-bean.com/">the Subversion Book</a>...</p> | ||
| 60 | |||
| 61 | <p>A morris account also gives you a personal web page | ||
| 62 | (http://busybox.net/~username comes from ~/public_html on morris), and of | ||
| 63 | course a shell prompt you can ssh into (as a regular user, root access is | ||
| 64 | reserved for Erik and Rob). But keep in mind an account on Morris is a | ||
| 65 | priviledge, not a requirement. Most contributors to busybox and uClibc | ||
| 66 | haven't got one, and accounts are handed out to make the project maintainers' | ||
| 67 | lives easier, not because "you deserve it".</p> | ||
| 68 | |||
| 69 | <!--#include file="footer.html" --> | ||
diff --git a/docs/busybox.net/download.html b/docs/busybox.net/download.html new file mode 100644 index 000000000..f8746ddab --- /dev/null +++ b/docs/busybox.net/download.html | |||
| @@ -0,0 +1,29 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | |||
| 4 | |||
| 5 | <h3>Download</h3> | ||
| 6 | |||
| 7 | Source for the latest release can always be | ||
| 8 | downloaded from <a href="downloads">http://www.busybox.net/downloads</a>. | ||
| 9 | |||
| 10 | <p> | ||
| 11 | You can also obtain <a href= "downloads/snapshots/">Daily Snapshots</a> of | ||
| 12 | the latest development source tree for those wishing to follow BusyBox development, | ||
| 13 | but cannot or do not wish to use Subversion (svn). | ||
| 14 | |||
| 15 | <ul> | ||
| 16 | <li> Click here to <a href="/cgi-bin/viewcvs.cgi/trunk/busybox/">browse the source tree</a>. | ||
| 17 | </li> | ||
| 18 | |||
| 19 | <li>Anonymous <a href="subversion.html">Subversion access</a> is available. | ||
| 20 | </li> | ||
| 21 | |||
| 22 | <li>For those that are actively contributing obtaining | ||
| 23 | <a href="developer.html">Subversion read/write access</a> is also possible. | ||
| 24 | </li> | ||
| 25 | |||
| 26 | </ul> | ||
| 27 | |||
| 28 | <!--#include file="footer.html" --> | ||
| 29 | |||
diff --git a/docs/busybox.net/footer.html b/docs/busybox.net/footer.html new file mode 100644 index 000000000..5f2335a2b --- /dev/null +++ b/docs/busybox.net/footer.html | |||
| @@ -0,0 +1,47 @@ | |||
| 1 | <!-- Footer --> | ||
| 2 | |||
| 3 | |||
| 4 | </td> | ||
| 5 | </tr> | ||
| 6 | </table> | ||
| 7 | |||
| 8 | <hr /> | ||
| 9 | |||
| 10 | |||
| 11 | <table width="100%"> | ||
| 12 | <tr> | ||
| 13 | <td width="60%"> | ||
| 14 | <font face="arial, helvetica, sans-serif" size="-1"> | ||
| 15 | <a href="/copyright.txt">Copyright © 1999-2005 Erik Andersen</a> | ||
| 16 | <br> | ||
| 17 | Mail all comments, insults, suggestions and bribes to | ||
| 18 | <br> | ||
| 19 | Denis Vlasenko <a href="mailto:vda.linux@googlemail.com">vda.linux@googlemail.com</a><br> | ||
| 20 | </font> | ||
| 21 | </td> | ||
| 22 | |||
| 23 | <td> | ||
| 24 | <a href="http://www.vim.org/"><img border=0 width=88 height=31 | ||
| 25 | src="images/written.in.vi.png" | ||
| 26 | alt="This site created with the vi editor"></a> | ||
| 27 | </td> | ||
| 28 | |||
| 29 | <td> | ||
| 30 | <a href="http://osuosl.org/"><img border=0 width=114 height=63 | ||
| 31 | src="images/osuosl.png" | ||
| 32 | alt="This site is kindly hosted by OSL"></a> | ||
| 33 | </td> | ||
| 34 | <!-- | ||
| 35 | <td> | ||
| 36 | <a href="http://validator.w3.org/check?uri=referer"><img | ||
| 37 | border="0" height="31" width="88" | ||
| 38 | src="images/valid-html401.png" | ||
| 39 | alt="Valid HTML"></a> | ||
| 40 | </td> | ||
| 41 | --> | ||
| 42 | </TR> | ||
| 43 | </table> | ||
| 44 | |||
| 45 | </body> | ||
| 46 | </html> | ||
| 47 | |||
diff --git a/docs/busybox.net/header.html b/docs/busybox.net/header.html new file mode 100644 index 000000000..081f18c7f --- /dev/null +++ b/docs/busybox.net/header.html | |||
| @@ -0,0 +1,96 @@ | |||
| 1 | <!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN'> | ||
| 2 | |||
| 3 | <html> | ||
| 4 | <head> | ||
| 5 | <meta http-equiv='Content-Type' content='text/html; charset=iso-8859-1'> | ||
| 6 | <title>BusyBox</title> | ||
| 7 | <style type="text/css"> | ||
| 8 | body { | ||
| 9 | background-color: #DEE2DE; | ||
| 10 | color: #000000; | ||
| 11 | } | ||
| 12 | :link { color: #660000 } | ||
| 13 | :visited { color: #660000 } | ||
| 14 | :active { color: #660000 } | ||
| 15 | td.c2 {font-family: arial, helvetica, sans-serif; font-size: 80%} | ||
| 16 | td.c1 {font-family: lucida, helvetica; font-size: 248%} | ||
| 17 | </style> | ||
| 18 | </head> | ||
| 19 | |||
| 20 | <body> | ||
| 21 | <basefont face="lucida, helvetica, arial" size="3"> | ||
| 22 | |||
| 23 | |||
| 24 | |||
| 25 | |||
| 26 | <table border="0" cellpadding="0" cellspacing="0"> | ||
| 27 | |||
| 28 | |||
| 29 | <tr> | ||
| 30 | <td> | ||
| 31 | <div class="c3"> | ||
| 32 | <table border="0" cellspacing="1" cellpadding="2"> | ||
| 33 | <tr> | ||
| 34 | <td class="c1">BUSYBOX</td> | ||
| 35 | </tr> | ||
| 36 | </table> | ||
| 37 | </div> | ||
| 38 | |||
| 39 | <a href="/"><IMG SRC="images/busybox1.png" alt="BusyBox" border="0"></a><BR> | ||
| 40 | </td> | ||
| 41 | </tr> | ||
| 42 | |||
| 43 | <tr> | ||
| 44 | |||
| 45 | <td valign="TOP"> | ||
| 46 | <b>About</b> | ||
| 47 | <ul> | ||
| 48 | <li><a href="about.html">About BusyBox</a></li> | ||
| 49 | <li><a href="screenshot.html">Screenshot</a></li> | ||
| 50 | <li><a href="news.html">Announcements</a></li> | ||
| 51 | <li><a href="downloads/news">BusyBox Weekly News</a></li> | ||
| 52 | </ul> | ||
| 53 | <b>Documentation</b> | ||
| 54 | <ul> | ||
| 55 | <li><a href="FAQ.html">FAQ</a></li> | ||
| 56 | <li><a href="downloads/BusyBox.html">Command Help</a></li> | ||
| 57 | <li><a href="downloads/README">README</a></li> | ||
| 58 | </ul> | ||
| 59 | <b>Get BusyBox</b> | ||
| 60 | <ul> | ||
| 61 | <li><a href="download.html">Download Source</a></li> | ||
| 62 | <li><a href="license.html">License</a></li> | ||
| 63 | <li><a href="products.html">Products</a></li> | ||
| 64 | </ul> | ||
| 65 | <b>Development</b> | ||
| 66 | <ul> | ||
| 67 | <li><a href="/cgi-bin/viewcvs.cgi/trunk/busybox/">Browse Source</a></li> | ||
| 68 | <li><a href="subversion.html">Source Control</a></li> | ||
| 69 | <li><a href="/downloads/patches/recent.html">Recent Changes</a></li> | ||
| 70 | <li><a href="lists.html">Mailing Lists</a></li> | ||
| 71 | <li><a href="http://bugs.busybox.net/">Bug Tracking</a></li> | ||
| 72 | </ul> | ||
| 73 | <p><b>Links</b> | ||
| 74 | <ul> | ||
| 75 | <li><a href="links.html">Related Sites</a></li> | ||
| 76 | <li><a href="tinyutils.html">Tiny Utilities</a></li> | ||
| 77 | <li><a href="sponsors.html">Sponsors</a></li> | ||
| 78 | </ul> | ||
| 79 | <p><b>Developer Pages</b> | ||
| 80 | <ul> | ||
| 81 | <li><a href="http://busybox.net/~landley">Rob</a></li> | ||
| 82 | <li><a href="http://busybox.net/~aldot">Bernhard</a></li> | ||
| 83 | <li><a href="http://busybox.net/~vda">Denis</a></li> | ||
| 84 | </ul> | ||
| 85 | |||
| 86 | <!-- | ||
| 87 | <a href="http://validator.w3.org/check/referer"><img | ||
| 88 | src="/images/vh40.gif" height=31 width=88 | ||
| 89 | align=left border=0 alt="Valid HTML 4.0!"></a> | ||
| 90 | --> | ||
| 91 | |||
| 92 | </td> | ||
| 93 | |||
| 94 | |||
| 95 | <td Valign="TOP"> | ||
| 96 | |||
diff --git a/docs/busybox.net/images/back.png b/docs/busybox.net/images/back.png new file mode 100644 index 000000000..79923869b --- /dev/null +++ b/docs/busybox.net/images/back.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/busybox.jpeg b/docs/busybox.net/images/busybox.jpeg new file mode 100644 index 000000000..37edc9614 --- /dev/null +++ b/docs/busybox.net/images/busybox.jpeg | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/busybox.png b/docs/busybox.net/images/busybox.png new file mode 100644 index 000000000..b1eb92f38 --- /dev/null +++ b/docs/busybox.net/images/busybox.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/busybox1.png b/docs/busybox.net/images/busybox1.png new file mode 100644 index 000000000..4d3126a52 --- /dev/null +++ b/docs/busybox.net/images/busybox1.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/busybox2.jpg b/docs/busybox.net/images/busybox2.jpg new file mode 100644 index 000000000..abf8f0610 --- /dev/null +++ b/docs/busybox.net/images/busybox2.jpg | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/busybox3.jpg b/docs/busybox.net/images/busybox3.jpg new file mode 100644 index 000000000..0fab84cf9 --- /dev/null +++ b/docs/busybox.net/images/busybox3.jpg | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/dir.png b/docs/busybox.net/images/dir.png new file mode 100644 index 000000000..1d633ce4a --- /dev/null +++ b/docs/busybox.net/images/dir.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/donate.png b/docs/busybox.net/images/donate.png new file mode 100644 index 000000000..b55621bb9 --- /dev/null +++ b/docs/busybox.net/images/donate.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/fm.mini.png b/docs/busybox.net/images/fm.mini.png new file mode 100644 index 000000000..c0883cd34 --- /dev/null +++ b/docs/busybox.net/images/fm.mini.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/gfx_by_gimp.png b/docs/busybox.net/images/gfx_by_gimp.png new file mode 100644 index 000000000..d58314034 --- /dev/null +++ b/docs/busybox.net/images/gfx_by_gimp.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/ltbutton2.png b/docs/busybox.net/images/ltbutton2.png new file mode 100644 index 000000000..9bad9496a --- /dev/null +++ b/docs/busybox.net/images/ltbutton2.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/osuosl.png b/docs/busybox.net/images/osuosl.png new file mode 100644 index 000000000..b00b5007d --- /dev/null +++ b/docs/busybox.net/images/osuosl.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/sdsmall.png b/docs/busybox.net/images/sdsmall.png new file mode 100644 index 000000000..b1024501b --- /dev/null +++ b/docs/busybox.net/images/sdsmall.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/text.png b/docs/busybox.net/images/text.png new file mode 100644 index 000000000..6034f899f --- /dev/null +++ b/docs/busybox.net/images/text.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/valid-html401.png b/docs/busybox.net/images/valid-html401.png new file mode 100644 index 000000000..ec9bc0ce0 --- /dev/null +++ b/docs/busybox.net/images/valid-html401.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/vh40.gif b/docs/busybox.net/images/vh40.gif new file mode 100644 index 000000000..c5e9402e7 --- /dev/null +++ b/docs/busybox.net/images/vh40.gif | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/images/written.in.vi.png b/docs/busybox.net/images/written.in.vi.png new file mode 100644 index 000000000..84f59bc15 --- /dev/null +++ b/docs/busybox.net/images/written.in.vi.png | |||
| Binary files differ | |||
diff --git a/docs/busybox.net/index.html b/docs/busybox.net/index.html new file mode 100644 index 000000000..1bab6b069 --- /dev/null +++ b/docs/busybox.net/index.html | |||
| @@ -0,0 +1 @@ | |||
| <!--#include file="news.html" --> | |||
diff --git a/docs/busybox.net/license.html b/docs/busybox.net/license.html new file mode 100644 index 000000000..76358bc65 --- /dev/null +++ b/docs/busybox.net/license.html | |||
| @@ -0,0 +1,97 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | <p> | ||
| 4 | <h3>BusyBox is licensed under the GNU General Public License, version 2</h3> | ||
| 5 | |||
| 6 | <p>BusyBox is licensed under <a href="http://www.gnu.org/licenses/gpl.html#SEC1">the | ||
| 7 | GNU General Public License</a> version 2, which is often abbreviated as GPLv2. | ||
| 8 | (This is the same license the Linux kernel is under, so you may be somewhat | ||
| 9 | familiar with it by now.)</p> | ||
| 10 | |||
| 11 | <p>A complete copy of the license text is included in the file LICENSE in | ||
| 12 | the BusyBox source code.</p> | ||
| 13 | |||
| 14 | <p><a href="/products.html">Anyone thinking of shipping BusyBox as part of a | ||
| 15 | product</a> should be familiar with the licensing terms under which they are | ||
| 16 | allowed to use and distribute BusyBox. Read the full test of the GPL (either | ||
| 17 | through the above link, or in the file LICENSE in the busybox tarball), and | ||
| 18 | also read the <a href="http://www.gnu.org/licenses/gpl-faq.html">Frequently | ||
| 19 | Asked Questions about the GPL</a>.</p> | ||
| 20 | |||
| 21 | <p>Basically, if you distribute GPL software the license requires that you also | ||
| 22 | distribute the source code to that GPL-licensed software. So if you distribute | ||
| 23 | BusyBox without making the source code to the version you distribute available, | ||
| 24 | you violate the license terms, and thus infringe on the copyrights of BusyBox. | ||
| 25 | (This requirement applies whether or not you modified BusyBox; either way the | ||
| 26 | license terms still apply to you.) Read the license text for the details.</p> | ||
| 27 | |||
| 28 | <h3>A note on GPL versions</h3> | ||
| 29 | |||
| 30 | <p>Version 2 of the GPL is the only version of the GPL which current versions | ||
| 31 | of BusyBox may be distributed under. New code added to the tree is licensed | ||
| 32 | GPL version 2, and the project's license is GPL version 2.</p> | ||
| 33 | |||
| 34 | <p>Older versions of BusyBox (versions 1.2.2 and earlier, up through about svn | ||
| 35 | 16112) included variants of the recommended "GPL version 2 or (at your option) | ||
| 36 | later versions" boilerplate permission grant. Ancient versions of BusyBox | ||
| 37 | (before svn 49) did not specify any version at all, and section 9 of GPLv2 | ||
| 38 | (the most recent version at the time) says those old versions may be | ||
| 39 | redistributed under any version of GPL (including the obsolete V1). This was | ||
| 40 | conceptually similar to a dual license, except that the different licenses were | ||
| 41 | different versions of the GPL.</p> | ||
| 42 | |||
| 43 | <p>However, BusyBox has apparently always contained chunks of code that were | ||
| 44 | licensed under GPL version 2 only. Examples include applets written by Linus | ||
| 45 | Torvalds (util-linux/mkfs_minix.c and util_linux/mkswap.c) which stated they | ||
| 46 | "may be redistributed as per the Linux copyright" (which Linus clarified in the | ||
| 47 | 2.4.0-pre8 release announcement in 2000 was GPLv2 only), and Linux kernel code | ||
| 48 | copied into libbb/loop.c (after Linus's announcement). There are probably | ||
| 49 | more, because all we used to check was that the code was GPL, not which | ||
| 50 | version. (Before the GPLv3 draft proceedings in 2006, it was a purely | ||
| 51 | theoretical issue that didn't come up much.)</p> | ||
| 52 | |||
| 53 | <p>To summarize: every version of BusyBox may be distributed under the terms of | ||
| 54 | GPL version 2. New versions (after 1.2.2) may <b>only</b> be distributed under | ||
| 55 | GPLv2, not under other versions of the GPL. Older versions of BusyBox might | ||
| 56 | (or might not) be distributable under other versions of the GPL. If you | ||
| 57 | want to use a GPL version other than 2, you should start with one of the old | ||
| 58 | versions such as release 1.2.2 or SVN 16112, and do your own homework to | ||
| 59 | identify and remove any code that can't be licensed under the GPL version you | ||
| 60 | want to use. New development is all GPLv2.</p> | ||
| 61 | |||
| 62 | <h3>License enforcement</h3> | ||
| 63 | |||
| 64 | <p>BusyBox's copyrights are enforced by the <a | ||
| 65 | href="http://www.softwarefreedom.org">Software Freedom Law Center</a> | ||
| 66 | (you can contact them at gpl@busybox.net), which | ||
| 67 | "accepts primary responsibility for enforcement of US copyrights on the | ||
| 68 | software... and coordinates international copyright enforcement efforts for | ||
| 69 | such works as necessary." If you distribute BusyBox in a way that doesn't | ||
| 70 | comply with the terms of the license BusyBox is distributed under, expect to | ||
| 71 | hear from these guys. Their entire reason for existing is to do pro-bono | ||
| 72 | legal work for free/open source software projects. (We used to list people who | ||
| 73 | violate the BusyBox license in <a href="/shame.html">The Hall of Shame</a>, | ||
| 74 | but these days we find it much more effective to hand them over to the | ||
| 75 | lawyers.)</p> | ||
| 76 | |||
| 77 | <p>Our enforcement efforts are aimed at bringing people into compliance with | ||
| 78 | the BusyBox license. Open source software is under a different license from | ||
| 79 | proprietary software, but if you violate that license you're still a software | ||
| 80 | pirate and the law gives the vendor (us) some big sticks to play with. We | ||
| 81 | don't want monetary awards, injunctions, or to generate bad PR for a company, | ||
| 82 | unless that's the only way to get somebody that repeatedly ignores us to comply | ||
| 83 | with the license on our code.</p> | ||
| 84 | |||
| 85 | <h3>A Good Example</h3> | ||
| 86 | |||
| 87 | <p>These days, <a href="http://www.linksys.com/">Linksys</a> is | ||
| 88 | doing a good job at complying with the GPL, they get to be an | ||
| 89 | example of how to do things right. Please take a moment and | ||
| 90 | check out what they do with | ||
| 91 | <a href="http://www.linksys.com/servlet/Satellite?c=L_Content_C1&childpagename=US%2FLayout&cid=1115416836002&pagename=Linksys%2FCommon%2FVisitorWrapper"> | ||
| 92 | distributing the firmware for their WRT54G Router.</a> | ||
| 93 | Following their example would be a fine way to ensure that you | ||
| 94 | have also fulfilled your licensing obligations.</p> | ||
| 95 | |||
| 96 | <!--#include file="footer.html" --> | ||
| 97 | |||
diff --git a/docs/busybox.net/links.html b/docs/busybox.net/links.html new file mode 100644 index 000000000..9cdbd7c8c --- /dev/null +++ b/docs/busybox.net/links.html | |||
| @@ -0,0 +1,19 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | <h3>Related Sites</h3> | ||
| 4 | |||
| 5 | <br><a href="http://uclibc.org/">uClibc.org</a> | ||
| 6 | <br><a href="http://cxx.uclibc.org/">uClibc++</a> | ||
| 7 | <br><a href="http://udhcp.busybox.net/">udhcp</a> | ||
| 8 | <br><a href="http://buildroot.uclibc.org/">buildroot</a> | ||
| 9 | <br><a href="http://www.scratchbox.org/">Scratchbox</a> | ||
| 10 | <br><a href="http://openembedded.org/">OpenEmbedded</a> | ||
| 11 | <br><a href="http://www.ucdot.org/">uCdot</a> | ||
| 12 | <br><a href="http://www.linuxdevices.com">LinuxDevices</a> | ||
| 13 | <br><a href="http://slashdot.org/">Slashdot</a> | ||
| 14 | <br><a href="http://freshmeat.net/">Freshmeat</a> | ||
| 15 | <br><a href="http://linuxtoday.com/">Linux Today</a> | ||
| 16 | <br><a href="http://lwn.net/">Linux Weekly News</a> | ||
| 17 | <br><a href="http://www.tldp.org/HOWTO">Linux HOWTOs</a> | ||
| 18 | |||
| 19 | <!--#include file="footer.html" --> | ||
diff --git a/docs/busybox.net/lists.html b/docs/busybox.net/lists.html new file mode 100644 index 000000000..3a28cc07e --- /dev/null +++ b/docs/busybox.net/lists.html | |||
| @@ -0,0 +1,46 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | |||
| 4 | <!-- Begin Introduction section --> | ||
| 5 | |||
| 6 | <h3>Mailing List Information</h3> | ||
| 7 | BusyBox has a <a href="/lists/busybox/">mailing list</a> for discussion and | ||
| 8 | development. You can subscribe by visiting | ||
| 9 | <a href="http://busybox.net/mailman/listinfo/busybox">this page</a>. | ||
| 10 | Only subscribers to the BusyBox mailing list are allowed to post | ||
| 11 | to this list. | ||
| 12 | |||
| 13 | <p> | ||
| 14 | There is also a mailing list for <a href="/lists/busybox-cvs/">active developers</a> | ||
| 15 | wishing to read the complete diff of each and every change to busybox -- not for the | ||
| 16 | faint of heart. Active developers can subscribe by visiting | ||
| 17 | <a href="http://busybox.net/mailman/listinfo/busybox-cvs">this page</a>. | ||
| 18 | The Subversion server is the only one permtted to post to this list. And yes, | ||
| 19 | this list name uses the word 'cvs' even though we don't use that anymore... | ||
| 20 | |||
| 21 | <p> | ||
| 22 | |||
| 23 | |||
| 24 | <h3>Search the List Archives</h3> | ||
| 25 | Please search the mailing list archives before asking questions on the mailing | ||
| 26 | list, since there is a good chance someone else has asked the same question | ||
| 27 | before. Checking the archives is a great way to avoid annoying everyone on the | ||
| 28 | list with frequently asked questions... | ||
| 29 | <p> | ||
| 30 | |||
| 31 | <center> | ||
| 32 | <form method="GET" action="http://www.google.com/custom"> | ||
| 33 | <input type="hidden" name="domains" value="busybox.net"> | ||
| 34 | <input type="hidden" name="sitesearch" value="busybox.net"> | ||
| 35 | <input type="text" name="q" size="31" maxlength="255" value=""> | ||
| 36 | <br> | ||
| 37 | <input type="submit" name="sa" value="search the mailing list archives"> | ||
| 38 | <br> | ||
| 39 | <a href="http://www.google.com"><img src="http://www.google.com/logos/Logo_25wht.gif" border="0" alt="Google" height="32" width="75" align="middle"></a> | ||
| 40 | <br> | ||
| 41 | </form> | ||
| 42 | </center> | ||
| 43 | |||
| 44 | |||
| 45 | |||
| 46 | <!--#include file="footer.html" --> | ||
diff --git a/docs/busybox.net/news.html b/docs/busybox.net/news.html new file mode 100644 index 000000000..375519925 --- /dev/null +++ b/docs/busybox.net/news.html | |||
| @@ -0,0 +1,185 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | |||
| 4 | <ul> | ||
| 5 | <li><b>14 December, 2006 -- BusyBox 1.3.0 (stable)</b> | ||
| 6 | <p><a href=http://busybox.net/downloads/busybox-1.3.0.tar.bz2>BusyBox 1.3.0</a>.</p> | ||
| 7 | |||
| 8 | <p>This release has CONFIG_DESKTOP option which enables features | ||
| 9 | needed for busybox usage on desktop machine. For example, find, chmod | ||
| 10 | and chown get several less frequently used options, od is significantly | ||
| 11 | bigger but matches GNU coreutils, etc. Intended to eventually make | ||
| 12 | busybox a viable alternative for "standard" utilities for slightly | ||
| 13 | adventurous desktop users. | ||
| 14 | <p>Changes since previous release: | ||
| 15 | <ul> | ||
| 16 | <li>find: taking many more of standard options | ||
| 17 | <li>ps: POSIX-compliant -o implemented | ||
| 18 | <li>cp: added -s, -l | ||
| 19 | <li>grep: added -r, fixed -h | ||
| 20 | <li>watch: make it exec child like standard one does (was totally | ||
| 21 | incompatible) | ||
| 22 | <li>tar: fix limitations which were preventing bbox tar usage | ||
| 23 | on a big directories: long names and linknames, pax headers | ||
| 24 | (Linux kernel tarballs have that). Fixed a number of obscure bugs. | ||
| 25 | Raised max file limit (now 64Gb). Security fixes (/../ attacks). | ||
| 26 | <li>httpd: added -i (inetd), -f (foreground), support for | ||
| 27 | directory indexer CGI (example is included), bugfixes. | ||
| 28 | <li>telnetd: fixed/improved IPv6 support, inetd+standalone support, | ||
| 29 | other fixes. Useful IPv6 stuff factored out into libbb. | ||
| 30 | <li>runit/*: new applets adapted from http://smarden.sunsite.dk/runit/ | ||
| 31 | (these are my personal favorite small-and-beautiful toys) | ||
| 32 | <li>minor bugfixes to: login, dd, mount, umount, chmod, chown, ln, udhcp, | ||
| 33 | fdisk, ifconfig, sort, tee, mkswap, wget, insmod. | ||
| 34 | </ul> | ||
| 35 | <p>Note that GnuPG key used to sign this release is different. | ||
| 36 | 1.2.2.1 is also signed post-factum now. Sorry for the mess. | ||
| 37 | </p> | ||
| 38 | </li> | ||
| 39 | |||
| 40 | <li><b>29 October, 2006 -- BusyBox 1.2.2.1 (fix)</b> | ||
| 41 | <p><a href=http://busybox.net/downloads/busybox-1.2.2.1.tar.bz2>BusyBox 1.2.2.1</a>.</p> | ||
| 42 | |||
| 43 | <p>Added compile-time warning that static linking against glibc | ||
| 44 | produces buggy executables. | ||
| 45 | </li> | ||
| 46 | |||
| 47 | <li><b>24 October, 2006 -- BusyBox 1.2.2 (stable)</b> | ||
| 48 | <p>It's a bit overdue, but | ||
| 49 | <a href=http://busybox.net/downloads/busybox-1.2.2.tar.bz2>here is | ||
| 50 | BusyBox 1.2.2</a>.</p> | ||
| 51 | |||
| 52 | <p>This release has dozens of fixes backported from the ongoing development | ||
| 53 | branch. There are a couple of bugfixes to sed, two fixes to documentation | ||
| 54 | generation (BusyBox.html shouldn't have USE() macros in it anymore), fix | ||
| 55 | umount to report the right errno on failure and to umount block devices by | ||
| 56 | name with newer kernels, fix mount to handle symlinks properly, make mdev | ||
| 57 | delete device nodes when called for hotplug remove, fix a segfault | ||
| 58 | in traceroute, a minor portability fix to md5sum option parsing, a build | ||
| 59 | fix for httpd with old gccs, an options parsing tweak to hdparm, make test | ||
| 60 | fail gracefully when getgroups() returns -1, fix a race condition in | ||
| 61 | modprobe when two instances run at once (hotplug does this), make "tar xf | ||
| 62 | foo.tar dir/dir" extract all subdirectories, make our getty initialize the | ||
| 63 | terminal more like mingetty, an selinux build fix, an endianness fix in | ||
| 64 | ping6, fix for zcip defending addresses, clean up some global variables in | ||
| 65 | gzip to save memory, fix sulogin -tNNN, a help text tweak, several warning | ||
| 66 | fixes and build fixes, fixup dnsd a bit, and a partridge in a pear tree.</p> | ||
| 67 | |||
| 68 | <p>As <a href=http://lwn.net/Articles/202106/>Linux Weekly News noted</a>, | ||
| 69 | this is my (Rob's) last release of BusyBox. The new maintainer is Denis | ||
| 70 | Vlasenko, I'm off to do <a href=http://landley.net/code>other things</a>. | ||
| 71 | </p> | ||
| 72 | </li> | ||
| 73 | |||
| 74 | <li><b>29 September, 2006 -- New license email address.</b> | ||
| 75 | <p>The email address gpl@busybox.net is now the recommended way to contact | ||
| 76 | the Software Freedom Law Center to report BusyBox license violations.</p> | ||
| 77 | |||
| 78 | <li><b>31 July 2006 -- BusyBox 1.2.1 (stable)</b> | ||
| 79 | <p>Since nobody seems to have objected too loudly over the weekend, I | ||
| 80 | might as well point you all at | ||
| 81 | <a href="http://busybox.net/downloads/busybox-1.2.1.tar.bz2">Busybox | ||
| 82 | 1.2.1</a>, a bugfix-only release with no new features.</p> | ||
| 83 | |||
| 84 | <p>It has three shell fixes (two to lash: going "var=value" without | ||
| 85 | saying "export" should now work, plus a missing null pointer check, and | ||
| 86 | one to ash when redirecting output to a file that fills up.) Fix three | ||
| 87 | embarassing thinkos in the new dmesg command. Two build tweaks | ||
| 88 | (dependencies for the compressed usage messages and running make in the | ||
| 89 | libbb subdirectory). One fix to tar so it can extract git-generated | ||
| 90 | tarballs (rather than barfing on the pax extensions). And a partridge | ||
| 91 | in a pear... Ahem.</p> | ||
| 92 | |||
| 93 | <p>But wait, there's more! A passwd changing fix so an empty | ||
| 94 | gecos field doesn't trigger a false objection that the new passwd contains | ||
| 95 | the gecos field. Make all our setuid() and setgid() calls check the return | ||
| 96 | value in case somebody's using per-process resource limits that prevent | ||
| 97 | a user from having too many processes (and thus prevent a process from | ||
| 98 | switching away from root, in which case the process will now _die_ rather | ||
| 99 | than continue with root privileges). A fix to adduser to make sure that | ||
| 100 | /etc/group gets updated. And a fix to modprobe to look for modules.conf | ||
| 101 | in the right place on 2.6 kernels.</p> | ||
| 102 | |||
| 103 | <li><b>30 June 2006 -- BusyBox 1.2.0</b> | ||
| 104 | <p>The -devel branch has been stabilized and the result is | ||
| 105 | <a href="http://busybox.net/downloads/busybox-1.2.0.tar.bz2">Busybox | ||
| 106 | 1.2.0</a>. Lots of stuff changed, I need to work up a decent changelog | ||
| 107 | over the weekend.</p> | ||
| 108 | |||
| 109 | <p>I'm still experimenting with how long is best for the development | ||
| 110 | cycle, and since we've got some largeish projects queued up I'm going to | ||
| 111 | try a longer one. Expect 1.3.0 in December. (Expect 1.2.1 any time | ||
| 112 | we fix enough bugs. :)</p> | ||
| 113 | |||
| 114 | <p>Update: Here are <a href="http://busybox.net/downloads/busybox-1.2.0.fixes.patch">the first few bug fixes</a> that will go into 1.2.1.</p> | ||
| 115 | |||
| 116 | <li><b>17 May 2006 -- BusyBox 1.1.3 (stable)</b> | ||
| 117 | <p><a href="http://busybox.net/downloads/busybox-1.1.3.tar.bz2">BusyBox | ||
| 118 | 1.1.3</a> is another bugfix release. It makes passwd use salt, fixes a | ||
| 119 | memory freeing bug in ls, fixes "build all sources at once" mode, makes | ||
| 120 | mount -a not abort on the first failure, fixes msh so ctrl-c doesn't kill | ||
| 121 | background processes, makes patch work with patch hunks that don't have a | ||
| 122 | timestamp, make less's text search a lot more robust (the old one could | ||
| 123 | segfault), and fixes readlink -f when built against uClibc.</p> | ||
| 124 | |||
| 125 | <p>Expect 1.2.0 sometime next month, which won't be a bugfix release.</p> | ||
| 126 | |||
| 127 | <li><b>10 April 2006 -- BusyBox 1.1.2 (stable)</b> | ||
| 128 | <p>You can now download <a href="http://busybox.net/downloads/busybox-1.1.2.tar.bz2">BusyBox 1.1.2</a>, a bug fix release consisting of 11 patches | ||
| 129 | backported from the development branch: Some build fixes, several fixes | ||
| 130 | for mount and nfsmount, a fix for insmod on big endian systems, a fix for | ||
| 131 | find -xdev, and a fix for comm. Check the file "changelog" in the tarball | ||
| 132 | for more info.</p> | ||
| 133 | |||
| 134 | <p>The next new development release (1.2.0) is slated for June. A 1.1.3 | ||
| 135 | will be released before then if more bug fixes crop up. (The new plan is | ||
| 136 | to have a 1.x.0 new development release every 3 months, with 1.x.y stable | ||
| 137 | bugfix only releases based on that as appropriate.)</p> | ||
| 138 | |||
| 139 | <li><b>27 March 2006 -- Software Freedom Law Center representing BusyBox and uClibc</b> | ||
| 140 | <p>One issue Erik Andersen wanted to resolve when handing off BusyBox | ||
| 141 | maintainership to Rob Landley was license enforcement. BusyBox and | ||
| 142 | uClibc's existing license enforcement efforts (pro-bono representation | ||
| 143 | by Erik's father's law firm, and the | ||
| 144 | <a href="http://www.busybox.net/shame.html">Hall of Shame</a>), haven't | ||
| 145 | scaled to match the popularity of the projects. So we put our heads | ||
| 146 | together and did the obvious thing: ask Pamela Jones of | ||
| 147 | <a href="http://www.groklaw.net">Groklaw</a> for suggestions. She | ||
| 148 | referred us to the fine folks at softwarefreedom.org.</p> | ||
| 149 | |||
| 150 | <p>As a result, we're pleased to announce that the | ||
| 151 | <a href="http://www.softwarefreedom.org">Software Freedom Law Center</a> | ||
| 152 | has agreed to represent BusyBox and uClibc. We join a number of other | ||
| 153 | free and open source software projects (such as | ||
| 154 | <a href="http://lwn.net/Articles/141806/">X.org</a>, | ||
| 155 | <a href="http://lwn.net/Articles/135413/">Wine</a>, and | ||
| 156 | <a href="http://plone.org/foundation/newsitems/software-freedom-law-center-support/">Plone</a> | ||
| 157 | in being represented by a fairly cool bunch of lawyers, which is not a | ||
| 158 | phrase you get to use every day.</p> | ||
| 159 | |||
| 160 | <li><b>22 March 2006 -- BusyBox 1.1.1</b> | ||
| 161 | <p>The new maintainer is Rob Landley, and the new release is <a href="http://busybox.net/downloads/busybox-1.1.1.tar.bz2">BusyBox 1.1.1</a>. Expect a "what's new" document in a few days. (Also, Erik and I have have another announcement pending...)</p> | ||
| 162 | <p>Update: Rather than put out an endless stream of 1.1.1.x releases, | ||
| 163 | the various small fixes have been collected together into a | ||
| 164 | <a href="http://busybox.net/downloads/busybox-1.1.1.fixes.patch">patch</a>, | ||
| 165 | and new fixes will be appended to that as needed. Expect 1.1.2 around | ||
| 166 | June.</p> | ||
| 167 | </li> | ||
| 168 | <li><b>11 January 2006 -- 1.1.0 is out</b> | ||
| 169 | <p>The new stable release is | ||
| 170 | <a href="http://www.busybox.net/downloads/busybox-1.1.0.tar.bz2">BusyBox | ||
| 171 | 1.1.0</a>. It has a number of improvements, including several new applets. | ||
| 172 | (It also has <a href="http://www.busybox.net/lists/busybox/2006-January/017733.html">a few rough spots</a>, | ||
| 173 | but we're trying out a "release early, release often" strategy to see how | ||
| 174 | that works. Expect 1.1.1 sometime in March.)</p> | ||
| 175 | |||
| 176 | <li><b>Old News</b><p> | ||
| 177 | <a href="/oldnews.html">Click here to read older news</a> | ||
| 178 | </p> | ||
| 179 | </li> | ||
| 180 | |||
| 181 | |||
| 182 | </ul> | ||
| 183 | |||
| 184 | <!--#include file="footer.html" --> | ||
| 185 | |||
diff --git a/docs/busybox.net/oldnews.html b/docs/busybox.net/oldnews.html new file mode 100644 index 000000000..1017b6975 --- /dev/null +++ b/docs/busybox.net/oldnews.html | |||
| @@ -0,0 +1,1140 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | |||
| 4 | <ul> | ||
| 5 | <li><b>31 October 2005 -- 1.1.0-pre1</b> | ||
| 6 | <p>The development branch of busybox is stable enough for wider testing, so | ||
| 7 | you can now | ||
| 8 | <a href="http://www.busybox.net/downloads/busybox-1.1.0-pre1.tar.bz2">download</a>, | ||
| 9 | the first prerelease of 1.1.0. This prerelease includes a lot of | ||
| 10 | <a href="http://www.busybox.net/downloads/BusyBox.html">new | ||
| 11 | functionality</a>: new applets, new features, and extensive rewrites of | ||
| 12 | several existing applets. This prerelease should be noticeably more | ||
| 13 | <a href="http://www.opengroup.org/onlinepubs/009695399/">standards | ||
| 14 | compliant</a> than earlier versions of busybox, although we're | ||
| 15 | still working out the <a href="http://bugs.busybox.net">bugs</a>.</p> | ||
| 16 | |||
| 17 | <li><b>16 August 2005 -- 1.01 is out</b> | ||
| 18 | |||
| 19 | <p>A new stable release (<a href="http://www.busybox.net/downloads/busybox-1.01.tar.bz2">BusyBox | ||
| 20 | 1.01</a>) is now available for download, containing over a hundred | ||
| 21 | <a href="http://www.busybox.net/lists/busybox/2005-August/015424.html">small | ||
| 22 | fixes</a> that have cropped up since the 1.00 release.</p> | ||
| 23 | |||
| 24 | <li><b>13 January 2005 -- Bug and Patch Tracking</b><p> | ||
| 25 | |||
| 26 | Bug reports sometimes get lost when posted to the mailing list. The | ||
| 27 | developers of BusyBox are busy people, and have only so much they can keep | ||
| 28 | in their brains at a time. In my case, I'm lucky if I can remember my own | ||
| 29 | name, much less a bug report posted last week... To prevent your bug report | ||
| 30 | from getting lost, if you find a bug in BusyBox, please use the | ||
| 31 | <a href="http://bugs.busybox.net/">shiny new Bug and Patch Tracking System</a> | ||
| 32 | to post all the gory details. | ||
| 33 | |||
| 34 | <p> | ||
| 35 | |||
| 36 | The same applies to patches... Regardless of whether your patch | ||
| 37 | is a bug fix or adds spiffy new features, please post your patch | ||
| 38 | to the Bug and Patch Tracking System to make certain it is | ||
| 39 | properly considered. | ||
| 40 | |||
| 41 | |||
| 42 | <p> | ||
| 43 | <li><b>13 October 2004 -- BusyBox 1.00 released</b><p> | ||
| 44 | |||
| 45 | When you take a careful look at nearly every embedded Linux device or | ||
| 46 | software distribution shipping today, you will find a copy of BusyBox. | ||
| 47 | With countless routers, set top boxes, wireless access points, PDAs, and | ||
| 48 | who knows what else, the future for Linux and BusyBox on embedded devices | ||
| 49 | is looking very bright. | ||
| 50 | |||
| 51 | <p> | ||
| 52 | |||
| 53 | It is therefore with great satisfaction that I declare each and every | ||
| 54 | device already shipping with BusyBox is now officially out of date. | ||
| 55 | The highly anticipated release of BusyBox 1.00 has arrived! | ||
| 56 | |||
| 57 | <p> | ||
| 58 | |||
| 59 | Over three years in development, BusyBox 1.00 represents a tremendous | ||
| 60 | improvement over the old 0.60.x stable series. Now featuring a Linux | ||
| 61 | KernelConf based configuration system (as used by the Linux kernel), | ||
| 62 | Linux 2.6 kernel support, many many new applets, and the development | ||
| 63 | work and testing of thousands of people from around the world. | ||
| 64 | |||
| 65 | <p> | ||
| 66 | |||
| 67 | If you are already using BusyBox, you are strongly encouraged to upgrade to | ||
| 68 | BusyBox 1.00. If you are considering developing an embedded Linux device | ||
| 69 | or software distribution, you may wish to investigate if using BusyBox is | ||
| 70 | right for your application. If you need help getting started using | ||
| 71 | BusyBox, if you wish to donate to help cover expenses, or if you find a bug | ||
| 72 | and need help reporting it, you are invited to visit the <a | ||
| 73 | href="FAQ.html">BusyBox FAQ</a>. | ||
| 74 | |||
| 75 | <p> | ||
| 76 | |||
| 77 | As usual you can <a href="downloads">download busybox here</a>. | ||
| 78 | |||
| 79 | <p>Have Fun! | ||
| 80 | |||
| 81 | <p> | ||
| 82 | <li><b>Old News</b><p> | ||
| 83 | <a href="/oldnews.html">Click here to read older news</a> | ||
| 84 | |||
| 85 | |||
| 86 | <li><b>16 August 2004 -- BusyBox 1.0.0-rc3 released</b><p> | ||
| 87 | |||
| 88 | Here goes release candidate 3... | ||
| 89 | <p> | ||
| 90 | The <a href="downloads/Changelog">changelog</a> has all the details. | ||
| 91 | And as usual you can <a href="downloads">download busybox here</a>. | ||
| 92 | |||
| 93 | <p>Have Fun! | ||
| 94 | |||
| 95 | <p> | ||
| 96 | <li><b>26 July 2004 -- BusyBox 1.0.0-rc2 released</b><p> | ||
| 97 | |||
| 98 | Here goes release candidate 2... | ||
| 99 | <p> | ||
| 100 | The <a href="downloads/Changelog">changelog</a> has all the details. | ||
| 101 | And as usual you can <a href="downloads">download busybox here</a>. | ||
| 102 | |||
| 103 | <p>Have Fun! | ||
| 104 | |||
| 105 | <p> | ||
| 106 | <li><b>20 July 2004 -- BusyBox 1.0.0-rc1 released</b><p> | ||
| 107 | |||
| 108 | Here goes release candidate 1... This fixes all (most?) of the problems | ||
| 109 | that have turned up since -pre10. In particular, loading and unloading of | ||
| 110 | kernel modules with 2.6.x kernels should be working much better. | ||
| 111 | <p> | ||
| 112 | |||
| 113 | I <b>really</b> want to get BusyBox 1.0.0 released soon and I see no real | ||
| 114 | reason why the 1.0.0 release shouldn't happen with things pretty much as | ||
| 115 | is. BusyBox is in good shape at the moment, and it works nicely for | ||
| 116 | everything that I'm doing with it. And from the reports I've been getting, | ||
| 117 | it works nicely for what most everyone else is doing with it as well. | ||
| 118 | There will eventually be a 1.0.1 anyway, so we might as well get on with | ||
| 119 | it. No, BusyBox is not perfect. No piece of software ever is. And while | ||
| 120 | there is still plenty that can be done to improve things, most of that work | ||
| 121 | is waiting till we can get a solid 1.0.0 release out the door.... | ||
| 122 | <p> | ||
| 123 | |||
| 124 | Please do not bother to send in patches adding cool new features at this | ||
| 125 | time. Only bug-fix patches will be accepted. If you have submitted a | ||
| 126 | bug-fixing patch to the busybox mailing list and no one has emailed you | ||
| 127 | explaining why your patch was rejected, it is safe to say that your patch | ||
| 128 | has been lost or forgotten. That happens sometimes. Please re-submit your | ||
| 129 | bug-fixing patch to the BusyBox mailing list, and be sure to put "[PATCH]" | ||
| 130 | at the beginning of the email subject line! | ||
| 131 | |||
| 132 | <p> | ||
| 133 | The <a href="downloads/Changelog">changelog</a> has all the details. | ||
| 134 | And as usual you can <a href="downloads">download busybox here</a>. | ||
| 135 | |||
| 136 | <p>Have Fun! | ||
| 137 | |||
| 138 | <p> | ||
| 139 | On a less happy note, My 92 year old grandmother (my dad's mom) passed away | ||
| 140 | yesterday (June 19th). The funeral will be Thursday in a little town about | ||
| 141 | 2 hours south of my home. I've checked and there is absolutely no way I | ||
| 142 | could be back in time for the funeral if I attend <a | ||
| 143 | href="http://www.linuxsymposium.org/2004/">OLS</a> and give my presentation | ||
| 144 | as scheduled. | ||
| 145 | <p> | ||
| 146 | As such, it is with great reluctance and sadness that I have come | ||
| 147 | to the conclusion I will have to make my appologies and skip OLS | ||
| 148 | this year. | ||
| 149 | <p> | ||
| 150 | |||
| 151 | |||
| 152 | <p> | ||
| 153 | <li><b>13 April 2004 -- BusyBox 1.0.0-pre10 released</b><p> | ||
| 154 | |||
| 155 | Ok, I lied. It turns out that -pre9 will not be the final BusyBox | ||
| 156 | pre-release. With any luck however -pre10 will be, since I <b>really</b> | ||
| 157 | want to get BusyBox 1.0.0 released very soon. As usual, please do not | ||
| 158 | bother to send in patches adding cool new features at this time. Only | ||
| 159 | bug-fix patches will be accepted. It would also be <b>very</b> helpful if | ||
| 160 | people could continue to review the BusyBox documentation and submit | ||
| 161 | improvements. | ||
| 162 | |||
| 163 | <p> | ||
| 164 | The <a href="downloads/Changelog">changelog</a> has all the details. | ||
| 165 | And as usual you can <a href="downloads">download busybox here</a>. | ||
| 166 | |||
| 167 | <p>Have Fun! | ||
| 168 | <p> | ||
| 169 | |||
| 170 | |||
| 171 | <p> | ||
| 172 | <li><b>6 April 2004 -- BusyBox 1.0.0-pre9 released</b><p> | ||
| 173 | |||
| 174 | Here goes the final BusyBox pre-release... This is your last chance for | ||
| 175 | bug fixes. With luck this will be released as BusyBox 1.0.0 later this | ||
| 176 | week. Please do not bother to send in patches adding cool new features at | ||
| 177 | this time. Only bug-fix patches will be accepted. It would also be | ||
| 178 | <b>very</b> helpful if people could help review the BusyBox documentation | ||
| 179 | and submit improvements. I've spent a lot of time updating the | ||
| 180 | documentation to make it better match reality, but I could really use some | ||
| 181 | assistance in checking that the features supported by the various applets | ||
| 182 | match the features listed in the documentation. | ||
| 183 | |||
| 184 | <p> | ||
| 185 | I had hoped to get this released a month ago, but | ||
| 186 | <a href="http://codepoet.org/gallery/baby_peter/img_1796"> | ||
| 187 | another release on 1 March 2004</a> has kept me busy... | ||
| 188 | |||
| 189 | <p> | ||
| 190 | The <a href="downloads/Changelog">changelog</a> has all the details. | ||
| 191 | And as usual you can <a href="downloads">download busybox here</a>. | ||
| 192 | |||
| 193 | <p>Have Fun! | ||
| 194 | <p> | ||
| 195 | |||
| 196 | |||
| 197 | <p> | ||
| 198 | <li><b>23 February 2004 -- BusyBox 1.0.0-pre8 released</b><p> | ||
| 199 | |||
| 200 | Here goes yet another BusyBox pre-release... Please do not bother to send | ||
| 201 | in patches supplying new features at this time. Only bug-fix patches will | ||
| 202 | be accepted. If you have a cool new feature you would like to see | ||
| 203 | supported, or if you have an amazing new applet you would like to submit, | ||
| 204 | please wait and submit such things later. We really want to get a release | ||
| 205 | out we can all be proud of. We are still aiming to finish off the -pre | ||
| 206 | series in February and move on to the final 1.0.0 release... So if you | ||
| 207 | spot any bugs, now would be an excellent time to send in a fix to the | ||
| 208 | busybox mailing list. It would also be <b>very</b> helpful if people could | ||
| 209 | help review the BusyBox documentation and submit improvements. It would be | ||
| 210 | especially helpful if people could check that the features supported by the | ||
| 211 | various applets match the features listed in the documentation. | ||
| 212 | |||
| 213 | <p> | ||
| 214 | |||
| 215 | The <a href="downloads/Changelog">changelog</a> has all the details. | ||
| 216 | And as usual you can <a href="downloads">download busybox here</a>. | ||
| 217 | |||
| 218 | <p>Have Fun! | ||
| 219 | <p> | ||
| 220 | |||
| 221 | |||
| 222 | <li><b>4 February 2004 -- BusyBox 1.0.0-pre7 released</b><p> | ||
| 223 | |||
| 224 | There was a bug in -pre6 that broke argument parsing for a | ||
| 225 | number of applets, since a variable was not being zeroed out | ||
| 226 | properly. This release is primarily intended to fix that one | ||
| 227 | problem. In addition, this release fixes several other | ||
| 228 | problems, including a rewrite by mjn3 of the code for parsing | ||
| 229 | the busybox.conf file used for suid handling, some shell updates | ||
| 230 | from vodz, and a scattering of other small fixes. We are still | ||
| 231 | aiming to finish off the -pre series in February and move on to | ||
| 232 | the final 1.0.0 release... If you see any problems, of have | ||
| 233 | suggestions to make, as always, please feel free to email the | ||
| 234 | busybox mailing list. | ||
| 235 | |||
| 236 | <p> | ||
| 237 | |||
| 238 | The <a href="downloads/Changelog">changelog</a> has all | ||
| 239 | the details. And as usual you can | ||
| 240 | <a href="downloads">download busybox here</a>. | ||
| 241 | |||
| 242 | <p>Have Fun! | ||
| 243 | <p> | ||
| 244 | |||
| 245 | |||
| 246 | <p> | ||
| 247 | <li><b>30 January 2004 -- BusyBox 1.0.0-pre6 released</b><p> | ||
| 248 | |||
| 249 | Here goes the next pre-release for the new BusyBox stable | ||
| 250 | series. This release adds a number of size optimizations, | ||
| 251 | updates udhcp, fixes up 2.6 modutils support, updates ash | ||
| 252 | and the shell command line editing, and the usual pile of | ||
| 253 | bug fixes both large and small. Things appear to be | ||
| 254 | settling down now, so with a bit of luck and some testing | ||
| 255 | perhaps we can finish off the -pre series in February and | ||
| 256 | move on to the final 1.0.0 release... If you see any | ||
| 257 | problems, of have suggestions to make, as always, please | ||
| 258 | feel free to email the busybox mailing list. | ||
| 259 | |||
| 260 | <p> | ||
| 261 | |||
| 262 | People who rely on the <a href= "downloads/snapshots/">daily BusyBox snapshots</a> | ||
| 263 | should be aware that snapshots of the old busybox 0.60.x | ||
| 264 | series are no longer available. Daily snapshots are now | ||
| 265 | only available for the BusyBox 1.0.0 series and now use | ||
| 266 | the naming scheme "busybox-<date>.tar.bz2". Please | ||
| 267 | adjust any build scripts using the old naming scheme accordingly. | ||
| 268 | |||
| 269 | <p> | ||
| 270 | |||
| 271 | The <a href="downloads/Changelog">changelog</a> has all | ||
| 272 | the details. And as usual you can | ||
| 273 | <a href="downloads">download busybox here</a>. | ||
| 274 | |||
| 275 | <p>Have Fun! | ||
| 276 | <p> | ||
| 277 | |||
| 278 | |||
| 279 | <p> | ||
| 280 | <li><b>23 December 2003 -- BusyBox 1.0.0-pre5 released</b><p> | ||
| 281 | |||
| 282 | Here goes the next pre-release for the new BusyBox stable | ||
| 283 | series. The most obvious thing in this release is a fix for | ||
| 284 | a terribly stupid bug in mount that prevented it from working | ||
| 285 | properly unless you specified the filesystem type. This | ||
| 286 | release also fixes a few compile problems, updates udhcp, | ||
| 287 | fixes a silly bug in fdisk, fixes ifup/ifdown to behave like | ||
| 288 | the Debian version, updates devfsd, updates the 2.6.x | ||
| 289 | modutils support, add a new 'rx' applet, removes the obsolete | ||
| 290 | 'loadacm' applet, fixes a few tar bugs, fixes a sed bug, and | ||
| 291 | a few other odd fixes. | ||
| 292 | |||
| 293 | <p> | ||
| 294 | |||
| 295 | If you see any problems, of have suggestions to make, as | ||
| 296 | always, please feel free to send an email to the busybox | ||
| 297 | mailing list. | ||
| 298 | |||
| 299 | <p> | ||
| 300 | |||
| 301 | The <a href="downloads/Changelog">changelog</a> has all | ||
| 302 | the details. And as usual you can | ||
| 303 | <a href="downloads">download busybox here</a>. | ||
| 304 | |||
| 305 | <p>Have Fun! | ||
| 306 | <p> | ||
| 307 | |||
| 308 | |||
| 309 | |||
| 310 | <li><b>10 December 2003 -- BusyBox 1.0.0-pre4 released</b><p> | ||
| 311 | |||
| 312 | Here goes the fourth pre-release for the new BusyBox stable | ||
| 313 | series. This release includes major rework to sed, lots of | ||
| 314 | rework on tar, a new tiny implementation of bunzip2, a new | ||
| 315 | devfsd applet, support for 2.6.x kernel modules, updates to | ||
| 316 | the ash shell, sha1sum and md5sum have been merged into a | ||
| 317 | common applet, the dpkg applets has been cleaned up, and tons | ||
| 318 | of random bugs have been fixed. Thanks everyone for all the | ||
| 319 | testing, bug reports, and patches! Once again, a big | ||
| 320 | thank-you goes to Glenn McGrath (bug1) for stepping in and | ||
| 321 | helping get patches merged! | ||
| 322 | |||
| 323 | <p> | ||
| 324 | |||
| 325 | And of course, if you are reading this, you might have noticed | ||
| 326 | the busybox website has been completely reworked. Hopefully | ||
| 327 | things are now somewhat easier to navigate... If you see any | ||
| 328 | problems, of have suggestions to make, as always, please feel | ||
| 329 | free to send an email to the busybox mailing list. | ||
| 330 | |||
| 331 | <p> | ||
| 332 | |||
| 333 | The <a href="downloads/Changelog">changelog</a> has all | ||
| 334 | the details. And as usual you can | ||
| 335 | <a href="downloads">download busybox here</a>. | ||
| 336 | |||
| 337 | <p>Have Fun! | ||
| 338 | |||
| 339 | |||
| 340 | |||
| 341 | <p> | ||
| 342 | <li><b>12 Sept 2003 -- BusyBox 1.0.0-pre3 released</b><p> | ||
| 343 | |||
| 344 | Here goes the third pre-release for the new BusyBox stable | ||
| 345 | series. The last prerelease has held up quite well under | ||
| 346 | testing, but a number of problems have turned up as the number | ||
| 347 | of people using it has increased. Thanks everyone for all | ||
| 348 | the testing, bug reports, and patches! | ||
| 349 | |||
| 350 | <p> | ||
| 351 | |||
| 352 | If you have submitted a patch or a bug report to the busybox | ||
| 353 | mailing list and no one has emailed you explaining why your | ||
| 354 | patch was rejected, it is safe to say that your patch has | ||
| 355 | somehow gotten lost or forgotten. That happens sometimes. | ||
| 356 | Please re-submit your patch or bug report to the BusyBox | ||
| 357 | mailing list! | ||
| 358 | |||
| 359 | <p> | ||
| 360 | |||
| 361 | The point of the "-preX" versions is to get a larger group of | ||
| 362 | people and vendors testing, so any problems that turn up can be | ||
| 363 | fixed prior to the final 1.0.0 release. The main feature | ||
| 364 | (besides additional testing) that is still still on the TODO | ||
| 365 | list before the final BusyBox 1.0.0 release is sorting out the | ||
| 366 | modutils issues. For the new 2.6.x kernels, we already have | ||
| 367 | patches adding insmod and rmmod support and those need to be | ||
| 368 | integrated. For 2.4.x kernels, for which busybox only supports | ||
| 369 | a limited number of architectures, we may want to invest a bit | ||
| 370 | more work before we cut 1.0.0. Or we may just leave 2.4.x | ||
| 371 | module loading alone. | ||
| 372 | |||
| 373 | <p> | ||
| 374 | |||
| 375 | I had hoped this release would be out a month ago. And of | ||
| 376 | course, it wasn't since Erik became busy getting a release of | ||
| 377 | <a href="http://www.uclibc.org/">uClibc</a> | ||
| 378 | out the door. Many thanks to Glenn McGrath (bug1) for | ||
| 379 | stepping in and helping get a bunch of patches merged! I am | ||
| 380 | not even going to state a date for releasing BusyBox 1.0.0 | ||
| 381 | -pre4 (or the final 1.0.0). We're aiming for late September... | ||
| 382 | But if this release proves as to be exceptionally stable (or | ||
| 383 | exceptionally unstable!), the next release may be very soon | ||
| 384 | indeed. | ||
| 385 | |||
| 386 | <p> | ||
| 387 | |||
| 388 | The <a href="downloads/Changelog">changelog</a> has all | ||
| 389 | the details. And as usual you can | ||
| 390 | <a href="downloads">download busybox here</a>. | ||
| 391 | |||
| 392 | <p>Have Fun! | ||
| 393 | |||
| 394 | |||
| 395 | <p> | ||
| 396 | <li><b>30 July 2003 -- BusyBox 1.0.0-pre2 released</b><p> | ||
| 397 | |||
| 398 | Here goes another pre release for the new BusyBox stable | ||
| 399 | series. The last prerelease (pre1) was given quite a lot of | ||
| 400 | testing (thanks everyone!) which has helped turn up a number of | ||
| 401 | bugs, and these problems have now been fixed. | ||
| 402 | |||
| 403 | <p> | ||
| 404 | |||
| 405 | Highlights of -pre2 include updating the 'ash' shell to sync up | ||
| 406 | with the Debian 'dash' shell, a new 'hdparm' applet was added, | ||
| 407 | init again supports pivot_root, The 'reboot' 'halt' and | ||
| 408 | 'poweroff' applets can now be used without using busybox init. | ||
| 409 | an ifconfig buffer overflow was fixed, losetup now allows | ||
| 410 | read-write loop devices, uClinux daemon support was added, the | ||
| 411 | 'watchdog', 'fdisk', and 'kill' applets were rewritten, there were | ||
| 412 | tons of doc updates, and there were many other bugs fixed. | ||
| 413 | <p> | ||
| 414 | |||
| 415 | If you have submitted a patch and it is not included in this | ||
| 416 | release and Erik has not emailed you explaining why your patch | ||
| 417 | was rejected, it is safe to say that he has lost your patch. | ||
| 418 | That happens sometimes. Please re-submit your patch to the | ||
| 419 | BusyBox mailing list. | ||
| 420 | <p> | ||
| 421 | |||
| 422 | The point of the "-preX" versions is to get a larger group of | ||
| 423 | people and vendors testing, so any problems that turn up can be | ||
| 424 | fixed prior to the final 1.0.0 release. The main feature that | ||
| 425 | is still still on the TODO list before the final BusyBox 1.0.0 | ||
| 426 | release is adding module support for the new 2.6.x kernels. If | ||
| 427 | necessary, a -pre3 BusyBox release will happen on August 6th. | ||
| 428 | Hopefully (i.e. unless some horrible catastrophic problem | ||
| 429 | turns up) the final BusyBox 1.0.0 release will be ready by | ||
| 430 | then... | ||
| 431 | <p> | ||
| 432 | |||
| 433 | The <a href="downloads/Changelog">changelog</a> has all | ||
| 434 | the details. As usual you can <a href="downloads">download busybox here</a>. | ||
| 435 | |||
| 436 | <p>Have Fun! | ||
| 437 | <p> | ||
| 438 | |||
| 439 | <p> | ||
| 440 | <li><b>15 July 2003 -- BusyBox 1.0.0-pre1 released</b><p> | ||
| 441 | |||
| 442 | The busybox development series has been under construction for | ||
| 443 | nearly two years now. Which is just entirely too long... So | ||
| 444 | it is with great pleasure that I announce the imminent release | ||
| 445 | of a new stable series. Due to the huge number of changes | ||
| 446 | since the last stable release (and the usual mindless version | ||
| 447 | number inflation) I am branding this new stable series verison | ||
| 448 | 1.0.x... | ||
| 449 | <p> | ||
| 450 | |||
| 451 | The point of "-preX" versions is to get a larger group of | ||
| 452 | people and vendors testing, so any problems that turn up can be | ||
| 453 | fixed prior to the magic 1.0.0 release (which should happen | ||
| 454 | later this month)... I plan to release BusyBox 1.0.0-pre2 next | ||
| 455 | Monday (July 21st), and, if necessary, -pre3 on July 28th. | ||
| 456 | Hopefully (i.e. unless some horrible catastrophic problem turns | ||
| 457 | up) the final BusyBox 1.0.0 release should be ready by the end | ||
| 458 | of July. | ||
| 459 | <p> | ||
| 460 | |||
| 461 | If you have submitted patches, and they are not in this release | ||
| 462 | and I have not emailed you explaining why your patch was | ||
| 463 | rejected, it is safe to say that I have lost your patch. That | ||
| 464 | happens sometimes. Please do <B>NOT</b> send all your patches, | ||
| 465 | support questions, etc, directly to Erik. I get hundreds of | ||
| 466 | emails every day (which is why I end up losing patches | ||
| 467 | sometimes in the flood)... The busybox mailing list is the | ||
| 468 | right place to send your patches, support questions, etc. | ||
| 469 | <p> | ||
| 470 | |||
| 471 | I would like to especially thank Vladimir Oleynik (vodz), Glenn | ||
| 472 | McGrath (bug1), Robert Griebl (sandman), and Manuel Novoa III | ||
| 473 | (mjn3) for their significant efforts and contributions that | ||
| 474 | have made this release possible. | ||
| 475 | <p> | ||
| 476 | |||
| 477 | As usual you can <a href="downloads">download busybox here</a>. | ||
| 478 | You don't really need to bother with the | ||
| 479 | <a href="downloads/Changelog">changelog</a>, as the changes | ||
| 480 | vs the stable version are way too extensive to easily enumerate. | ||
| 481 | But you can take a look if you really want too. | ||
| 482 | |||
| 483 | <p>Have Fun! | ||
| 484 | <p> | ||
| 485 | |||
| 486 | |||
| 487 | |||
| 488 | <p> | ||
| 489 | <li><b>26 October 2002 -- BusyBox 0.60.5 released</b><p> | ||
| 490 | |||
| 491 | I am very pleased to announce that the BusyBox 0.60.5 (stable) | ||
| 492 | is now available for download. This is a bugfix release for | ||
| 493 | the stable series to address all the problems that have turned | ||
| 494 | up since the last release. Unfortunately, the previous release | ||
| 495 | had a few nasty bugs (i.e. init could deadlock, gunzip -c tried | ||
| 496 | to delete source files, cp -a wouldn't copy symlinks, and init | ||
| 497 | was not always providing controlling ttys when it should have). | ||
| 498 | I know I said that the previous release would be the end of the | ||
| 499 | 0.60.x series. Well, it turns out I'm a liar. But this time I | ||
| 500 | mean it (just like last time ;-). This will be the last | ||
| 501 | release for the 0.60.x series -- all further development work | ||
| 502 | will be done for the development busybox tree. Expect the development | ||
| 503 | version to have its first real release very very soon now... | ||
| 504 | |||
| 505 | <p> | ||
| 506 | The <a href="downloads/Changelog.full">changelog</a> has all | ||
| 507 | the details. As usual you can <a href="downloads">download busybox here</a>. | ||
| 508 | <p>Have Fun! | ||
| 509 | <p> | ||
| 510 | |||
| 511 | <p> | ||
| 512 | <li><b>18 September 2002 -- BusyBox 0.60.4 released</b><p> | ||
| 513 | |||
| 514 | I am very pleased to announce that the BusyBox 0.60.4 | ||
| 515 | (stable) is now available for download. This is primarily | ||
| 516 | a bugfix release for the stable series to address all | ||
| 517 | the problems that have turned up since the last | ||
| 518 | release. This will be the last release for the 0.60.x series. | ||
| 519 | I mean it this time -- all further development work will be done | ||
| 520 | on the development busybox tree, which is quite solid now and | ||
| 521 | should soon be getting its first real release. | ||
| 522 | |||
| 523 | <p> | ||
| 524 | The <a href="downloads/Changelog.full">changelog</a> has all | ||
| 525 | the details. As usual you can <a href="downloads">download busybox here</a>. | ||
| 526 | <p>Have Fun! | ||
| 527 | <p> | ||
| 528 | |||
| 529 | |||
| 530 | <p> | ||
| 531 | <li><b>27 April 2002 -- BusyBox 0.60.3 released</b><p> | ||
| 532 | |||
| 533 | I am very pleased to announce that the BusyBox 0.60.3 (stable) is | ||
| 534 | now available for download. This is primarily a bugfix release | ||
| 535 | for the stable series. A number of problems have turned up since | ||
| 536 | the last release, and this should address most of those problems. | ||
| 537 | This should be the last release for the 0.60.x series. The | ||
| 538 | development busybox tree has been progressing nicely, and will | ||
| 539 | hopefully be ready to become the next stable release. | ||
| 540 | |||
| 541 | <p> | ||
| 542 | The <a href="downloads/Changelog">changelog</a> has all | ||
| 543 | the details. As usual you can <a href="downloads">download busybox here</a>. | ||
| 544 | <p>Have Fun! | ||
| 545 | <p> | ||
| 546 | |||
| 547 | |||
| 548 | <p> | ||
| 549 | <li><b>6 March 2002 -- busybox.net now has mirrors!</b><p> | ||
| 550 | |||
| 551 | Busybox.net is now much more available, thanks to | ||
| 552 | the fine folks at <a href= "http://i-netinnovations.com/">http://i-netinnovations.com/</a> | ||
| 553 | who are providing hosting for busybox.net and | ||
| 554 | uclibc.org. In addition, we now have two mirrors: | ||
| 555 | <a href= "http://busybox.linuxmagic.com/">http://busybox.linuxmagic.com/</a> | ||
| 556 | in Canada and | ||
| 557 | <a href= "http://busybox.csservers.de/">http://busybox.csservers.de/</a> | ||
| 558 | in Germany. I hope this makes things much more | ||
| 559 | accessible for everyone! | ||
| 560 | |||
| 561 | |||
| 562 | <li> | ||
| 563 | <b>3 January 2002 -- Welcome to busybox.net!</b> | ||
| 564 | |||
| 565 | <p>Thanks to the generosity of a number of busybox | ||
| 566 | users, we have been able to purchase busybox.net | ||
| 567 | (which is where you are probably reading this). | ||
| 568 | Right now, busybox.net and uclibc.org are both | ||
| 569 | living on my home system (at the end of my DSL | ||
| 570 | line). I apologize for the abrupt move off of | ||
| 571 | busybox.lineo.com. Unfortunately, I no longer have | ||
| 572 | the access needed to keep that system updated (for | ||
| 573 | example, you might notice the daily snapshots there | ||
| 574 | stopped some time ago).</p> | ||
| 575 | |||
| 576 | <p>Busybox.net is currently hosted on my home | ||
| 577 | server, at the end of a DSL line. Unfortunately, | ||
| 578 | the load on them is quite heavy. To address this, | ||
| 579 | I'm trying to make arrangements to get busybox.net | ||
| 580 | co-located directly at an ISP. To assist in the | ||
| 581 | co-location effort, <a href= | ||
| 582 | "http://www.codepoet.org/~markw">Mark Whitley</a> | ||
| 583 | (author of busybox sed, cut, and grep) has donated | ||
| 584 | his <a href= | ||
| 585 | "http://www.netwinder.org/">NetWinder</a> computer | ||
| 586 | for hosting busybox.net and uclibc.org. Once this | ||
| 587 | system is co-located, the current speed problems | ||
| 588 | should be completely eliminated. Hopefully, too, | ||
| 589 | some of you will volunteer to set up some mirror | ||
| 590 | sites, to help to distribute the load a bit.</p> | ||
| 591 | |||
| 592 | <p><!-- | ||
| 593 | <center> | ||
| 594 | Click here to help support busybox.net! | ||
| 595 | <form action="https://www.paypal.com/cgi-bin/webscr" method="post"> | ||
| 596 | <input type="hidden" name="cmd" value="_xclick"> | ||
| 597 | <input type="hidden" name="business" value="andersen@codepoet.org"> | ||
| 598 | <input type="hidden" name="item_name" value="Support Busybox"> | ||
| 599 | <input type="hidden" name="image_url" value="https://codepoet-consulting.com/images/busybox2.jpg"> | ||
| 600 | <input type="hidden" name="no_shipping" value="1"> | ||
| 601 | <input type="image" src="images/donate.png" border="0" name="submit" alt="Make donation using PayPal"> | ||
| 602 | </form> | ||
| 603 | </center> | ||
| 604 | --> | ||
| 605 | Since some people expressed concern over BusyBox | ||
| 606 | donations, let me assure you that no one is getting | ||
| 607 | rich here. All BusyBox and uClibc donations will be | ||
| 608 | spent paying for bandwidth and needed hardware | ||
| 609 | upgrades. For example, Mark's NetWinder currently | ||
| 610 | has just 64Meg of memory. As demonstrated when | ||
| 611 | google spidered the site the other day, 64 Megs in | ||
| 612 | not enough, so I'm going to be ordering 256Megs of | ||
| 613 | ram and a larger hard drive for the box today. So | ||
| 614 | far, donations received have been sufficient to | ||
| 615 | cover almost all expenses. In the future, we may | ||
| 616 | have co-location fees to worry about, but for now | ||
| 617 | we are ok. A <b>HUGE thank-you</b> goes out to | ||
| 618 | everyone that has contributed!<br> | ||
| 619 | -Erik</p> | ||
| 620 | </li> | ||
| 621 | |||
| 622 | <li> | ||
| 623 | <b>20 November 2001 -- BusyBox 0.60.2 released</b> | ||
| 624 | |||
| 625 | <p>We am very pleased to announce that the BusyBox | ||
| 626 | 0.60.2 (stable) is now released to the world. This | ||
| 627 | one is primarily a bugfix release for the stable | ||
| 628 | series, and it should take care of most everyone's | ||
| 629 | needs till we can get the nice new stuff we have | ||
| 630 | been working on in CVS ready to release (with the | ||
| 631 | wonderful new buildsystem). The biggest change in | ||
| 632 | this release (beyond bugfixes) is the fact that msh | ||
| 633 | (the minix shell) has been re-worked by Vladimir N. | ||
| 634 | Oleynik (vodz) and so it no longer crashes when | ||
| 635 | told to do complex things with backticks.</p> | ||
| 636 | |||
| 637 | <p>This release has been tested on x86, ARM, and | ||
| 638 | powerpc using glibc 2.2.4, libc5, and uClibc, so it | ||
| 639 | should work with just about any Linux system you | ||
| 640 | throw it at. See the <a href= | ||
| 641 | "downloads/Changelog">changelog</a> for <small>most | ||
| 642 | of</small> the details. The last release was | ||
| 643 | <em>very</em> solid for people, and this one should | ||
| 644 | be even better.</p> | ||
| 645 | |||
| 646 | <p>As usual BusyBox 0.60.2 can be downloaded from | ||
| 647 | <a href= | ||
| 648 | "downloads">http://www.busybox.net/downloads</a>.</p> | ||
| 649 | |||
| 650 | <p>Have Fun.<br> | ||
| 651 | -Erik</p> | ||
| 652 | </li> | ||
| 653 | |||
| 654 | <li> <b>18 November 2001 -- Help us buy busybox.net!</b> | ||
| 655 | |||
| 656 | <!-- Begin PayPal Logo --> | ||
| 657 | <center> | ||
| 658 | Click here to help buy busybox.net! | ||
| 659 | <form action="https://www.paypal.com/cgi-bin/webscr" method="post"> | ||
| 660 | <input type="hidden" name="cmd" value="_xclick"> | ||
| 661 | <input type="hidden" name="business" value="andersen@codepoet.org"> | ||
| 662 | <input type="hidden" name="item_name" value="Support Busybox"> | ||
| 663 | <input type="hidden" name="image_url" value="https://busybox.net/images/busybox2.jpg"> | ||
| 664 | <input type="hidden" name="no_shipping" value="1"> | ||
| 665 | <input type="image" src="images/donate.png" border="0" name="submit" alt="Make donation using PayPal"> | ||
| 666 | </form> | ||
| 667 | </center> | ||
| 668 | <!-- End PayPal Logo --> | ||
| 669 | |||
| 670 | I've contacted the current owner of busybox.net and he is willing | ||
| 671 | to sell the domain name -- for $250. He also owns busybox.org but | ||
| 672 | will not part with it... I will then need to pay the registry fee | ||
| 673 | for a couple of years and start paying for bandwidth, so this will | ||
| 674 | initially cost about $300. I would like to host busybox.net on my | ||
| 675 | home machine (codepoet.org) so I have full control over the system, | ||
| 676 | but to do that would require that I increase the level of bandwidth | ||
| 677 | I am paying for. Did you know that so far this month, there | ||
| 678 | have been over 1.4 Gigabytes of busybox ftp downloads? I don't | ||
| 679 | even <em>know</em> how much CVS bandwidth it requires. For the | ||
| 680 | time being, Lineo has continued to graciously provide this | ||
| 681 | bandwidth, despite the fact that I no longer work for them. If I | ||
| 682 | start running this all on my home machine, paying for the needed bandwidth | ||
| 683 | will start costing some money. | ||
| 684 | <p> | ||
| 685 | |||
| 686 | I was going to pay it all myself, but my wife didn't like that | ||
| 687 | idea at all (big surprise). It turns out <insert argument | ||
| 688 | where she wins and I don't> she has better ideas | ||
| 689 | about what we should spend our money on that don't involve | ||
| 690 | busybox. She suggested I should ask for contributions on the | ||
| 691 | mailing list and web page. So... | ||
| 692 | <p> | ||
| 693 | |||
| 694 | I am hoping that if everyone could contribute a bit, we could pick | ||
| 695 | up the busybox.net domain name and cover the bandwidth costs. I | ||
| 696 | know that busybox is being used by a lot of companies as well as | ||
| 697 | individuals -- hopefully people and companies that are willing to | ||
| 698 | contribute back a bit. So if everyone could please help out, that | ||
| 699 | would be wonderful! | ||
| 700 | <p> | ||
| 701 | |||
| 702 | |||
| 703 | <li> <b>23 August 2001 -- BusyBox 0.60.1 released</b> | ||
| 704 | <br> | ||
| 705 | |||
| 706 | This is a relatively minor bug fixing release that fixes | ||
| 707 | up the bugs that have shown up in the stable release in | ||
| 708 | the last few weeks. Fortunately, nothing <em>too</em> | ||
| 709 | serious has shown up. This release only fixes bugs -- no | ||
| 710 | new features, no new applets. So without further ado, | ||
| 711 | here it is. Come and get it. | ||
| 712 | <p> | ||
| 713 | The | ||
| 714 | <a href="downloads/Changelog">changelog</a> has all | ||
| 715 | the details. As usual BusyBox 0.60.1 can be downloaded from | ||
| 716 | <a href="downloads">http://busybox.net/downloads</a>. | ||
| 717 | <p>Have Fun! | ||
| 718 | <p> | ||
| 719 | |||
| 720 | |||
| 721 | <li> <b>2 August 2001 -- BusyBox 0.60.0 released</b> | ||
| 722 | <br> | ||
| 723 | I am very pleased to announce the immediate availability of | ||
| 724 | BusyBox 0.60.0. I have personally tested this release with libc5, glibc, | ||
| 725 | and <a href="http://uclibc.org/">uClibc</a> on | ||
| 726 | x86, ARM, and powerpc using linux 2.2 and 2.4, and I know a number | ||
| 727 | of people using it on everything from ia64 to m68k with great success. | ||
| 728 | Everything seems to be working very nicely now, so getting a nice | ||
| 729 | stable bug-free(tm) release out seems to be in order. This releases fixes | ||
| 730 | a memory leak in syslogd, a number of bugs in the ash and msh shells, and | ||
| 731 | cleans up a number of things. | ||
| 732 | |||
| 733 | <p> | ||
| 734 | |||
| 735 | Those wanting an easy way to test the 0.60.0 release with uClibc can | ||
| 736 | use <a href="http://user-mode-linux.sourceforge.net/">User-Mode Linux</a> | ||
| 737 | to give it a try by downloading and compiling | ||
| 738 | <a href="ftp://busybox.net/buildroot.tar.gz">buildroot.tar.gz</a>. | ||
| 739 | You don't have to be root or reboot your machine to run test this way. | ||
| 740 | Preconfigured User-Mode Linux kernel source is also on busybox.net. | ||
| 741 | <p> | ||
| 742 | Another cool thing is the nifty <a href="downloads/tutorial/index.html"> | ||
| 743 | BusyBox Tutorial</a> contributed by K Computing. This requires | ||
| 744 | a ShockWave plugin (or standalone viewer), so you may want to grab the | ||
| 745 | the GPLed shockwave viewer from <a href="http://www.swift-tools.com/Flash/flash-0.4.10.tgz">here</a> | ||
| 746 | to view the tutorial. | ||
| 747 | <p> | ||
| 748 | |||
| 749 | Finally, In case you didn't notice anything odd about the | ||
| 750 | version number of this release, let me point out that this release | ||
| 751 | is <em>not</em> 0.53, because I bumped the version number up a | ||
| 752 | bit. This reflects the fact that this release is intended to form | ||
| 753 | a new stable BusyBox release series. If you need to rely on a | ||
| 754 | stable version of BusyBox, you should plan on using the stable | ||
| 755 | 0.60.x series. If bugs show up then I will release 0.60.1, then | ||
| 756 | 0.60.2, etc... This is also intended to deal with the fact that | ||
| 757 | the BusyBox build system will be getting a major overhaul for the | ||
| 758 | next release and I don't want that to break products that people | ||
| 759 | are shipping. To avoid that, the new build system will be | ||
| 760 | released as part of a new BusyBox development series that will | ||
| 761 | have some not-yet-decided-on odd version number. Once things | ||
| 762 | stabilize and the new build system is working for everyone, then | ||
| 763 | I will release that as a new stable release series. | ||
| 764 | |||
| 765 | <p> | ||
| 766 | The | ||
| 767 | <a href="downloads/Changelog">changelog</a> has all | ||
| 768 | the details. As usual BusyBox 0.60.0 can be downloaded from | ||
| 769 | <a href="downloads">http://busybox.net/downloads</a>. | ||
| 770 | <p>Have Fun! | ||
| 771 | <p> | ||
| 772 | |||
| 773 | |||
| 774 | <li> <b>7 July 2001 -- BusyBox 0.52 released</b> | ||
| 775 | <br> | ||
| 776 | |||
| 777 | I am very pleased to announce the immediate availability of | ||
| 778 | BusyBox 0.52 (the "new-and-improved rock-solid release"). This | ||
| 779 | release is the result of <em>many</em> hours of work and has tons | ||
| 780 | of bugfixes, optimizations, and cleanups. This release adds | ||
| 781 | several new applets, including several new shells (such as hush, msh, | ||
| 782 | and ash). | ||
| 783 | |||
| 784 | <p> | ||
| 785 | The | ||
| 786 | <a href="downloads/Changelog">changelog</a> covers | ||
| 787 | some of the more obvious details, but there are many many things that | ||
| 788 | are not mentioned, but have been improved in subtle ways. As usual, | ||
| 789 | BusyBox 0.52 can be downloaded from | ||
| 790 | <a href="downloads">http://busybox.net/downloads</a>. | ||
| 791 | <p>Have Fun! | ||
| 792 | <p> | ||
| 793 | |||
| 794 | |||
| 795 | <li> <b>10 April 2001 - Graph of Busybox Growth </b> | ||
| 796 | <br> | ||
| 797 | The illustrious Larry Doolittle has made a PostScript chart of the growth | ||
| 798 | of the Busybox tarball size over time. It is available for downloading / | ||
| 799 | viewing <a href= "busybox-growth.ps"> right here</a>. | ||
| 800 | |||
| 801 | <p> (Note that while the number of applets in Busybox has increased, you | ||
| 802 | can still configure Busybox to be as small as you want by selectively | ||
| 803 | turning off whichever applets you don't need.) | ||
| 804 | <p> | ||
| 805 | |||
| 806 | |||
| 807 | <li> <b>10 April 2001 -- BusyBox 0.51 released</b> | ||
| 808 | <br> | ||
| 809 | |||
| 810 | BusyBox 0.51 (the "rock-solid release") is now out there. This | ||
| 811 | release adds only 2 new applets: env and vi. The vi applet, | ||
| 812 | contributed by Sterling Huxley, is very functional, and is only | ||
| 813 | 22k. This release fixes 3 critical bugs in the 0.50 release. | ||
| 814 | There were 2 potential segfaults in lash (the busybox shell) in | ||
| 815 | the 0.50 release which are now fixed. Another critical bug in | ||
| 816 | 0.50 which is now fixed: syslogd from 0.50 could potentially | ||
| 817 | deadlock the init process and thereby break your entire system. | ||
| 818 | <p> | ||
| 819 | |||
| 820 | There are a number of improvements in this release as well. For | ||
| 821 | one thing, the wget applet is greatly improved. Dmitry Zakharov | ||
| 822 | added FTP support, and Laurence Anderson make wget fully RFC | ||
| 823 | compliant for HTTP 1.1. The mechanism for including utility | ||
| 824 | functions in previous releases was clumsy and error prone. Now | ||
| 825 | all utility functions are part of a new libbb library, which makes | ||
| 826 | maintaining utility functions much simpler. And BusyBox now | ||
| 827 | compiles on itanium systems (thanks to the Debian itanium porters | ||
| 828 | for letting me use their system!). | ||
| 829 | <p> | ||
| 830 | You can read the | ||
| 831 | <a href="downloads/Changelog">changelog</a> for | ||
| 832 | complete details. BusyBox 0.51 can be downloaded from | ||
| 833 | <a href="downloads">http://busybox.net/downloads</a>. | ||
| 834 | <p>Have Fun! | ||
| 835 | <p> | ||
| 836 | |||
| 837 | <li> <b>Busybox Boot-Floppy Image</b> | ||
| 838 | |||
| 839 | <p>Because you asked for it, we have made available a <a href= | ||
| 840 | "downloads/busybox.floppy.img"> Busybox boot floppy | ||
| 841 | image</a>. Here's how you use it: | ||
| 842 | |||
| 843 | <ol> | ||
| 844 | |||
| 845 | <li> <a href= "downloads/busybox.floppy.img"> | ||
| 846 | Download the image</a> | ||
| 847 | |||
| 848 | <li> dd it onto a floppy like so: <tt> dd if=busybox.floppy.img | ||
| 849 | of=/dev/fd0 ; sync </tt> | ||
| 850 | |||
| 851 | <li> Pop it in a machine and boot up. | ||
| 852 | |||
| 853 | </ol> | ||
| 854 | |||
| 855 | <p> If you want to look at the contents of the initrd image, do this: | ||
| 856 | |||
| 857 | <pre> | ||
| 858 | mount ./busybox.floppy.img /mnt -o loop -t msdos | ||
| 859 | cp /mnt/initrd.gz /tmp | ||
| 860 | umount /mnt | ||
| 861 | gunzip /tmp/initrd.gz | ||
| 862 | mount /tmp/initrd /mnt -o loop -t minix | ||
| 863 | </pre> | ||
| 864 | |||
| 865 | |||
| 866 | <li> <b>15 March 2001 -- BusyBox 0.50 released</b> | ||
| 867 | <br> | ||
| 868 | |||
| 869 | This release adds several new applets including ifconfig, route, pivot_root, stty, | ||
| 870 | and tftp, and also fixes tons of bugs. Tab completion in the | ||
| 871 | shell is now working very well, and the shell's environment variable | ||
| 872 | expansion was fixed. Tons of other things were fixed or made | ||
| 873 | smaller. For a fairly complete overview, see the | ||
| 874 | <a href="downloads/Changelog">changelog</a>. | ||
| 875 | <p> | ||
| 876 | lash (the busybox shell) is still with us, fixed up a bit so it | ||
| 877 | now behaves itself quite nicely. It really is quite usable as | ||
| 878 | long as you don't expect it to provide Bourne shell grammer. | ||
| 879 | Standard things like pipes, redirects, command line editing, and | ||
| 880 | environment variable expansion work great. But we have found that | ||
| 881 | this shell, while very usable, does not provide an extensible | ||
| 882 | framework for adding in full Bourne shell behavior. So the first order of | ||
| 883 | business as we begin working on the next BusyBox release will be to merge in the new shell | ||
| 884 | currently in progress at | ||
| 885 | <a href="http://doolittle.faludi.com/~larry/parser.html">Larry Doolittle's website</a>. | ||
| 886 | <p> | ||
| 887 | |||
| 888 | |||
| 889 | <li> <b>27 January 2001 -- BusyBox 0.49 released</b> | ||
| 890 | <br> | ||
| 891 | |||
| 892 | Several new applets, lots of bug fixes, cleanups, and many smaller | ||
| 893 | things made nicer. Several cleanups and improvements to the shell. | ||
| 894 | For a list of the most interesting changes | ||
| 895 | you might want to look at the <a href="downloads/Changelog">changelog</a>. | ||
| 896 | <p> | ||
| 897 | Special thanks go out to Matt Kraai and Larry Doolittle for all their | ||
| 898 | work on this release, and for keeping on top of things while I've been | ||
| 899 | out of town. | ||
| 900 | <p> | ||
| 901 | <em>Special Note</em><br> | ||
| 902 | |||
| 903 | BusyBox 0.49 was supposed to have replaced lash, the BusyBox | ||
| 904 | shell, with a new shell that understands full Bourne shell/Posix shell grammer. | ||
| 905 | Well, that simply didn't happen in time for this release. A new | ||
| 906 | shell that will eventually replace lash is already under | ||
| 907 | construction. This new shell is being developed by Larry | ||
| 908 | Doolittle, and could use all of our help. Please see the work in | ||
| 909 | progress on <a href="http://doolittle.faludi.com/~larry/parser.html">Larry's website</a> | ||
| 910 | and help out if you can. This shell will be included in the next | ||
| 911 | release of BusyBox. | ||
| 912 | <p> | ||
| 913 | |||
| 914 | <li> <b>13 December 2000 -- BusyBox 0.48 released</b> | ||
| 915 | <br> | ||
| 916 | |||
| 917 | This release fixes lots and lots of bugs. This has had some very | ||
| 918 | rigorous testing, and looks very, very clean. The usual tar | ||
| 919 | update of course: tar no longer breaks hardlinks, tar -xzf is | ||
| 920 | optionally supported, and the LRP folks will be pleased to know | ||
| 921 | that 'tar -X' and 'tar --exclude' are both now in. Applets are | ||
| 922 | now looked up using a binary search making lash (the busybox | ||
| 923 | shell) much faster. For the new debian-installer (for Debian | ||
| 924 | woody) a .udeb can now be generated. | ||
| 925 | <p> | ||
| 926 | The curious can get a list of some of the more interesting changes by reading | ||
| 927 | the <a href="downloads/Changelog">changelog</a>. | ||
| 928 | <p> | ||
| 929 | Many thanks go out to the many many people that have contributed to | ||
| 930 | this release, especially Matt Kraai, Larry Doolittle, and Kent Robotti. | ||
| 931 | <p> | ||
| 932 | <p> <li> <b>26 September 2000 -- BusyBox 0.47 released</b> | ||
| 933 | <br> | ||
| 934 | |||
| 935 | This release fixes lots of bugs (including an ugly bug in 0.46 | ||
| 936 | syslogd that could fork-bomb your system). Added several new | ||
| 937 | apps: rdate, wget, getopt, dos2unix, unix2dos, reset, unrpm, | ||
| 938 | renice, xargs, and expr. syslogd now supports network logging. | ||
| 939 | There are the usual tar updates. Most apps now use getopt for | ||
| 940 | more correct option parsing. | ||
| 941 | See the <a href="downloads/Changelog">changelog</a> | ||
| 942 | for complete details. | ||
| 943 | |||
| 944 | |||
| 945 | <p> <li> <b>11 July 2000 -- BusyBox 0.46 released</b> | ||
| 946 | <br> | ||
| 947 | |||
| 948 | This release fixes several bugs (including a ugly bug in tar, | ||
| 949 | and fixes for NFSv3 mount support). Added a dumpkmap to allow | ||
| 950 | people to dump a binary keymaps for use with 'loadkmap', and a | ||
| 951 | completely reworked 'grep' and 'sed' which should behave better. | ||
| 952 | BusyBox shell can now also be used as a login shell. | ||
| 953 | See the <a href="downloads/Changelog">changelog</a> | ||
| 954 | for complete details. | ||
| 955 | |||
| 956 | |||
| 957 | <p> <li> <b>21 June 2000 -- BusyBox 0.45 released</b> | ||
| 958 | <br> | ||
| 959 | |||
| 960 | This release has been slow in coming, but is very solid at this | ||
| 961 | point. BusyBox now supports libc5 as well as GNU libc. This | ||
| 962 | release provides the following new apps: cut, tr, insmod, ar, | ||
| 963 | mktemp, setkeycodes, md5sum, uuencode, uudecode, which, and | ||
| 964 | telnet. There are bug fixes for just about every app as well (see | ||
| 965 | the <a href="downloads/Changelog">changelog</a> for | ||
| 966 | details). | ||
| 967 | <p> | ||
| 968 | Also, some exciting infrastructure news! Busybox now has its own | ||
| 969 | <a href="lists/busybox/">mailing list</a>, | ||
| 970 | publically browsable | ||
| 971 | <a href="/cgi-bin/viewcvs.cgi/trunk/busybox/">CVS tree</a>, | ||
| 972 | anonymous | ||
| 973 | <a href="cvs_anon.html">CVS access</a>, and | ||
| 974 | for those that are actively contributing there is even | ||
| 975 | <a href="cvs_write.html">CVS write access</a>. | ||
| 976 | I think this will be a huge help to the ongoing development of BusyBox. | ||
| 977 | <p> | ||
| 978 | Also, for the curious, there is no 0.44 release. Somehow 0.44 got announced | ||
| 979 | a few weeks ago prior to its actually being released. To avoid any confusion | ||
| 980 | we are just skipping 0.44. | ||
| 981 | <p> | ||
| 982 | Many thanks go out to the many people that have contributed to this release | ||
| 983 | of BusyBox (esp. Pavel Roskin)! | ||
| 984 | |||
| 985 | |||
| 986 | <p> <li> <b>19 April 2000 -- syslogd bugfix</b> | ||
| 987 | <br> | ||
| 988 | Turns out that there was still a bug in busybox syslogd. | ||
| 989 | For example, with the following test app: | ||
| 990 | <pre> | ||
| 991 | #include <syslog.h> | ||
| 992 | |||
| 993 | int do_log(char* msg, int delay) | ||
| 994 | { | ||
| 995 | openlog("testlog", LOG_PID, LOG_DAEMON); | ||
| 996 | while(1) { | ||
| 997 | syslog(LOG_ERR, "%s: testing one, two, three\n", msg); | ||
| 998 | sleep(delay); | ||
| 999 | } | ||
| 1000 | closelog(); | ||
| 1001 | return(0); | ||
| 1002 | }; | ||
| 1003 | |||
| 1004 | int main(void) | ||
| 1005 | { | ||
| 1006 | if (fork()==0) | ||
| 1007 | do_log("A", 2); | ||
| 1008 | do_log("B", 3); | ||
| 1009 | } | ||
| 1010 | </pre> | ||
| 1011 | it should be logging stuff from both "A" and "B". As released in 0.43 only stuff | ||
| 1012 | from "A" would have been logged. This means that if init tries to log something | ||
| 1013 | while say ppp has the syslog open, init would block (which is bad, bad, bad). | ||
| 1014 | <p> | ||
| 1015 | Karl M. Hegbloom has created a fix for the problem. | ||
| 1016 | Thanks Karl! | ||
| 1017 | |||
| 1018 | |||
| 1019 | <p> <li> <b>18 April 2000 -- BusyBox 0.43 released (finally!)</b> | ||
| 1020 | <br> | ||
| 1021 | I have finally gotten everything into a state where I feel pretty | ||
| 1022 | good about things. This is definitely the most stable, solid release | ||
| 1023 | so far. A lot of bugs have been fixed, and the following new apps | ||
| 1024 | have been added: sh, basename, dirname, killall, uptime, | ||
| 1025 | freeramdisk, tr, echo, test, and usleep. Tar has been completely | ||
| 1026 | rewritten from scratch. Bss size has also been greatly reduced. | ||
| 1027 | More details are available in the | ||
| 1028 | <a href="downloads/Changelog">changelog</a>. | ||
| 1029 | Oh, and as a special bonus, I wrote some fairly comprehensive | ||
| 1030 | <em>documentation</em>, complete with examples and full usage information. | ||
| 1031 | |||
| 1032 | <p> | ||
| 1033 | Many thanks go out to the fine people that have helped by submitting patches | ||
| 1034 | and bug reports; particularly instrumental in helping for this release were | ||
| 1035 | Karl Hegbloom, Pavel Roskin, Friedrich Vedder, Emanuele Caratti, | ||
| 1036 | Bob Tinsley, Nicolas Pitre, Avery Pennarun, Arne Bernin, John Beppu, and Jim Gleason. | ||
| 1037 | There were others so if I somehow forgot to mention you, I'm very sorry. | ||
| 1038 | <p> | ||
| 1039 | |||
| 1040 | You can grab BusyBox 0.43 tarballs <a href="downloads">here</a>. | ||
| 1041 | |||
| 1042 | <p> <li> <b>9 April 2000 -- BusyBox 0.43 pre release</b> | ||
| 1043 | <br> | ||
| 1044 | Unfortunately, I have not yet finished all the things I want to | ||
| 1045 | do for BusyBox 0.43, so I am posting this pre-release for people | ||
| 1046 | to poke at. This contains my complete rewrite of tar, which now weighs in at | ||
| 1047 | 5k (7k with all options turned on) and works for reading and writing | ||
| 1048 | tarballs (which it does correctly for everything I have been able to throw | ||
| 1049 | at it). Tar also (optionally) supports the "--exclude" option (mainly because | ||
| 1050 | the Linux Router Project folks asked for it). This also has a pre-release | ||
| 1051 | of the micro shell I have been writing. This pre-release should be stable | ||
| 1052 | enough for production use -- it just isn't a release since I have some structural | ||
| 1053 | changes I still want to make. | ||
| 1054 | <p> | ||
| 1055 | The pre-release can be found <a href="downloads">here</a>. | ||
| 1056 | Please let me know ASAP if you find <em>any</em> bugs. | ||
| 1057 | |||
| 1058 | <p> <li> <b>28 March 2000 -- Andersen Baby Boy release</b> | ||
| 1059 | <br> | ||
| 1060 | I am pleased to announce that on Tuesday March 28th at 5:48pm, weighing in at 7 | ||
| 1061 | lbs. 12 oz, Micah Erik Andersen was born at LDS Hospital here in Salt Lake City. | ||
| 1062 | He was born in the emergency room less then 5 minutes after we arrived -- and | ||
| 1063 | it was such a relief that we even made it to the hospital at all. Despite the | ||
| 1064 | fact that I was driving at an amazingly unlawful speed and honking at everybody | ||
| 1065 | and thinking decidedly unkind thoughts about the people in our way, my wife | ||
| 1066 | (inconsiderate of my feelings and complete lack of medical training) was lying | ||
| 1067 | down in the back seat saying things like "I think I need to start pushing now" | ||
| 1068 | (which she then proceeded to do despite my best encouraging statements to the | ||
| 1069 | contrary). | ||
| 1070 | <p> | ||
| 1071 | Anyway, I'm glad to note that despite the much-faster-than-we-were-expecting | ||
| 1072 | labor, both Shaunalei and our new baby boy are doing wonderfully. | ||
| 1073 | <p> | ||
| 1074 | So now that I am done with my excuse for the slow release cycle... | ||
| 1075 | Progress on the next release of BusyBox has been slow but steady. I expect | ||
| 1076 | to have a release sometime during the first week of April. This release will | ||
| 1077 | include a number of important changes, including the addition of a shell, a | ||
| 1078 | re-write of tar (to accommodate the Linux Router Project), and syslogd can now | ||
| 1079 | accept multiple concurrent connections, fixing lots of unexpected blocking | ||
| 1080 | problems. | ||
| 1081 | |||
| 1082 | |||
| 1083 | <p> <li> <b>11 February 2000 -- BusyBox 0.42 released</b> | ||
| 1084 | <br> | ||
| 1085 | |||
| 1086 | This is the most solid BusyBox release so far. Many, many | ||
| 1087 | bugs have been fixed. See the | ||
| 1088 | <a href="downloads/Changelog">changelog</a> for details. | ||
| 1089 | |||
| 1090 | Of particular interest, init will now cleanly unmount | ||
| 1091 | filesystems on reboot, cp and mv have been rewritten and | ||
| 1092 | behave much better, and mount and umount no longer leak | ||
| 1093 | loop devices. Many thanks go out to Randolph Chung, | ||
| 1094 | Karl M. Hegbloom, Taketoshi Sano, and Pavel Roskin for | ||
| 1095 | their hard work on this release of BusyBox. Please pound | ||
| 1096 | on it and let me know if you find any bugs. | ||
| 1097 | |||
| 1098 | <p> <li> <b>19 January 2000 -- BusyBox 0.41 released</b> | ||
| 1099 | <br> | ||
| 1100 | |||
| 1101 | This release includes bugfixes to cp, mv, logger, true, false, | ||
| 1102 | mkdir, syslogd, and init. New apps include wc, hostid, | ||
| 1103 | logname, tty, whoami, and yes. New features include loop device | ||
| 1104 | support in mount and umount, and better TERM handling by init. | ||
| 1105 | The changelog can be found <a href="downloads/Changelog">here</a>. | ||
| 1106 | |||
| 1107 | <p> <li> <b>7 January 2000 -- BusyBox 0.40 released</b> | ||
| 1108 | <br> | ||
| 1109 | |||
| 1110 | This release includes bugfixes to init (now includes inittab support), | ||
| 1111 | syslogd, head, logger, du, grep, cp, mv, sed, dmesg, ls, kill, gunzip, and mknod. | ||
| 1112 | New apps include sort, uniq, lsmod, rmmod, fbset, and loadacm. | ||
| 1113 | In particular, this release fixes an important bug in tar which | ||
| 1114 | in some cases produced serious security problems. | ||
| 1115 | As always, the changelog can be found <a href="downloads/Changelog">here</a>. | ||
| 1116 | |||
| 1117 | <p> <li> <b>11 December 1999 -- BusyBox Website</b> | ||
| 1118 | <br> | ||
| 1119 | I have received permission from Bruce Perens (the original author of BusyBox) | ||
| 1120 | to set up this site as the new primary website for BusyBox. This website | ||
| 1121 | will always contain pointers to the latest and greatest, and will also | ||
| 1122 | contain the latest documentation on how to use BusyBox, what it can do, | ||
| 1123 | what arguments its apps support, etc. | ||
| 1124 | |||
| 1125 | <p> <li> <b>10 December 1999 -- BusyBox 0.39 released</b> | ||
| 1126 | <br> | ||
| 1127 | This release includes fixes to init, reboot, halt, kill, and ls, and contains | ||
| 1128 | the new apps ping, hostname, mkfifo, free, tail, du, tee, and head. A full | ||
| 1129 | changelog can be found <a href="downloads/Changelog">here</a>. | ||
| 1130 | <p> <li> <b>5 December 1999 -- BusyBox 0.38 released</b> | ||
| 1131 | <br> | ||
| 1132 | This release includes fixes to tar, cat, ls, dd, rm, umount, find, df, | ||
| 1133 | and make install, and includes new apps syslogd/klogd and logger. | ||
| 1134 | |||
| 1135 | |||
| 1136 | </ul> | ||
| 1137 | |||
| 1138 | |||
| 1139 | <!--#include file="footer.html" --> | ||
| 1140 | |||
diff --git a/docs/busybox.net/products.html b/docs/busybox.net/products.html new file mode 100644 index 000000000..daf8add20 --- /dev/null +++ b/docs/busybox.net/products.html | |||
| @@ -0,0 +1,170 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | |||
| 4 | <h3>Products/Projects Using BusyBox</h3> | ||
| 5 | |||
| 6 | Do you use BusyBox? I'd love to know about it and | ||
| 7 | I'd be happy to link to you. | ||
| 8 | |||
| 9 | <p> | ||
| 10 | I know of the following products and/or projects that use BusyBox -- | ||
| 11 | listed in the order I happen to add them to the web page: | ||
| 12 | |||
| 13 | <ul> | ||
| 14 | |||
| 15 | <li><a href="http://buildroot.uclibc.org/">buildroot</a><br>A configurable | ||
| 16 | means for building your own busybox/uClibc based system systems, maintained | ||
| 17 | by the uClibc developers. | ||
| 18 | |||
| 19 | <li><a href="http://openwrt.org">OpenWrt</a> a Linux distribution for embedded | ||
| 20 | devices, based on buildroot. | ||
| 21 | |||
| 22 | <li><a href="http://www.pengutronix.de/software/ptxdist_en.html">PTXdist</a><br>another | ||
| 23 | configurable means for building your own busybox based system systems. | ||
| 24 | |||
| 25 | </li><li><a href= | ||
| 26 | "http://cvs.debian.org/boot-floppies/"> | ||
| 27 | Debian installer (boot floppies) project</a> | ||
| 28 | |||
| 29 | </li><li><a href="http://redhat.com/">Red Hat installer</a> | ||
| 30 | |||
| 31 | </li><li><a href= | ||
| 32 | "http://distro.ibiblio.org/pub/Linux/distributions/slackware/slackware-current/source/rootdisks/"> | ||
| 33 | Slackware Installer</a> | ||
| 34 | |||
| 35 | </li><li><a href="http://www.gentoo.org/">Gentoo Linux install/boot CDs</a> | ||
| 36 | </li><li><a href="http://www.mandriva.com/">The Mandriva installer</a> | ||
| 37 | |||
| 38 | </li><li><a href="http://Leaf.SourceForge.net">Linux Embedded Appliance Firewall</a><br>The sucessor of the Linux Router Project, supporting all sorts of embedded Linux gateways, routers, wireless routers, and firewalls. | ||
| 39 | |||
| 40 | </li><li><a href= | ||
| 41 | "http://www.toms.net/rb/">tomsrtbt</a> | ||
| 42 | |||
| 43 | </li><li><a href="http://www.stormix.com/">Stormix | ||
| 44 | Installer</a> | ||
| 45 | |||
| 46 | </li><li><a href= | ||
| 47 | "http://www.emacinc.com/linux2_sbc.htm">EMAC Linux | ||
| 48 | 2.0 SBC</a> | ||
| 49 | |||
| 50 | </li><li><a href="http://www.trinux.org/">Trinux</a> | ||
| 51 | |||
| 52 | </li><li><a href="http://oddas.sourceforge.net/">ODDAS | ||
| 53 | project</a> | ||
| 54 | |||
| 55 | </li><li><a href="http://byld.sourceforge.net/">Build Your | ||
| 56 | Linux Disk</a> | ||
| 57 | |||
| 58 | </li><li><a href= | ||
| 59 | "http://ibiblio.org/pub/Linux/system/recovery">Zdisk</a> | ||
| 60 | |||
| 61 | </li><li><a href="http://www.adtran.com">AdTran - | ||
| 62 | VPN/firewall VPN Linux Distribution</a> | ||
| 63 | |||
| 64 | </li><li><a href="http://mkcdrec.ota.be/">mkCDrec - make | ||
| 65 | CD-ROM recovery</a> | ||
| 66 | |||
| 67 | </li><li><a href= | ||
| 68 | "http://recycle.lbl.gov/~ldoolitt/bse/">Linux on | ||
| 69 | nanoEngine</a> | ||
| 70 | |||
| 71 | </li><li><a href= | ||
| 72 | "http://www.zelow.no/floppyfw/">Floppyfw</a> | ||
| 73 | |||
| 74 | </li><li><a href="http://www.ltsp.org/">Linux Terminal | ||
| 75 | Server Project</a> | ||
| 76 | |||
| 77 | </li><li><a href="http://www.devil-linux.org/">Devil-Linux</a> | ||
| 78 | |||
| 79 | </li><li><a href="http://dutnux.sourceforge.net/">DutNux</a> | ||
| 80 | |||
| 81 | </li><li><a href="http://www.microwerks.net/~hugo/mindi/">Mindi</a> | ||
| 82 | |||
| 83 | </li><li><a href="http://www.minimalinux.org/ttylinux/">ttylinux</a> | ||
| 84 | |||
| 85 | </li><li><a href="http://www.coyotelinux.com/">Coyote Linux</a> | ||
| 86 | |||
| 87 | </li><li><a href="http://www.partimage.org/">Partition | ||
| 88 | Image</a> | ||
| 89 | |||
| 90 | </li><li><a href="http://www.fli4l.de/">fli4l the on(e)-disk-router</a> | ||
| 91 | |||
| 92 | </li><li><a href="http://tinfoilhat.cultists.net/">Tinfoil | ||
| 93 | Hat Linux</a> | ||
| 94 | |||
| 95 | </li><li><a href="http://sourceforge.net/projects/gp32linux/">gp32linux</a> | ||
| 96 | </li><li><a href="http://familiar.handhelds.org/">Familiar Linux</a><br>A linux distribution for handheld computers | ||
| 97 | </li><li><a href="http://rescuecd.sourceforge.net/">Timo's Rescue CD Set</a> | ||
| 98 | </li><li><a href="http://sf.net/projects/netstation/">Netstation</a> | ||
| 99 | </li><li><a href="http://www.fiwix.org/">GNU/Fiwix Operating System</a> | ||
| 100 | </li><li><a href="http://www.softcraft.com/">Generations Linux</a> | ||
| 101 | </li><li><a href="http://systemimager.org/relatedprojects/">SystemImager / System Installation Suite</a> | ||
| 102 | </li><li><a href="http://www.bablokb.de/gendist/">GENDIST distribution generator</a> | ||
| 103 | </li><li><a href="http://diet-pc.sourceforge.net/">DIET-PC embedded Linux thin client distribution</a> | ||
| 104 | </li><li><a href="http://byzgl.sourceforge.net/">BYZantine Gnu/Linux</a> | ||
| 105 | </li><li><a href="http://dban.sourceforge.net/">Darik's Boot and Nuke</a> | ||
| 106 | </li><li><a href="http://www.timesys.com/">TimeSys real-time Linux</a> | ||
| 107 | </li><li><a href="http://movix.sf.net/">MoviX</a><br>Boots from CD and automatically plays every video file on the CD | ||
| 108 | </li><li><a href="http://katamaran.sourceforge.net">katamaran</a><br>Linux, X11, xfce windowmanager, based on BusyBox | ||
| 109 | </li><li><a href="http://www.sourceforge.net/projects/simplygnustep">Prometheus SimplyGNUstep</a> | ||
| 110 | </li><li><a href="http://www.renyi.hu/~ekho/lowlife/">lowlife</a><br>A documentation project on how to make your own uClibc-based systems and floppy. | ||
| 111 | </li><li><a href="http://metadistros.hispalinux.es/">Metadistros</a><br>a project to allow you easily make Live-CD distributions. | ||
| 112 | </li><li><a href="http://salvare.sourceforge.net/">Salvare</a><br>More Linux than tomsrtbt but less than Knoppix, aims to provide a useful workstation as well as a rescue disk. | ||
| 113 | </li><li><a href="http://www.stresslinux.org/">stresslinux</a><br>minimal linux distribution running from a bootable cdrom or via PXE. | ||
| 114 | </li><li><a href="http://thinstation.sourceforge.net/">thinstation</a><br>convert standard PCs into full-featured diskless thinclients. | ||
| 115 | </li><li><a href="http://www.uhulinux.hu/">UHU-Linux Hungary</a> | ||
| 116 | </li><li><a href="http://deep-water.berlios.de/">Deep-Water Linux</a> | ||
| 117 | </li><li><a href="http://www.freesco.org/">Freesco router</a> | ||
| 118 | </li><li><a href="http://Sentry.SourceForge.net/">Sentry Firewall CD</a> | ||
| 119 | |||
| 120 | |||
| 121 | |||
| 122 | </li><li><a href="http://tuxscreen.net">Tuxscreen Linux Phone</a> | ||
| 123 | </li><li><a href="http://www.kerbango.com/">The Kerbango Internet Radio</a> | ||
| 124 | </li><li><a href="http://www.linuxmagic.com/vpn/">LinuxMagic VPN Firewall</a> | ||
| 125 | </li><li><a href="http://www.isilver-inc.com/">I-Silver Linux appliance servers</a> | ||
| 126 | </li><li><a href="http://zaurus.sourceforge.net/">Sharp Zaurus PDA</a> | ||
| 127 | </li><li><a href="http://www.cyclades.com/">Cyclades-TS and other Cyclades products</a> | ||
| 128 | </li><li><a href="http://www.linksys.com/products/product.asp?prid=508">Linksys WRT54G - Wireless-G Broadband Router</a> | ||
| 129 | </li><li><a href="http://www.dell.com/us/en/biz/topics/sbtopic_005_truemobile.htm">Dell TrueMobile 1184</a> | ||
| 130 | </li><li><a href="http://actiontec.com/products/modems/dual_pcmodem/dpm_overview.html">Actiontec Dual PC Modem</a> | ||
| 131 | </li><li><a href="http://www.kiss-technology.com/">Kiss DP Series DVD players</a> | ||
| 132 | </li><li><a href="http://www.netgear.com/products/prod_details.asp?prodID=170">NetGear WG602 wireless router</a> | ||
| 133 | <br>with sources <a href="http://www.netgear.com/support/support_details.asp?dnldID=453">here</a> | ||
| 134 | </li><li><a href="http://www.trendware.com/products/TEW-411BRP.htm">TRENDnet TEW-411BRP 802.11g Wireless AP/Router/Switch</a> | ||
| 135 | <br>Source for busybox and udhcp <a href="http://www.trendware.com/asp/download/fileinfo.asp?file_id=277&B1=Search">here</a> though no kernel source is provided. | ||
| 136 | </li><li><a href="http://www.buffalo-technology.com/webcontent/products/wireless/wbr-g54.htm">Buffalo WBR-G54 wireless router</a> | ||
| 137 | </li><li><a href="http://www.asus.com/products/communication/wireless/wl-300g/overview.htm">ASUS WL-300g Wireless LAN Access Point</a> | ||
| 138 | <br>with source<a href="http://www.asus.com.tw/support/download/item.aspx?ModelName=WL-300G">here</a> | ||
| 139 | </li><li><a href="http://catalog.belkin.com/IWCatProductPage.process?Merchant_Id=&Section_Id=201522&pcount=&Product_Id=136493">Belkin 54g Wireless DSL/Cable Gateway Router</a> | ||
| 140 | <br>with source<a href="http://web.belkin.com/support/gpl.asp">here</a> | ||
| 141 | <li><a href="http://www.acronis.com/products/partitionexpert/">Acronis PartitionExpert 2003</a> | ||
| 142 | <br>includes a heavily modified BusyBox v0.60.5 with built in | ||
| 143 | cardmgr, device detection, gpm, lspci, etc. Also includes udhcp, | ||
| 144 | uClibc 0.9.26, a heavily patched up linux kernel, etc. Source | ||
| 145 | can only be obtained <a href="http://www.acronis.com/files/gpl/linux.tar.bz2">here</a> | ||
| 146 | |||
| 147 | </li><li><a href="http://www.usr.com/">U.S. Robotics Sureconnect 4-port ADSL router</a><br> | ||
| 148 | with source <a href="http://www.usr.com/support/s-gpl-code.asp">here</a> | ||
| 149 | </li><li><a href="http://www.actiontec.com/products/broadband/54mbps_wireless_gateway_1p/index.html"> | ||
| 150 | ActionTec GT701-WG Wireless Gateway/DSL Modem</a> | ||
| 151 | with source <a href="http://128.121.226.214/gtproducts/index.html">here</a> | ||
| 152 | </li><li><a href="http://smartlinux.sourceforge.net/">S.M.A.R.T. Linux</a> | ||
| 153 | </li><li><a href="http://www.dlink.com/">DLink - Model GSL-G604T, DSL-300T, and possibly other models</a> | ||
| 154 | with source <a href="ftp://ftp.dlink.co.uk/dsl_routers_modems/">here,</a> | ||
| 155 | with source <a href="ftp://ftp.dlink.de/dsl-products/">and here,</a> | ||
| 156 | and quite possibly other places as well. You may need to dig down a bit | ||
| 157 | to find the source, but it does seem to be there. | ||
| 158 | </li><li><a href="http://www.siemens-mobile.de/cds/frontdoor/0,2241,de_de_0_42931_rArNrNrNrN,00.html">Siemens SE515 DSL router</a> | ||
| 159 | with source <a href="http://now-portal.c-lab.de/projects/gigaset/">here, I think...</a> | ||
| 160 | with some details <a href="http://heinz.hippenstiel.org/familie/hp/hobby/gigaset_se515dsl.html">here.</a> | ||
| 161 | </li><li><a href="http://frwt.stim.ru/">Free Remote Windows Terminal</a> | ||
| 162 | |||
| 163 | </li><li><a href="http://www.zyxel.com/">ZyXEL Routers</a> | ||
| 164 | |||
| 165 | </li> | ||
| 166 | </ul> | ||
| 167 | |||
| 168 | |||
| 169 | <!--#include file="footer.html" --> | ||
| 170 | |||
diff --git a/docs/busybox.net/screenshot.html b/docs/busybox.net/screenshot.html new file mode 100644 index 000000000..4e07fdaba --- /dev/null +++ b/docs/busybox.net/screenshot.html | |||
| @@ -0,0 +1,62 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | |||
| 4 | <!-- Begin Screenshot --> | ||
| 5 | |||
| 6 | <h3> Busybox Screenshot! </h3> | ||
| 7 | |||
| 8 | |||
| 9 | Everybody loves to look at screenshots, so here is a live action screenshot of BusyBox. | ||
| 10 | |||
| 11 | <pre style="background-color: black; color: lightgreen; padding: 5px; | ||
| 12 | font-family: monospace; font-size: smaller;" width="100"> | ||
| 13 | |||
| 14 | |||
| 15 | $ ./busybox | ||
| 16 | BusyBox v1.1.2 (2006.04.11-08:27+0000) multi-call binary | ||
| 17 | |||
| 18 | Usage: busybox [function] [arguments]... | ||
| 19 | or: [function] [arguments]... | ||
| 20 | |||
| 21 | BusyBox is a multi-call binary that combines many common Unix | ||
| 22 | utilities into a single executable. Most people will create a | ||
| 23 | link to busybox for each function they wish to use and BusyBox | ||
| 24 | will act like whatever it was invoked as! | ||
| 25 | |||
| 26 | Currently defined functions: | ||
| 27 | [, [[, addgroup, adduser, adjtimex, ar, arping, ash, awk, basename, | ||
| 28 | bbconfig, bunzip2, busybox, bzcat, cal, cat, chattr, chgrp, chmod, | ||
| 29 | chown, chroot, chvt, clear, cmp, comm, cp, cpio, crond, crontab, | ||
| 30 | cut, date, dc, dd, deallocvt, delgroup, deluser, devfsd, df, dirname, | ||
| 31 | dmesg, dnsd, dos2unix, dpkg, dpkg-deb, du, dumpkmap, dumpleases, | ||
| 32 | e2fsck, e2label, echo, egrep, eject, env, ether-wake, expr, fakeidentd, | ||
| 33 | false, fbset, fdflush, fdformat, fdisk, fgrep, find, findfs, fold, | ||
| 34 | free, freeramdisk, fsck, fsck.ext2, fsck.ext3, fsck.minix, ftpget, | ||
| 35 | ftpput, fuser, getopt, getty, grep, gunzip, gzip, halt, hdparm, | ||
| 36 | head, hexdump, hostid, hostname, httpd, hush, hwclock, id, ifconfig, | ||
| 37 | ifdown, ifup, inetd, init, insmod, install, ip, ipaddr, ipcalc, | ||
| 38 | ipcrm, ipcs, iplink, iproute, iptunnel, kill, killall, klogd, | ||
| 39 | lash, last, length, less, linux32, linux64, linuxrc, ln, loadfont, | ||
| 40 | loadkmap, logger, login, logname, logread, losetup, ls, lsattr, | ||
| 41 | lsmod, lzmacat, makedevs, md5sum, mdev, mesg, mkdir, mke2fs, mkfifo, | ||
| 42 | mkfs.ext2, mkfs.ext3, mkfs.minix, mknod, mkswap, mktemp, modprobe, | ||
| 43 | more, mount, mountpoint, msh, mt, mv, nameif, nc, netstat, nice, | ||
| 44 | nohup, nslookup, od, openvt, passwd, patch, pidof, ping, ping6, | ||
| 45 | pipe_progress, pivot_root, poweroff, printenv, printf, ps, pwd, | ||
| 46 | rdate, readlink, readprofile, realpath, reboot, renice, reset, | ||
| 47 | rm, rmdir, rmmod, route, rpm, rpm2cpio, run-parts, runlevel, rx, | ||
| 48 | sed, seq, setarch, setconsole, setkeycodes, setsid, sha1sum, sleep, | ||
| 49 | sort, start-stop-daemon, stat, strings, stty, su, sulogin, sum, | ||
| 50 | swapoff, swapon, switch_root, sync, sysctl, syslogd, tail, tar, | ||
| 51 | tee, telnet, telnetd, test, tftp, time, top, touch, tr, traceroute, | ||
| 52 | true, tty, tune2fs, udhcpc, udhcpd, umount, uname, uncompress, | ||
| 53 | uniq, unix2dos, unlzma, unzip, uptime, usleep, uudecode, uuencode, | ||
| 54 | vconfig, vi, vlock, watch, watchdog, wc, wget, which, who, whoami, | ||
| 55 | xargs, yes, zcat, zcip | ||
| 56 | |||
| 57 | $ <span style="text-decoration:blink;">_</span> | ||
| 58 | |||
| 59 | </pre> | ||
| 60 | |||
| 61 | <!--#include file="footer.html" --> | ||
| 62 | |||
diff --git a/docs/busybox.net/shame.html b/docs/busybox.net/shame.html new file mode 100644 index 000000000..d9da44b69 --- /dev/null +++ b/docs/busybox.net/shame.html | |||
| @@ -0,0 +1,82 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | |||
| 4 | <h3>Hall of Shame!!!</h3> | ||
| 5 | |||
| 6 | <p>This page is no longer updated, these days we forward this sort of | ||
| 7 | thing to the <a href="http://www.softwarefreedom.org">Software Freedom Law | ||
| 8 | Center</a> instead.</p> | ||
| 9 | |||
| 10 | <p>The following products and/or projects appear to use BusyBox, but do not | ||
| 11 | appear to release source code as required by the <a | ||
| 12 | href="/license.html">BusyBox license</a>. This is a violation of the law! | ||
| 13 | The distributors of these products are invited to contact <a href= | ||
| 14 | "mailto:andersen@codepoet.org">Erik Andersen</a> if they have any confusion | ||
| 15 | as to what is needed to bring their products into compliance, or if they have | ||
| 16 | already brought their product into compliance and wish to be removed from the | ||
| 17 | Hall of Shame. | ||
| 18 | |||
| 19 | <p> | ||
| 20 | |||
| 21 | Here are the details of <a href="/license.html">exactly how to comply | ||
| 22 | with the BusyBox license</a>, so there should be no question as to | ||
| 23 | exactly what is expected. | ||
| 24 | Complying with the Busybox license is easy and completely free, so the | ||
| 25 | companies listed below should be ashamed of themselves. Furthermore, each | ||
| 26 | product listed here is subject to being legally ordered to cease and desist | ||
| 27 | distribution for violation of copyright law, and the distributor of each | ||
| 28 | product is subject to being sued for statutory copyright infringement damages | ||
| 29 | of up to $150,000 per work plus legal fees. Nobody wants to be sued, and <a | ||
| 30 | href="mailto:andersen@codepoet.org">Erik</a> certainly would prefer to spend | ||
| 31 | his time doing better things than sue people. But he will sue if forced to | ||
| 32 | do so to maintain compliance. | ||
| 33 | |||
| 34 | <p> | ||
| 35 | |||
| 36 | Do everyone a favor and don't break the law -- if you use busybox, comply with | ||
| 37 | the busybox license by releasing the source code with your product. | ||
| 38 | |||
| 39 | <p> | ||
| 40 | |||
| 41 | <ul> | ||
| 42 | |||
| 43 | <li><a href="http://www.trittontechnologies.com/products.html">Tritton Technologies NAS120</a> | ||
| 44 | <br>see <a href="http://www.ussg.iu.edu/hypermail/linux/kernel/0404.0/1611.html">here for details</a> | ||
| 45 | <li><a href="http://www.macsense.com/product/homepod/">Macsense HomePod</a> | ||
| 46 | <br>with details | ||
| 47 | <a href="http://developer.gloolabs.com/modules.php?op=modload&name=Forums&file=viewtopic&topic=123&forum=7">here</a> | ||
| 48 | <li><a href="http://www.cpx.com/products.asp?c=Wireless+Products">Compex Wireless Products</a> | ||
| 49 | <br>appears to be running v0.60.5 with Linux version 2.4.20-uc0 on ColdFire, | ||
| 50 | but no source code is mentioned or offered. | ||
| 51 | <li><a href="http://www.inventel.com/en/product/datasheet/10/">Inventel DW 200 wireless/ADSL router</a> | ||
| 52 | <li><a href="http://www.sweex.com/product.asp">Sweex DSL router</a> | ||
| 53 | <br>appears to be running BusyBox v1.00-pre2 and udhcpd, but no source | ||
| 54 | code is mentioned or offered. | ||
| 55 | <li><a href="http://www.trendware.com/products/TEW-410APB.htm">TRENDnet TEW-410APB</a> | ||
| 56 | </li><li><a href="http://www.hauppauge.com/Pages/products/data_mediamvp.html">Hauppauge Media MVP</a> | ||
| 57 | <br>Hauppauge contacted me on 16 Dec 2003, and claims to be working on resolving this problem. | ||
| 58 | </li><li><a href="http://www.hitex.com/download/adescom/data/">TriCore</a> | ||
| 59 | </li><li><a href="http://www.allnet.de/">ALLNET 0186 wireless router</a> | ||
| 60 | </li><li><a href="http://www.dmmtv.com/">Dreambox DM7000S DVB Satellite Receiver</a> | ||
| 61 | <br> Dream Multimedia contacted me on 22 Dec 2003 and is working on resolving this problem. | ||
| 62 | <br> Source _may_ be here: http://cvs.tuxbox.org/cgi-bin/viewcvs.cgi/tuxbox/cdk/ | ||
| 63 | </li><li><a href="http://testing.lkml.org/slashdot.php?mid=331690">Sigma Designs EM8500 based DVD players</a> | ||
| 64 | <br>Source for the Sigma Designs reference platform is found here<br> | ||
| 65 | <a href="http://www.uclinux.org/pub/uClinux/ports/arm/EM8500/uClinux-2.4-sigma.tar.gz">uClinux-2.4-sigma.tar.gz</a>, so while Sigma Designs itself appears to be in compliance, as far as I can tell, | ||
| 66 | no vendors of Sigma Designs EM8500 based devices actually comply with the GPL.... | ||
| 67 | </li><li><a href="http://testing.lkml.org/slashdot.php?mid=433790">Liteon LVD2001 DVD player using the Sigma Designs EM8500</a> | ||
| 68 | </li><li><a href="http://www.rimax.net/">Rimax DVD players using the Sigma Designs EM8500</a> | ||
| 69 | </li><li><a href="http://www.vinc.us/">Bravo DVD players using the Sigma Designs EM8500</a> | ||
| 70 | </li><li><a href="http://www.hb-direct.com/">H&B DX3110 Divx player based on Sigma Designs EM8500</a> | ||
| 71 | </li><li><a href="http://www.recospa.it/mdpro1/index.php">United *DVX4066 mpeg4 capable DVD players</a> | ||
| 72 | </li><li><a href="http://www.a-link.com/RR64AP.html">Avaks alink Roadrunner 64</a> | ||
| 73 | <br> Partial source available, based on source distributed under NDA from <a href="http://www.lsilogic.com/products/dsl_platform_solutions/hb_linuxr2_2.html"> LSILogic</a>. Why the NDA LSILogic, what are you hiding ? | ||
| 74 | <br>To verify the Avaks infrigment see my slashdot <a href="http://slashdot.org/~bug1/journal/">journal</a>. | ||
| 75 | <br>The ZipIt wireless IM device appears to be using Busybox-1.00-pre1 in the ramdisk, however no source has been made available. | ||
| 76 | </li><li>Undoubtedly there are others... Please report them so we can shame them (or if necessary sue them) into compliance. | ||
| 77 | |||
| 78 | </ul> | ||
| 79 | |||
| 80 | |||
| 81 | <!--#include file="footer.html" --> | ||
| 82 | |||
diff --git a/docs/busybox.net/sponsors.html b/docs/busybox.net/sponsors.html new file mode 100644 index 000000000..ba7920bf2 --- /dev/null +++ b/docs/busybox.net/sponsors.html | |||
| @@ -0,0 +1,35 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | <h3>Sponsors</h3> | ||
| 4 | |||
| 5 | <p>Please visit our sponsors and thank them for their support! They have | ||
| 6 | provided money for equipment and bandwidth. Next time you need help with a | ||
| 7 | project, consider these fine companies!</p> | ||
| 8 | |||
| 9 | |||
| 10 | <ul> | ||
| 11 | <li><a href="http://osuosl.org/">OSU OSL</a><br> | ||
| 12 | OSU OSL kindly provides hosting for BusyBox and uClibc. | ||
| 13 | </li> | ||
| 14 | |||
| 15 | <li><a href="http://www.penguru.net">Penguru Consulting</a><br> | ||
| 16 | Custom development for embedded Linux systems and multimedia platforms | ||
| 17 | </li> | ||
| 18 | |||
| 19 | <li><a href="http://opensource.se/">opensource.se</a><br> | ||
| 20 | Embedded open source consulting in Europe. | ||
| 21 | </li> | ||
| 22 | |||
| 23 | <li><a href="http://www.codepoet-consulting.com">Codepoet Consulting</a><br> | ||
| 24 | Custom Linux, embedded Linux, BusyBox, and uClibc development. | ||
| 25 | </li> | ||
| 26 | |||
| 27 | <li><a href="http://www.timesys.com">TimeSys</a><br> | ||
| 28 | Embedded Linux development, cross-compilers, real-time, KGDB, tsrpm and cygwin. | ||
| 29 | </li> | ||
| 30 | </ul> | ||
| 31 | |||
| 32 | <p>If you wish to be a sponsor, or if you have already contributed and would | ||
| 33 | like your name added here, email <a href="mailto:rob@landley.net">Rob</a>.</p> | ||
| 34 | |||
| 35 | <!--#include file="footer.html" --> | ||
diff --git a/docs/busybox.net/subversion.html b/docs/busybox.net/subversion.html new file mode 100644 index 000000000..7fb620f98 --- /dev/null +++ b/docs/busybox.net/subversion.html | |||
| @@ -0,0 +1,52 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | <h3>Accessing Source</h3> | ||
| 4 | |||
| 5 | |||
| 6 | |||
| 7 | <h3>Patches</h3> | ||
| 8 | |||
| 9 | <p>If you don't want to mess with subversion, you can download | ||
| 10 | <a href="/downloads/patches/">all BusyBox patches</a> or check the | ||
| 11 | <a href="/downloads/patches/recent.html">most recent patches</a>. | ||
| 12 | |||
| 13 | <h3>Anonymous Subversion Access</h3> | ||
| 14 | |||
| 15 | We allow anonymous (read-only) Subversion (svn) access to everyone. To | ||
| 16 | grab a copy of the latest version of BusyBox using anonymous svn access: | ||
| 17 | |||
| 18 | <pre> | ||
| 19 | svn co svn://busybox.net/trunk/busybox</pre> | ||
| 20 | |||
| 21 | <p> | ||
| 22 | The current <em>stable branch</em> can be obtained with | ||
| 23 | <pre> | ||
| 24 | svn co svn://busybox.net/branches/busybox_1_1_stable | ||
| 25 | </pre> | ||
| 26 | |||
| 27 | <p> | ||
| 28 | |||
| 29 | If you are not already familiar with using Subversion, I recommend you visit <a | ||
| 30 | href="http://subversion.tigris.org/">the Subversion website</a>. You might | ||
| 31 | also want to read online or buy a copy of <a | ||
| 32 | href="http://svnbook.red-bean.com/">the Subversion Book</a>. If you are | ||
| 33 | already comfortable with using CVS, you may want to skip ahead to the <a | ||
| 34 | href="http://svnbook.red-bean.com/en/1.1/apa.html">Subversion for CVS Users</a> | ||
| 35 | part of the Subversion Book. | ||
| 36 | |||
| 37 | <p> | ||
| 38 | |||
| 39 | Once you've checked out a copy of the source tree, you can update your source | ||
| 40 | tree at any time so it is in sync with the latest and greatest by entering your | ||
| 41 | BusyBox directory and running the command: | ||
| 42 | |||
| 43 | <pre> | ||
| 44 | svn update</pre> | ||
| 45 | |||
| 46 | Because you've only been granted anonymous access to the tree, you won't be | ||
| 47 | able to commit any changes. Changes can be submitted for inclusion by posting | ||
| 48 | them to the BusyBox mailing list. For those that are actively contributing | ||
| 49 | <a href="developer.html">Subversion commit access</a> can be made available. | ||
| 50 | |||
| 51 | <!--#include file="footer.html" --> | ||
| 52 | |||
diff --git a/docs/busybox.net/tinyutils.html b/docs/busybox.net/tinyutils.html new file mode 100644 index 000000000..9122d6e35 --- /dev/null +++ b/docs/busybox.net/tinyutils.html | |||
| @@ -0,0 +1,86 @@ | |||
| 1 | <!--#include file="header.html" --> | ||
| 2 | |||
| 3 | |||
| 4 | <h3>External Tiny Utilities</h3> | ||
| 5 | |||
| 6 | This is a list of tiny utilities whose functionality is not provided by | ||
| 7 | busybox. If you have additional suggestions, please send an e-mail to our | ||
| 8 | dev mailing list. | ||
| 9 | |||
| 10 | <br><br> | ||
| 11 | |||
| 12 | <table border=1> | ||
| 13 | <tr> | ||
| 14 | <th>Feature</th> | ||
| 15 | <th>Utilities</th> | ||
| 16 | </tr> | ||
| 17 | |||
| 18 | <tr> | ||
| 19 | <td>SSH</td> | ||
| 20 | <td><a href="http://matt.ucc.asn.au/dropbear/">Dropbear</a> has both an ssh server and an ssh client that together come in around 100k. It has no external | ||
| 21 | dependencies (I.E. it does not depend on OpenSSL, using a built-in copy of | ||
| 22 | LibTomCrypt instead). It's actively maintained, with a quiet but responsive | ||
| 23 | mailing list.</td> | ||
| 24 | </tr> | ||
| 25 | |||
| 26 | <tr> | ||
| 27 | <td>SMTP</td> | ||
| 28 | <td><a href="ftp://ftp.debian.org/debian/pool/main/s/ssmtp/">ssmtp</a> is an extremely simple Mail Transfer Agent.</td> | ||
| 29 | </tr> | ||
| 30 | |||
| 31 | <tr> | ||
| 32 | <td>ntp</td> | ||
| 33 | <td><a href="http://doolittle.icarus.com/ntpclient/">ntpclient</a> is a | ||
| 34 | tiny ntp client. BusyBox has rdate to set the date from a remote server, but | ||
| 35 | if you want a daemon to repeatedly adjust the clock over time, try that.</td> | ||
| 36 | </table> | ||
| 37 | |||
| 38 | <p>In a gui environment, you'll probably want a web browser. | ||
| 39 | <a href="http://www.konqueror.org/embedded/">Konqueror Embedded</a> requires QT | ||
| 40 | (or QT Embedded), but not KDE. The <a href="http://www.dillo.org/">Dillo</a> | ||
| 41 | requires GTK+, but not Gnome. Or you can try the <a href="http://links.twibright.com/">graphical | ||
| 42 | version of links</a>.</p> | ||
| 43 | |||
| 44 | <h3>SCRIPTING LANGUAGES</h3> | ||
| 45 | <p>Although busybox has built-in support for shell scripts, plenty of other | ||
| 46 | small scripting languages are available on the net. A few examples:</p> | ||
| 47 | <table border=1> | ||
| 48 | <tr> | ||
| 49 | <th><language></th> | ||
| 50 | <th><description></th> | ||
| 51 | </tr> | ||
| 52 | <tr> | ||
| 53 | <td> <a href=http://www.foo.be/docs/tpj/issues/vol5_3/tpj0503-0003.html>microperl</a> </td> | ||
| 54 | <td> A small standalone perl interpreter that can be built from the perl source | ||
| 55 | s via "make -f Makefile.micro". If you really feel the need for perl on an embe | ||
| 56 | dded system, this is where to start. | ||
| 57 | </tr> | ||
| 58 | <tr> | ||
| 59 | |||
| 60 | <td><a href=http://www.lua.org/pil/>Lua</a></td> | ||
| 61 | <td>If you just want a small embedded scripting language to write <em>new</en> | ||
| 62 | code in, this Brazilian import is lightweight, fairly popular, and has | ||
| 63 | a complete book about it online.</td> | ||
| 64 | </tr> | ||
| 65 | |||
| 66 | <tr> | ||
| 67 | <td><a href= http://www.star.le.ac.uk/%7Etjg/rc/>rc</a></td> | ||
| 68 | <td>The PLAN9 shell. Not compatible with conventional bourne shell syntax, | ||
| 69 | but fairly lightweight and small.</td> | ||
| 70 | </tr> | ||
| 71 | |||
| 72 | </tr> | ||
| 73 | <tr> | ||
| 74 | <td><a href=http://www.forth.org>forth</a></td> | ||
| 75 | <td>A well known language for fast and small programs, decades old but still | ||
| 76 | in use for everything from OpenBIOS to computer controlled engine timing.</td> | ||
| 77 | </tr> | ||
| 78 | </table> | ||
| 79 | |||
| 80 | <p>For more information, you probably want to look at | ||
| 81 | <a href=http://buildroot.uclibc.org>buildroot</a> and | ||
| 82 | <a href=http://gentoo-wiki.com/TinyGentoo>TinyGentoo</a>, which | ||
| 83 | build and use tiny utilities for all sorts of things.</p> | ||
| 84 | |||
| 85 | <!--#include file="footer.html" --> | ||
| 86 | |||
diff --git a/docs/busybox_footer.pod b/docs/busybox_footer.pod new file mode 100644 index 000000000..b2835f6bc --- /dev/null +++ b/docs/busybox_footer.pod | |||
| @@ -0,0 +1,258 @@ | |||
| 1 | =back | ||
| 2 | |||
| 3 | =head1 LIBC NSS | ||
| 4 | |||
| 5 | GNU Libc (glibc) uses the Name Service Switch (NSS) to configure the behavior | ||
| 6 | of the C library for the local environment, and to configure how it reads | ||
| 7 | system data, such as passwords and group information. This is implemented | ||
| 8 | using an /etc/nsswitch.conf configuration file, and using one or more of the | ||
| 9 | /lib/libnss_* libraries. BusyBox tries to avoid using any libc calls that make | ||
| 10 | use of NSS. Some applets however, such as login and su, will use libc functions | ||
| 11 | that require NSS. | ||
| 12 | |||
| 13 | If you enable CONFIG_USE_BB_PWD_GRP, BusyBox will use internal functions to | ||
| 14 | directly access the /etc/passwd, /etc/group, and /etc/shadow files without | ||
| 15 | using NSS. This may allow you to run your system without the need for | ||
| 16 | installing any of the NSS configuration files and libraries. | ||
| 17 | |||
| 18 | When used with glibc, the BusyBox 'networking' applets will similarly require | ||
| 19 | that you install at least some of the glibc NSS stuff (in particular, | ||
| 20 | /etc/nsswitch.conf, /lib/libnss_dns*, /lib/libnss_files*, and /lib/libresolv*). | ||
| 21 | |||
| 22 | Shameless Plug: As an alternative, one could use a C library such as uClibc. In | ||
| 23 | addition to making your system significantly smaller, uClibc does not require the | ||
| 24 | use of any NSS support files or libraries. | ||
| 25 | |||
| 26 | =head1 MAINTAINER | ||
| 27 | |||
| 28 | Denis Vlasenko <vda.linux@googlemail.com> | ||
| 29 | |||
| 30 | =head1 AUTHORS | ||
| 31 | |||
| 32 | The following people have contributed code to BusyBox whether they know it or | ||
| 33 | not. If you have written code included in BusyBox, you should probably be | ||
| 34 | listed here so you can obtain your bit of eternal glory. If you should be | ||
| 35 | listed here, or the description of what you have done needs more detail, or is | ||
| 36 | incorect, please send in an update. | ||
| 37 | |||
| 38 | |||
| 39 | =for html <br> | ||
| 40 | |||
| 41 | Emanuele Aina <emanuele.aina@tiscali.it> | ||
| 42 | run-parts | ||
| 43 | |||
| 44 | =for html <br> | ||
| 45 | |||
| 46 | Erik Andersen <andersen@codepoet.org> | ||
| 47 | |||
| 48 | Tons of new stuff, major rewrite of most of the | ||
| 49 | core apps, tons of new apps as noted in header files. | ||
| 50 | Lots of tedious effort writing these boring docs that | ||
| 51 | nobody is going to actually read. | ||
| 52 | |||
| 53 | =for html <br> | ||
| 54 | |||
| 55 | Laurence Anderson <l.d.anderson@warwick.ac.uk> | ||
| 56 | |||
| 57 | rpm2cpio, unzip, get_header_cpio, read_gz interface, rpm | ||
| 58 | |||
| 59 | =for html <br> | ||
| 60 | |||
| 61 | Jeff Angielski <jeff@theptrgroup.com> | ||
| 62 | |||
| 63 | ftpput, ftpget | ||
| 64 | |||
| 65 | =for html <br> | ||
| 66 | |||
| 67 | Edward Betts <edward@debian.org> | ||
| 68 | |||
| 69 | expr, hostid, logname, whoami | ||
| 70 | |||
| 71 | =for html <br> | ||
| 72 | |||
| 73 | John Beppu <beppu@codepoet.org> | ||
| 74 | |||
| 75 | du, nslookup, sort | ||
| 76 | |||
| 77 | =for html <br> | ||
| 78 | |||
| 79 | Brian Candler <B.Candler@pobox.com> | ||
| 80 | |||
| 81 | tiny-ls(ls) | ||
| 82 | |||
| 83 | =for html <br> | ||
| 84 | |||
| 85 | Randolph Chung <tausq@debian.org> | ||
| 86 | |||
| 87 | fbset, ping, hostname | ||
| 88 | |||
| 89 | =for html <br> | ||
| 90 | |||
| 91 | Dave Cinege <dcinege@psychosis.com> | ||
| 92 | |||
| 93 | more(v2), makedevs, dutmp, modularization, auto links file, | ||
| 94 | various fixes, Linux Router Project maintenance | ||
| 95 | |||
| 96 | =for html <br> | ||
| 97 | |||
| 98 | Jordan Crouse <jordan@cosmicpenguin.net> | ||
| 99 | |||
| 100 | ipcalc | ||
| 101 | |||
| 102 | =for html <br> | ||
| 103 | |||
| 104 | Magnus Damm <damm@opensource.se> | ||
| 105 | |||
| 106 | tftp client insmod powerpc support | ||
| 107 | |||
| 108 | =for html <br> | ||
| 109 | |||
| 110 | Larry Doolittle <ldoolitt@recycle.lbl.gov> | ||
| 111 | |||
| 112 | pristine source directory compilation, lots of patches and fixes. | ||
| 113 | |||
| 114 | =for html <br> | ||
| 115 | |||
| 116 | Glenn Engel <glenne@engel.org> | ||
| 117 | |||
| 118 | httpd | ||
| 119 | |||
| 120 | =for html <br> | ||
| 121 | |||
| 122 | Gennady Feldman <gfeldman@gena01.com> | ||
| 123 | |||
| 124 | Sysklogd (single threaded syslogd, IPC Circular buffer support, | ||
| 125 | logread), various fixes. | ||
| 126 | |||
| 127 | =for html <br> | ||
| 128 | |||
| 129 | Karl M. Hegbloom <karlheg@debian.org> | ||
| 130 | |||
| 131 | cp_mv.c, the test suite, various fixes to utility.c, &c. | ||
| 132 | |||
| 133 | =for html <br> | ||
| 134 | |||
| 135 | Daniel Jacobowitz <dan@debian.org> | ||
| 136 | |||
| 137 | mktemp.c | ||
| 138 | |||
| 139 | =for html <br> | ||
| 140 | |||
| 141 | Matt Kraai <kraai@alumni.cmu.edu> | ||
| 142 | |||
| 143 | documentation, bugfixes, test suite | ||
| 144 | |||
| 145 | =for html <br> | ||
| 146 | |||
| 147 | Stephan Linz <linz@li-pro.net> | ||
| 148 | |||
| 149 | ipcalc, Red Hat equivalence | ||
| 150 | |||
| 151 | =for html <br> | ||
| 152 | |||
| 153 | John Lombardo <john@deltanet.com> | ||
| 154 | |||
| 155 | tr | ||
| 156 | |||
| 157 | =for html <br> | ||
| 158 | |||
| 159 | Glenn McGrath <bug1@iinet.net.au> | ||
| 160 | |||
| 161 | Common unarchving code and unarchiving applets, ifupdown, ftpgetput, | ||
| 162 | nameif, sed, patch, fold, install, uudecode. | ||
| 163 | Various bugfixes, review and apply numerous patches. | ||
| 164 | |||
| 165 | =for html <br> | ||
| 166 | |||
| 167 | Manuel Novoa III <mjn3@codepoet.org> | ||
| 168 | |||
| 169 | cat, head, mkfifo, mknod, rmdir, sleep, tee, tty, uniq, usleep, wc, yes, | ||
| 170 | mesg, vconfig, make_directory, parse_mode, dirname, mode_string, | ||
| 171 | get_last_path_component, simplify_path, and a number trivial libbb routines | ||
| 172 | |||
| 173 | also bug fixes, partial rewrites, and size optimizations in | ||
| 174 | ash, basename, cal, cmp, cp, df, du, echo, env, ln, logname, md5sum, mkdir, | ||
| 175 | mv, realpath, rm, sort, tail, touch, uname, watch, arith, human_readable, | ||
| 176 | interface, dutmp, ifconfig, route | ||
| 177 | |||
| 178 | =for html <br> | ||
| 179 | |||
| 180 | Vladimir Oleynik <dzo@simtreas.ru> | ||
| 181 | |||
| 182 | cmdedit; xargs(current), httpd(current); | ||
| 183 | ports: ash, crond, fdisk, inetd, stty, traceroute, top; | ||
| 184 | locale, various fixes | ||
| 185 | and irreconcilable critic of everything not perfect. | ||
| 186 | |||
| 187 | =for html <br> | ||
| 188 | |||
| 189 | Bruce Perens <bruce@pixar.com> | ||
| 190 | |||
| 191 | Original author of BusyBox in 1995, 1996. Some of his code can | ||
| 192 | still be found hiding here and there... | ||
| 193 | |||
| 194 | =for html <br> | ||
| 195 | |||
| 196 | Tim Riker <Tim@Rikers.org> | ||
| 197 | |||
| 198 | bug fixes, member of fan club | ||
| 199 | |||
| 200 | =for html <br> | ||
| 201 | |||
| 202 | Kent Robotti <robotti@metconnect.com> | ||
| 203 | |||
| 204 | reset, tons and tons of bug reports and patches. | ||
| 205 | |||
| 206 | =for html <br> | ||
| 207 | |||
| 208 | Chip Rosenthal <chip@unicom.com>, <crosenth@covad.com> | ||
| 209 | |||
| 210 | wget - Contributed by permission of Covad Communications | ||
| 211 | |||
| 212 | =for html <br> | ||
| 213 | |||
| 214 | Pavel Roskin <proski@gnu.org> | ||
| 215 | |||
| 216 | Lots of bugs fixes and patches. | ||
| 217 | |||
| 218 | =for html <br> | ||
| 219 | |||
| 220 | Gyepi Sam <gyepi@praxis-sw.com> | ||
| 221 | |||
| 222 | Remote logging feature for syslogd | ||
| 223 | |||
| 224 | =for html <br> | ||
| 225 | |||
| 226 | Linus Torvalds <torvalds@transmeta.com> | ||
| 227 | |||
| 228 | mkswap, fsck.minix, mkfs.minix | ||
| 229 | |||
| 230 | =for html <br> | ||
| 231 | |||
| 232 | Mark Whitley <markw@codepoet.org> | ||
| 233 | |||
| 234 | grep, sed, cut, xargs(previous), | ||
| 235 | style-guide, new-applet-HOWTO, bug fixes, etc. | ||
| 236 | |||
| 237 | =for html <br> | ||
| 238 | |||
| 239 | Charles P. Wright <cpwright@villagenet.com> | ||
| 240 | |||
| 241 | gzip, mini-netcat(nc) | ||
| 242 | |||
| 243 | =for html <br> | ||
| 244 | |||
| 245 | Enrique Zanardi <ezanardi@ull.es> | ||
| 246 | |||
| 247 | tarcat (since removed), loadkmap, various fixes, Debian maintenance | ||
| 248 | |||
| 249 | =for html <br> | ||
| 250 | |||
| 251 | Tito Ragusa <farmatito@tiscali.it> | ||
| 252 | |||
| 253 | devfsd and size optimizations in strings, openvt and deallocvt. | ||
| 254 | |||
| 255 | =cut | ||
| 256 | |||
| 257 | # $Id: busybox_footer.pod,v 1.18 2004/04/25 06:05:14 bug1 Exp $ | ||
| 258 | |||
diff --git a/docs/busybox_header.pod b/docs/busybox_header.pod new file mode 100644 index 000000000..ab1ebd501 --- /dev/null +++ b/docs/busybox_header.pod | |||
| @@ -0,0 +1,82 @@ | |||
| 1 | # vi: set sw=4 ts=4: | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | BusyBox - The Swiss Army Knife of Embedded Linux | ||
| 6 | |||
| 7 | =head1 SYNTAX | ||
| 8 | |||
| 9 | BusyBox <function> [arguments...] # or | ||
| 10 | |||
| 11 | <function> [arguments...] # if symlinked | ||
| 12 | |||
| 13 | =head1 DESCRIPTION | ||
| 14 | |||
| 15 | BusyBox combines tiny versions of many common UNIX utilities into a single | ||
| 16 | small executable. It provides minimalist replacements for most of the utilities | ||
| 17 | you usually find in GNU coreutils, util-linux, etc. The utilities in BusyBox | ||
| 18 | generally have fewer options than their full-featured GNU cousins; however, the | ||
| 19 | options that are included provide the expected functionality and behave very | ||
| 20 | much like their GNU counterparts. | ||
| 21 | |||
| 22 | BusyBox has been written with size-optimization and limited resources in mind. | ||
| 23 | It is also extremely modular so you can easily include or exclude commands (or | ||
| 24 | features) at compile time. This makes it easy to customize your embedded | ||
| 25 | systems. To create a working system, just add /dev, /etc, and a Linux kernel. | ||
| 26 | BusyBox provides a fairly complete POSIX environment for any small or embedded | ||
| 27 | system. | ||
| 28 | |||
| 29 | BusyBox is extremely configurable. This allows you to include only the | ||
| 30 | components you need, thereby reducing binary size. Run 'make config' or 'make | ||
| 31 | menuconfig' to select the functionality that you wish to enable. Then run | ||
| 32 | 'make' to compile BusyBox using your configuration. | ||
| 33 | |||
| 34 | After the compile has finished, you should use 'make install' to install | ||
| 35 | BusyBox. This will install the 'bin/busybox' binary, in the target directory | ||
| 36 | specified by PREFIX. PREFIX can be set when configuring BusyBox, or you can | ||
| 37 | specify an alternative location at install time (i.e., with a command line | ||
| 38 | like 'make PREFIX=/tmp/foo install'). If you enabled any applet installation | ||
| 39 | scheme (either as symlinks or hardlinks), these will also be installed in | ||
| 40 | the location pointed to by PREFIX. | ||
| 41 | |||
| 42 | =head1 USAGE | ||
| 43 | |||
| 44 | BusyBox is a multi-call binary. A multi-call binary is an executable program | ||
| 45 | that performs the same job as more than one utility program. That means there | ||
| 46 | is just a single BusyBox binary, but that single binary acts like a large | ||
| 47 | number of utilities. This allows BusyBox to be smaller since all the built-in | ||
| 48 | utility programs (we call them applets) can share code for many common operations. | ||
| 49 | |||
| 50 | You can also invoke BusyBox by issuing a command as an argument on the | ||
| 51 | command line. For example, entering | ||
| 52 | |||
| 53 | /bin/busybox ls | ||
| 54 | |||
| 55 | will also cause BusyBox to behave as 'ls'. | ||
| 56 | |||
| 57 | Of course, adding '/bin/busybox' into every command would be painful. So most | ||
| 58 | people will invoke BusyBox using links to the BusyBox binary. | ||
| 59 | |||
| 60 | For example, entering | ||
| 61 | |||
| 62 | ln -s /bin/busybox ls | ||
| 63 | ./ls | ||
| 64 | |||
| 65 | will cause BusyBox to behave as 'ls' (if the 'ls' command has been compiled | ||
| 66 | into BusyBox). Generally speaking, you should never need to make all these | ||
| 67 | links yourself, as the BusyBox build system will do this for you when you run | ||
| 68 | the 'make install' command. | ||
| 69 | |||
| 70 | If you invoke BusyBox with no arguments, it will provide you with a list of the | ||
| 71 | applets that have been compiled into your BusyBox binary. | ||
| 72 | |||
| 73 | =head1 COMMON OPTIONS | ||
| 74 | |||
| 75 | Most BusyBox commands support the B<--help> argument to provide a terse runtime | ||
| 76 | description of their behavior. If the CONFIG_FEATURE_VERBOSE_USAGE option has | ||
| 77 | been enabled, more detailed usage information will also be available. | ||
| 78 | |||
| 79 | =head1 COMMANDS | ||
| 80 | |||
| 81 | Currently defined functions include: | ||
| 82 | |||
diff --git a/docs/contributing.txt b/docs/contributing.txt new file mode 100644 index 000000000..aad43035c --- /dev/null +++ b/docs/contributing.txt | |||
| @@ -0,0 +1,449 @@ | |||
| 1 | Contributing To Busybox | ||
| 2 | ======================= | ||
| 3 | |||
| 4 | This document describes what you need to do to contribute to Busybox, where | ||
| 5 | you can help, guidelines on testing, and how to submit a well-formed patch | ||
| 6 | that is more likely to be accepted. | ||
| 7 | |||
| 8 | The Busybox home page is at: http://busybox.net/ | ||
| 9 | |||
| 10 | |||
| 11 | |||
| 12 | Pre-Contribution Checklist | ||
| 13 | -------------------------- | ||
| 14 | |||
| 15 | So you want to contribute to Busybox, eh? Great, wonderful, glad you want to | ||
| 16 | help. However, before you dive in, headlong and hotfoot, there are some things | ||
| 17 | you need to do: | ||
| 18 | |||
| 19 | |||
| 20 | Checkout the Latest Code from CVS | ||
| 21 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 22 | |||
| 23 | This is a necessary first step. Please do not try to work with the last | ||
| 24 | released version, as there is a good chance that somebody has already fixed | ||
| 25 | the bug you found. Somebody might have even added the feature you had in mind. | ||
| 26 | Don't make your work obsolete before you start! | ||
| 27 | |||
| 28 | For information on how to check out Busybox from CVS, please look at the | ||
| 29 | following links: | ||
| 30 | |||
| 31 | http://busybox.net/cvs_anon.html | ||
| 32 | http://busybox.net/cvs_howto.html | ||
| 33 | |||
| 34 | |||
| 35 | Read the Mailing List | ||
| 36 | ~~~~~~~~~~~~~~~~~~~~~ | ||
| 37 | |||
| 38 | No one is required to read the entire archives of the mailing list, but you | ||
| 39 | should at least read up on what people have been talking about lately. If | ||
| 40 | you've recently discovered a problem, chances are somebody else has too. If | ||
| 41 | you're the first to discover a problem, post a message and let the rest of us | ||
| 42 | know. | ||
| 43 | |||
| 44 | Archives can be found here: | ||
| 45 | |||
| 46 | http://busybox.net/lists/busybox/ | ||
| 47 | |||
| 48 | If you have a serious interest in Busybox, i.e., you are using it day-to-day or | ||
| 49 | as part of an embedded project, it would be a good idea to join the mailing | ||
| 50 | list. | ||
| 51 | |||
| 52 | A web-based sign-up form can be found here: | ||
| 53 | |||
| 54 | http://busybox.net/mailman/listinfo/busybox | ||
| 55 | |||
| 56 | |||
| 57 | Coordinate with the Applet Maintainer | ||
| 58 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 59 | |||
| 60 | Some (not all) of the applets in Busybox are "owned" by a maintainer who has | ||
| 61 | put significant effort into it and is probably more familiar with it than | ||
| 62 | others. To find the maintainer of an applet, look at the top of the .c file | ||
| 63 | for a name following the word 'Copyright' or 'Written by' or 'Maintainer'. | ||
| 64 | |||
| 65 | Before plunging ahead, it's a good idea to send a message to the mailing list | ||
| 66 | that says: "Hey, I was thinking about adding the 'transmogrify' feature to the | ||
| 67 | 'foo' applet. Would this be useful? Is anyone else working on it?" You might | ||
| 68 | want to CC the maintainer (if any) with your question. | ||
| 69 | |||
| 70 | |||
| 71 | |||
| 72 | Areas Where You Can Help | ||
| 73 | ------------------------ | ||
| 74 | |||
| 75 | Busybox can always use improvement! If you're looking for ways to help, there | ||
| 76 | are a variety of areas where you could help. | ||
| 77 | |||
| 78 | |||
| 79 | What Busybox Doesn't Need | ||
| 80 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 81 | |||
| 82 | Before listing the areas where you _can_ help, it's worthwhile to mention the | ||
| 83 | areas where you shouldn't bother. While Busybox strives to be the "Swiss Army | ||
| 84 | Knife" of embedded Linux, there are some applets that will not be accepted: | ||
| 85 | |||
| 86 | - Any filesystem manipulation tools: Busybox is filesystem independent and | ||
| 87 | we do not want to start adding mkfs/fsck tools for every (or any) | ||
| 88 | filesystem under the sun. (fsck_minix.c and mkfs_minix.c are living on | ||
| 89 | borrowed time.) There are far too many of these tools out there. Use | ||
| 90 | the upstream version. Not everything has to be part of Busybox. | ||
| 91 | |||
| 92 | - Any partitioning tools: Partitioning a device is typically done once and | ||
| 93 | only once, and tools which do this generally do not need to reside on the | ||
| 94 | target device (esp a flash device). If you need a partitioning tool, grab | ||
| 95 | one (such as fdisk, sfdisk, or cfdisk from util-linux) and use that, but | ||
| 96 | don't try to merge it into busybox. These are nasty and complex and we | ||
| 97 | don't want to maintain them. | ||
| 98 | |||
| 99 | - Any disk, device, or media-specific tools: Use the -utils or -tools package | ||
| 100 | that was designed for your device; don't try to shoehorn them into Busybox. | ||
| 101 | |||
| 102 | - Any architecture specific tools: Busybox is (or should be) architecture | ||
| 103 | independent. Do not send us tools that cannot be used across multiple | ||
| 104 | platforms / arches. | ||
| 105 | |||
| 106 | - Any daemons that are not essential to basic system operation. To date, only | ||
| 107 | syslogd and klogd meet this requirement. We do not need a web server, an | ||
| 108 | ftp daemon, a dhcp server, a mail transport agent or a dns resolver. If you | ||
| 109 | need one of those, you are welcome to ask the folks on the mailing list for | ||
| 110 | recommendations, but please don't bloat up Busybox with any of these. | ||
| 111 | |||
| 112 | |||
| 113 | Bug Reporting | ||
| 114 | ~~~~~~~~~~~~~ | ||
| 115 | |||
| 116 | If you find bugs, please submit a detailed bug report to the busybox mailing | ||
| 117 | list at busybox@busybox.net. A well-written bug report should include a | ||
| 118 | transcript of a shell session that demonstrates the bad behavior and enables | ||
| 119 | anyone else to duplicate the bug on their own machine. The following is such | ||
| 120 | an example: | ||
| 121 | |||
| 122 | To: busybox@busybox.net | ||
| 123 | From: diligent@testing.linux.org | ||
| 124 | Subject: /bin/date doesn't work | ||
| 125 | |||
| 126 | Package: busybox | ||
| 127 | Version: 1.00 | ||
| 128 | |||
| 129 | When I execute Busybox 'date' it produces unexpected results. | ||
| 130 | With GNU date I get the following output: | ||
| 131 | |||
| 132 | $ date | ||
| 133 | Wed Mar 21 14:19:41 MST 2001 | ||
| 134 | |||
| 135 | But when I use BusyBox date I get this instead: | ||
| 136 | |||
| 137 | $ date | ||
| 138 | llegal instruction | ||
| 139 | |||
| 140 | I am using Debian unstable, kernel version 2.4.19-rmk1 on an Netwinder, | ||
| 141 | and the latest uClibc from CVS. Thanks for the wonderful program! | ||
| 142 | |||
| 143 | -Diligent | ||
| 144 | |||
| 145 | Note the careful description and use of examples showing not only what BusyBox | ||
| 146 | does, but also a counter example showing what an equivalent GNU app does. Bug | ||
| 147 | reports lacking such detail may never be fixed... Thanks for understanding. | ||
| 148 | |||
| 149 | |||
| 150 | |||
| 151 | Write Documentation | ||
| 152 | ~~~~~~~~~~~~~~~~~~~ | ||
| 153 | |||
| 154 | Chances are, documentation in Busybox is either missing or needs improvement. | ||
| 155 | Either way, help is welcome. | ||
| 156 | |||
| 157 | Work is being done to automatically generate documentation from sources, | ||
| 158 | especially from the usage.h file. If you want to correct the documentation, | ||
| 159 | please make changes to the pre-generation parts, rather than the generated | ||
| 160 | documentation. [More to come on this later...] | ||
| 161 | |||
| 162 | It is preferred that modifications to documentation be submitted in patch | ||
| 163 | format (more on this below), but we're a little more lenient when it comes to | ||
| 164 | docs. You could, for example, just say "after the listing of the mount | ||
| 165 | options, the following example would be helpful..." | ||
| 166 | |||
| 167 | |||
| 168 | Consult Existing Sources | ||
| 169 | ~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 170 | |||
| 171 | For a quick listing of "needs work" spots in the sources, cd into the Busybox | ||
| 172 | directory and run the following: | ||
| 173 | |||
| 174 | for i in TODO FIXME XXX; do find -name '*.[ch]'|xargs grep $i; done | ||
| 175 | |||
| 176 | This will show all of the trouble spots or 'questionable' code. Pick a spot, | ||
| 177 | any spot, these are all invitations for you to contribute. | ||
| 178 | |||
| 179 | |||
| 180 | Add a New Applet | ||
| 181 | ~~~~~~~~~~~~~~~~ | ||
| 182 | |||
| 183 | If you want to add a new applet to Busybox, we'd love to see it. However, | ||
| 184 | before you write any code, please ask beforehand on the mailing list something | ||
| 185 | like "Do you think applet 'foo' would be useful in Busybox?" or "Would you | ||
| 186 | guys accept applet 'foo' into Busybox if I were to write it?" If the answer is | ||
| 187 | "no" by the folks on the mailing list, then you've saved yourself some time. | ||
| 188 | Conversely, you could get some positive responses from folks who might be | ||
| 189 | interested in helping you implement it, or can recommend the best approach. | ||
| 190 | Perhaps most importantly, this is your way of calling "dibs" on something and | ||
| 191 | avoiding duplication of effort. | ||
| 192 | |||
| 193 | Also, before you write a line of code, please read the 'new-applet-HOWTO.txt' | ||
| 194 | file in the docs/ directory. | ||
| 195 | |||
| 196 | |||
| 197 | Janitorial Work | ||
| 198 | ~~~~~~~~~~~~~~~ | ||
| 199 | |||
| 200 | These are dirty jobs, but somebody's gotta do 'em. | ||
| 201 | |||
| 202 | - Converting applets to use getopt() for option processing. Type 'find -name | ||
| 203 | '*.c'|grep -L getopt' to get a listing of the applets that currently don't | ||
| 204 | use getopt. If a .c file processes no options, it should have a line that | ||
| 205 | reads: /* no options, no getopt */ somewhere in the file. | ||
| 206 | |||
| 207 | - Replace any "naked" calls to malloc, calloc, realloc, str[n]dup, fopen with | ||
| 208 | the x* equivalents found in libbb/xfuncs.c. | ||
| 209 | |||
| 210 | - Security audits: | ||
| 211 | http://www.securityfocus.com/popups/forums/secprog/intro.shtml | ||
| 212 | |||
| 213 | - Synthetic code removal: http://www.perl.com/pub/2000/06/commify.html - This | ||
| 214 | is very Perl-specific, but the advice given in here applies equally well to | ||
| 215 | C. | ||
| 216 | |||
| 217 | - C library function use audits: Verifying that functions are being used | ||
| 218 | properly (called with the right args), replacing unsafe library functions | ||
| 219 | with safer versions, making sure return codes are being checked, etc. | ||
| 220 | |||
| 221 | - Where appropriate, replace preprocessor defined macros and values with | ||
| 222 | compile-time equivalents. | ||
| 223 | |||
| 224 | - Style guide compliance. See: docs/style-guide.txt | ||
| 225 | |||
| 226 | - Add testcases to tests/testcases. | ||
| 227 | |||
| 228 | - Makefile improvements: | ||
| 229 | http://www.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html | ||
| 230 | (I think the recursive problems are pretty much taken care of at this point, non?) | ||
| 231 | |||
| 232 | - "Ten Commandments" compliance: (this is a "maybe", certainly not as | ||
| 233 | important as any of the previous items.) | ||
| 234 | http://www.lysator.liu.se/c/ten-commandments.html | ||
| 235 | |||
| 236 | Other useful links: | ||
| 237 | |||
| 238 | - the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources | ||
| 239 | |||
| 240 | |||
| 241 | |||
| 242 | Submitting Patches To Busybox | ||
| 243 | ----------------------------- | ||
| 244 | |||
| 245 | Here are some guidelines on how to submit a patch to Busybox. | ||
| 246 | |||
| 247 | |||
| 248 | Making A Patch | ||
| 249 | ~~~~~~~~~~~~~~ | ||
| 250 | |||
| 251 | If you've got anonymous CVS access set up, making a patch is simple. Just make | ||
| 252 | sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'. | ||
| 253 | You can send the resulting .patch file to the mailing list with a description | ||
| 254 | of what it does. (But not before you test it! See the next section for some | ||
| 255 | guidelines.) It is preferred that patches be sent as attachments, but it is | ||
| 256 | not required. | ||
| 257 | |||
| 258 | Also, feel free to help test other people's patches and reply to them with | ||
| 259 | comments. You can apply a patch by saving it into your busybox/ directory and | ||
| 260 | typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test | ||
| 261 | if it works as advertised, and post your findings to the mailing list. | ||
| 262 | |||
| 263 | NOTE: Please do not include extraneous or irrelevant changes in your patches. | ||
| 264 | Please do not try to "bundle" two patches together into one. Make single, | ||
| 265 | discreet changes on a per-patch basis. Sometimes you need to make a patch that | ||
| 266 | touches code in many places, but these kind of patches are rare and should be | ||
| 267 | coordinated with a maintainer. | ||
| 268 | |||
| 269 | |||
| 270 | Testing Guidelines | ||
| 271 | ~~~~~~~~~~~~~~~~~~ | ||
| 272 | |||
| 273 | It's considered good form to test your new feature before you submit a patch | ||
| 274 | to the mailing list, and especially before you commit a change to CVS. Here | ||
| 275 | are some guidelines on how to test your changes. | ||
| 276 | |||
| 277 | - Always test Busybox applets against GNU counterparts and make sure the | ||
| 278 | behavior / output is identical between the two. | ||
| 279 | |||
| 280 | - Try several different permutations and combinations of the features you're | ||
| 281 | adding (i.e., different combinations of command-line switches) and make sure | ||
| 282 | they all work; make sure one feature does not interfere with another. | ||
| 283 | |||
| 284 | - Make sure you test compiling against the source both with the feature | ||
| 285 | turned on and turned off in Config.h and make sure Busybox compiles cleanly | ||
| 286 | both ways. | ||
| 287 | |||
| 288 | - Run the multibuild.pl script in the tests directory and make sure | ||
| 289 | everything checks out OK. (Do this from within the busybox/ directory by | ||
| 290 | typing: 'tests/multibuild.pl'.) | ||
| 291 | |||
| 292 | |||
| 293 | Making Sure Your Patch Doesn't Get Lost | ||
| 294 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 295 | |||
| 296 | If you don't want your patch to be lost or forgotten, send it to the busybox | ||
| 297 | mailing list with a subject line something like this: | ||
| 298 | |||
| 299 | [PATCH] - Adds "transmogrify" feature to "foo" | ||
| 300 | |||
| 301 | In the body, you should have a pseudo-header that looks like the following: | ||
| 302 | |||
| 303 | Package: busybox | ||
| 304 | Version: v1.01pre (or whatever the current version is) | ||
| 305 | Severity: wishlist | ||
| 306 | |||
| 307 | The remainder of the body should read along these lines: | ||
| 308 | |||
| 309 | This patch adds the "transmogrify" feature to the "foo" applet. I have | ||
| 310 | tested this on [arch] system(s) and it works. I have tested it against the | ||
| 311 | GNU counterparts and the outputs are identical. I have run the scripts in | ||
| 312 | the 'tests' directory and nothing breaks. | ||
| 313 | |||
| 314 | |||
| 315 | |||
| 316 | Improving Your Chances of Patch Acceptance | ||
| 317 | ------------------------------------------ | ||
| 318 | |||
| 319 | Even after you send a brilliant patch to the mailing list, sometimes it can go | ||
| 320 | unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an | ||
| 321 | unfortunate fact of life, but there are steps you can take to help your patch | ||
| 322 | get noticed and convince a maintainer that it should be added: | ||
| 323 | |||
| 324 | |||
| 325 | Be Succinct | ||
| 326 | ~~~~~~~~~~~ | ||
| 327 | |||
| 328 | A patch that includes small, isolated, obvious changes is more likely to be | ||
| 329 | accepted than a patch that touches code in lots of different places or makes | ||
| 330 | sweeping, dubious changes. | ||
| 331 | |||
| 332 | |||
| 333 | Back It Up | ||
| 334 | ~~~~~~~~~~ | ||
| 335 | |||
| 336 | Hard facts on why your patch is better than the existing code will go a long | ||
| 337 | way toward convincing maintainers that your patch should be included. | ||
| 338 | Specifically, patches are more likely to be accepted if they are provably more | ||
| 339 | correct, smaller, faster, simpler, or more maintainable than the existing | ||
| 340 | code. | ||
| 341 | |||
| 342 | Conversely, any patch that is supported with nothing more than "I think this | ||
| 343 | would be cool" or "this patch is good because I say it is and I've got a Phd | ||
| 344 | in Computer Science" will likely be ignored. | ||
| 345 | |||
| 346 | |||
| 347 | Follow The Style Guide | ||
| 348 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
| 349 | |||
| 350 | It's considered good form to abide by the established coding style used in a | ||
| 351 | project; Busybox is no exception. We have gone so far as to delineate the | ||
| 352 | "elements of Busybox style" in the file docs/style-guide.txt. Please follow | ||
| 353 | them. | ||
| 354 | |||
| 355 | |||
| 356 | Work With Someone Else | ||
| 357 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
| 358 | |||
| 359 | Working on a patch in isolation is less effective than working with someone | ||
| 360 | else for a variety of reasons. If another Busybox user is interested in what | ||
| 361 | you're doing, then it's two (or more) voices instead of one that can petition | ||
| 362 | for inclusion of the patch. You'll also have more people that can test your | ||
| 363 | changes, or even offer suggestions on better approaches you could take. | ||
| 364 | |||
| 365 | Getting other folks interested follows as a natural course if you've received | ||
| 366 | responses from queries to applet maintainer or positive responses from folks | ||
| 367 | on the mailing list. | ||
| 368 | |||
| 369 | We've made strident efforts to put a useful "collaboration" infrastructure in | ||
| 370 | place in the form of mailing lists, the bug tracking system, and CVS. Please | ||
| 371 | use these resources. | ||
| 372 | |||
| 373 | |||
| 374 | Send Patches to the Bug Tracking System | ||
| 375 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 376 | |||
| 377 | This was mentioned above in the "Making Sure Your Patch Doesn't Get Lost" | ||
| 378 | section, but it is worth mentioning again. A patch sent to the mailing list | ||
| 379 | might be unnoticed and forgotten. A patch sent to the bug tracking system will | ||
| 380 | be stored and closely connected to the bug it fixes. | ||
| 381 | |||
| 382 | |||
| 383 | Be Polite | ||
| 384 | ~~~~~~~~~ | ||
| 385 | |||
| 386 | The old saying "You'll catch more flies with honey than you will with vinegar" | ||
| 387 | applies when submitting patches to the mailing list for approval. The way you | ||
| 388 | present your patch is sometimes just as important as the actual patch itself | ||
| 389 | (if not more so). Being rude to the maintainers is not an effective way to | ||
| 390 | convince them that your patch should be included; it will likely have the | ||
| 391 | opposite effect. | ||
| 392 | |||
| 393 | |||
| 394 | |||
| 395 | Committing Changes to CVS | ||
| 396 | ------------------------- | ||
| 397 | |||
| 398 | If you submit several patches that demonstrate that you are a skilled and wise | ||
| 399 | coder, you may be invited to become a committer, thus enabling you to commit | ||
| 400 | changes directly to CVS. This is nice because you don't have to wait for | ||
| 401 | someone else to commit your change for you, you can just do it yourself. | ||
| 402 | |||
| 403 | But note that this is a privilege that comes with some responsibilities. You | ||
| 404 | should test your changes before you commit them. You should also talk to an | ||
| 405 | applet maintainer before you make any kind of sweeping changes to somebody | ||
| 406 | else's code. Big changes should still go to the mailing list first. Remember, | ||
| 407 | being wise, polite, and discreet is more important than being clever. | ||
| 408 | |||
| 409 | |||
| 410 | When To Commit | ||
| 411 | ~~~~~~~~~~~~~~ | ||
| 412 | |||
| 413 | Generally, you should feel free to commit a change if: | ||
| 414 | |||
| 415 | - Your changes are small and don't touch many files | ||
| 416 | - You are fixing a bug | ||
| 417 | - Somebody has told you that it's okay | ||
| 418 | - It's obviously the Right Thing | ||
| 419 | |||
| 420 | The more of the above are true, the better it is to just commit a change | ||
| 421 | directly to CVS. | ||
| 422 | |||
| 423 | |||
| 424 | When Not To Commit | ||
| 425 | ~~~~~~~~~~~~~~~~~~ | ||
| 426 | |||
| 427 | Even if you have commit rights, you should probably still post a patch to the | ||
| 428 | mailing list if: | ||
| 429 | |||
| 430 | - Your changes are broad and touch many different files | ||
| 431 | - You are adding a feature | ||
| 432 | - Your changes are speculative or experimental (i.e., trying a new algorithm) | ||
| 433 | - You are not the maintainer and your changes make the maintainer cringe | ||
| 434 | |||
| 435 | The more of the above are true, the better it is to post a patch to the | ||
| 436 | mailing list instead of committing. | ||
| 437 | |||
| 438 | |||
| 439 | |||
| 440 | Final Words | ||
| 441 | ----------- | ||
| 442 | |||
| 443 | If all of this seems complicated, don't panic, it's really not that tough. If | ||
| 444 | you're having difficulty following some of the steps outlined in this | ||
| 445 | document don't worry, the folks on the Busybox mailing list are a fairly | ||
| 446 | good-natured bunch and will work with you to help get your patches into shape | ||
| 447 | or help you make contributions. | ||
| 448 | |||
| 449 | |||
diff --git a/docs/ipv4_ipv6.txt b/docs/ipv4_ipv6.txt new file mode 100644 index 000000000..92010b59c --- /dev/null +++ b/docs/ipv4_ipv6.txt | |||
| @@ -0,0 +1,223 @@ | |||
| 1 | We need better network address conv helpers. | ||
| 2 | This is what our applets want: | ||
| 3 | |||
| 4 | sockaddr -> hostname | ||
| 5 | udhcp: hostname -> ipv4 addr | ||
| 6 | nslookup: hostname -> list of names - done | ||
| 7 | tftp: host,port -> sockaddr | ||
| 8 | nc: host,port -> sockaddr | ||
| 9 | inetd: ? | ||
| 10 | traceroute: ?, hostname -> ipv4 addr | ||
| 11 | arping hostname -> ipv4 addr | ||
| 12 | ping6 hostname -> ipv6 addr | ||
| 13 | ifconfig hostname -> ipv4 addr (FIXME error check?) | ||
| 14 | ipcalc ipv4 addr -> hostname | ||
| 15 | syslogd hostname -> sockaddr | ||
| 16 | inet_common.c: buggy. hostname -> ipv4 addr | ||
| 17 | mount hostname -> sockaddr_in | ||
| 18 | |||
| 19 | ================== | ||
| 20 | HOWTO get rid of inet_ntoa/aton: | ||
| 21 | |||
| 22 | foo.sin_addr.s_addr = inet_addr(cp); | ||
| 23 | - | ||
| 24 | inet_pton(AF_INET, cp, &foo.sin_addr); | ||
| 25 | |||
| 26 | inet_aton(cp, &foo.sin_addr); | ||
| 27 | - | ||
| 28 | inet_pton(AF_INET, cp, &foo.sin_addr); | ||
| 29 | |||
| 30 | ptr = inet_ntoa(foo.sin_addr); | ||
| 31 | - | ||
| 32 | char str[INET_ADDRSTRLEN]; | ||
| 33 | ptr = inet_ntop(AF_INET, &foo.sin_addr, str, sizeof(str)); | ||
| 34 | |||
| 35 | =================== | ||
| 36 | |||
| 37 | struct addrinfo { | ||
| 38 | int ai_flags; | ||
| 39 | int ai_family; | ||
| 40 | int ai_socktype; | ||
| 41 | int ai_protocol; | ||
| 42 | size_t ai_addrlen; | ||
| 43 | struct sockaddr *ai_addr; | ||
| 44 | char *ai_canonname; | ||
| 45 | struct addrinfo *ai_next; | ||
| 46 | }; | ||
| 47 | int getaddrinfo(const char *node, const char *service, | ||
| 48 | const struct addrinfo *hints, | ||
| 49 | struct addrinfo **res); | ||
| 50 | |||
| 51 | void freeaddrinfo(struct addrinfo *res); | ||
| 52 | |||
| 53 | const char *gai_strerror(int errcode); | ||
| 54 | |||
| 55 | The members ai_family, ai_socktype, and ai_protocol have the same meaning | ||
| 56 | as the corresponding parameters in the socket(2) system call. The getad- | ||
| 57 | drinfo(3) function returns socket addresses in either IPv4 or IPv6 address | ||
| 58 | family, (ai_family will be set to either AF_INET or AF_INET6). | ||
| 59 | |||
| 60 | The hints parameter specifies the preferred socket type, or protocol. A | ||
| 61 | NULL hints specifies that any network address or protocol is acceptable. | ||
| 62 | If this parameter is not NULL it points to an addrinfo structure whose | ||
| 63 | ai_family, ai_socktype, and ai_protocol members specify the preferred | ||
| 64 | socket type. AF_UNSPEC in ai_family specifies any protocol family (either | ||
| 65 | IPv4 or IPv6, for example). 0 in ai_socktype or ai_protocol specifies | ||
| 66 | that any socket type or protocol is acceptable as well. The ai_flags mem- | ||
| 67 | ber specifies additional options, defined below. Multiple flags are spec- | ||
| 68 | ified by logically OR-ing them together. All the other members in the | ||
| 69 | hints parameter must contain either 0, or a null pointer. | ||
| 70 | |||
| 71 | The node or service parameter, but not both, may be NULL. node specifies | ||
| 72 | either a numerical network address (dotted-decimal format for IPv4, hex- | ||
| 73 | adecimal format for IPv6) or a network hostname, whose network addresses | ||
| 74 | are looked up and resolved. If hints.ai_flags contains the AI_NUMERICHOST | ||
| 75 | flag then the node parameter must be a numerical network address. The | ||
| 76 | AI_NUMERICHOST flag suppresses any potentially lengthy network host | ||
| 77 | address lookups. | ||
| 78 | |||
| 79 | The getaddrinfo(3) function creates a linked list of addrinfo structures, | ||
| 80 | one for each network address subject to any restrictions imposed by the | ||
| 81 | hints parameter. The ai_canonname field of the first of these addrinfo | ||
| 82 | structures is set to point to the official name of the host, if | ||
| 83 | hints.ai_flags includes the AI_CANONNAME flag. ai_family, ai_socktype, | ||
| 84 | and ai_protocol specify the socket creation parameters. A pointer to the | ||
| 85 | socket address is placed in the ai_addr member, and the length of the | ||
| 86 | socket address, in bytes, is placed in the ai_addrlen member. | ||
| 87 | |||
| 88 | If node is NULL, the network address in each socket structure is initial- | ||
| 89 | ized according to the AI_PASSIVE flag, which is set in hints.ai_flags. | ||
| 90 | The network address in each socket structure will be left unspecified if | ||
| 91 | AI_PASSIVE flag is set. This is used by server applications, which intend | ||
| 92 | to accept client connections on any network address. The network address | ||
| 93 | will be set to the loopback interface address if the AI_PASSIVE flag is | ||
| 94 | not set. This is used by client applications, which intend to connect to | ||
| 95 | a server running on the same network host. | ||
| 96 | |||
| 97 | If hints.ai_flags includes the AI_ADDRCONFIG flag, then IPv4 addresses are | ||
| 98 | returned in the list pointed to by result only if the local system has at | ||
| 99 | least has at least one IPv4 address configured, and IPv6 addresses are | ||
| 100 | only returned if the local system has at least one IPv6 address config- | ||
| 101 | ured. | ||
| 102 | |||
| 103 | If hint.ai_flags specifies the AI_V4MAPPED flag, and hints.ai_family was | ||
| 104 | specified as AF_INET6, and no matching IPv6 addresses could be found, then | ||
| 105 | return IPv4-mapped IPv6 addresses in the list pointed to by result. If | ||
| 106 | both AI_V4MAPPED and AI_ALL are specified in hints.ai_family, then return | ||
| 107 | both IPv6 and IPv4-mapped IPv6 addresses in the list pointed to by result. | ||
| 108 | AI_ALL is ignored if AI_V4MAPPED is not also specified. | ||
| 109 | |||
| 110 | service sets the port number in the network address of each socket struc- | ||
| 111 | ture. If service is NULL the port number will be left uninitialized. If | ||
| 112 | AI_NUMERICSERV is specified in hints.ai_flags and service is not NULL, | ||
| 113 | then service must point to a string containing a numeric port number. | ||
| 114 | This flag is used to inhibit the invocation of a name resolution service | ||
| 115 | in cases where it is known not to be required. | ||
| 116 | |||
| 117 | |||
| 118 | ============== | ||
| 119 | |||
| 120 | int getnameinfo(const struct sockaddr *sa, socklen_t salen, | ||
| 121 | char *host, size_t hostlen, | ||
| 122 | char *serv, size_t servlen, int flags); | ||
| 123 | |||
| 124 | The getnameinfo(3) function is defined for protocol-independent | ||
| 125 | address-to-nodename translation. It combines the functionality | ||
| 126 | of gethostbyaddr(3) and getservbyport(3) and is the inverse of | ||
| 127 | getaddrinfo(3). The sa argument is a pointer to a generic socket address | ||
| 128 | structure (of type sockaddr_in or sockaddr_in6) of size salen that | ||
| 129 | holds the input IP address and port number. The arguments host and | ||
| 130 | serv are pointers to buffers (of size hostlen and servlen respectively) | ||
| 131 | to hold the return values. | ||
| 132 | |||
| 133 | The caller can specify that no hostname (or no service name) is required | ||
| 134 | by providing a NULL host (or serv) argument or a zero hostlen (or servlen) | ||
| 135 | parameter. However, at least one of hostname or service name must be requested. | ||
| 136 | |||
| 137 | The flags argument modifies the behaviour of getnameinfo(3) as follows: | ||
| 138 | |||
| 139 | NI_NOFQDN | ||
| 140 | If set, return only the hostname part of the FQDN for local hosts. | ||
| 141 | |||
| 142 | NI_NUMERICHOST | ||
| 143 | If set, then the numeric form of the hostname is returned. | ||
| 144 | (When not set, this will still happen in case the node's name | ||
| 145 | cannot be looked up.) | ||
| 146 | |||
| 147 | NI_NAMEREQD | ||
| 148 | If set, then a error is returned if the hostname cannot be looked up. | ||
| 149 | |||
| 150 | NI_NUMERICSERV | ||
| 151 | If set, then the service address is returned in numeric form, | ||
| 152 | for example by its port number. | ||
| 153 | |||
| 154 | NI_DGRAM | ||
| 155 | If set, then the service is datagram (UDP) based rather than stream | ||
| 156 | (TCP) based. This is required for the few ports (512-514) that have different | ||
| 157 | services for UDP and TCP. | ||
| 158 | |||
| 159 | ================= | ||
| 160 | |||
| 161 | Modified IPv6-aware C code: | ||
| 162 | |||
| 163 | struct addrinfo *res, *aip; | ||
| 164 | struct addrinfo hints; | ||
| 165 | int sock = -1; | ||
| 166 | int error; | ||
| 167 | |||
| 168 | /* Get host address. Any type of address will do. */ | ||
| 169 | memset(&hints, 0, sizeof(hints)); | ||
| 170 | hints.ai_flags = AI_ALL|AI_ADDRCONFIG; | ||
| 171 | hints.ai_socktype = SOCK_STREAM; | ||
| 172 | |||
| 173 | error = getaddrinfo(hostname, servicename, &hints, &res); | ||
| 174 | if (error != 0) { | ||
| 175 | (void) fprintf(stderr, | ||
| 176 | "getaddrinfo: %s for host %s service %s\n", | ||
| 177 | gai_strerror(error), hostname, servicename); | ||
| 178 | return -1; | ||
| 179 | } | ||
| 180 | /* Try all returned addresses until one works */ | ||
| 181 | for (aip = res; aip != NULL; aip = aip->ai_next) { | ||
| 182 | /* | ||
| 183 | * Open socket. The address type depends on what | ||
| 184 | * getaddrinfo() gave us. | ||
| 185 | */ | ||
| 186 | sock = socket(aip->ai_family, aip->ai_socktype, aip->ai_protocol); | ||
| 187 | if (sock == -1) { | ||
| 188 | perror("socket"); | ||
| 189 | freeaddrinfo(res); | ||
| 190 | return -1; | ||
| 191 | } | ||
| 192 | |||
| 193 | /* Connect to the host. */ | ||
| 194 | if (connect(sock, aip->ai_addr, aip->ai_addrlen) == -1) { | ||
| 195 | perror("connect"); | ||
| 196 | (void) close(sock); | ||
| 197 | sock = -1; | ||
| 198 | continue; | ||
| 199 | } | ||
| 200 | break; | ||
| 201 | } | ||
| 202 | freeaddrinfo(res); | ||
| 203 | |||
| 204 | Note that for new applications, if you write address-family-agnostic data structures, | ||
| 205 | there is no need for porting. | ||
| 206 | |||
| 207 | However, when it comes to server-side programming in C/C++, there is an additional wrinkle. | ||
| 208 | Namely, depending on whether your application is written for a dual-stack platform, such | ||
| 209 | as Solaris or Linux, or a single-stack platform, such as Windows, you would need to | ||
| 210 | structure the code differently. | ||
| 211 | |||
| 212 | Here's the corresponding server C code for a dual-stack platform: | ||
| 213 | |||
| 214 | int ServSock, csock; | ||
| 215 | /* struct sockaddr is too small! */ | ||
| 216 | struct sockaddr_storage addr, from; | ||
| 217 | ... | ||
| 218 | ServSock = socket(AF_INET6, SOCK_STREAM, PF_INET6); | ||
| 219 | bind(ServSock, &addr, sizeof(addr)); | ||
| 220 | do { | ||
| 221 | csock = accept(ServSocket, &from, sizeof(from)); | ||
| 222 | doClientStuff(csock); | ||
| 223 | } while (!finished); | ||
diff --git a/docs/new-applet-HOWTO.txt b/docs/new-applet-HOWTO.txt new file mode 100644 index 000000000..1c2383f35 --- /dev/null +++ b/docs/new-applet-HOWTO.txt | |||
| @@ -0,0 +1,150 @@ | |||
| 1 | How to Add a New Applet to BusyBox | ||
| 2 | ================================== | ||
| 3 | |||
| 4 | This document details the steps you must take to add a new applet to BusyBox. | ||
| 5 | |||
| 6 | Credits: | ||
| 7 | Matt Kraai - initial writeup | ||
| 8 | Mark Whitley - the remix | ||
| 9 | Thomas Lundquist - Added stuff for the new directory layout. | ||
| 10 | |||
| 11 | Initial Write | ||
| 12 | ------------- | ||
| 13 | |||
| 14 | First, write your applet. Be sure to include copyright information at the top, | ||
| 15 | such as who you stole the code from and so forth. Also include the mini-GPL | ||
| 16 | boilerplate. Be sure to name the main function <applet>_main instead of main. | ||
| 17 | And be sure to put it in <applet>.c. Usage does not have to be taken care of by | ||
| 18 | your applet. | ||
| 19 | Make sure to #include "busybox.h" as the first include file in your applet so | ||
| 20 | the bb_config.h and appropriate platform specific files are included properly. | ||
| 21 | |||
| 22 | For a new applet mu, here is the code that would go in mu.c: | ||
| 23 | |||
| 24 | ----begin example code------ | ||
| 25 | |||
| 26 | /* vi: set sw=4 ts=4: */ | ||
| 27 | /* | ||
| 28 | * Mini mu implementation for busybox | ||
| 29 | * | ||
| 30 | * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL> | ||
| 31 | * | ||
| 32 | * Licensed under GPLv2 or later, see file LICENSE in this tarball for details. | ||
| 33 | */ | ||
| 34 | |||
| 35 | #include "busybox.h" | ||
| 36 | #include <other.h> | ||
| 37 | |||
| 38 | int mu_main(int argc, char **argv) | ||
| 39 | { | ||
| 40 | int fd; | ||
| 41 | char mu; | ||
| 42 | |||
| 43 | fd = xopen("/dev/random", O_RDONLY); | ||
| 44 | |||
| 45 | if ((n = safe_read(fd, &mu, 1)) < 1) | ||
| 46 | bb_perror_msg_and_die("/dev/random"); | ||
| 47 | |||
| 48 | return mu; | ||
| 49 | } | ||
| 50 | |||
| 51 | ----end example code------ | ||
| 52 | |||
| 53 | |||
| 54 | Coding Style | ||
| 55 | ------------ | ||
| 56 | |||
| 57 | Before you submit your applet for inclusion in BusyBox, (or better yet, before | ||
| 58 | you _write_ your applet) please read through the style guide in the docs | ||
| 59 | directory and make your program compliant. | ||
| 60 | |||
| 61 | |||
| 62 | Some Words on libbb | ||
| 63 | ------------------- | ||
| 64 | |||
| 65 | As you are writing your applet, please be aware of the body of pre-existing | ||
| 66 | useful functions in libbb. Use these instead of reinventing the wheel. | ||
| 67 | |||
| 68 | Additionally, if you have any useful, general-purpose functions in your | ||
| 69 | applet that could be useful in other applets, consider putting them in libbb. | ||
| 70 | |||
| 71 | |||
| 72 | Placement / Directory | ||
| 73 | --------------------- | ||
| 74 | |||
| 75 | Find the appropriate directory for your new applet. | ||
| 76 | |||
| 77 | Make sure you find the appropriate places in the files, the applets are | ||
| 78 | sorted alphabetically. | ||
| 79 | |||
| 80 | Add the applet to Makefile.in in the chosen directory: | ||
| 81 | |||
| 82 | obj-$(CONFIG_MU) += mu.o | ||
| 83 | |||
| 84 | Add the applet to Config.in in the chosen directory: | ||
| 85 | |||
| 86 | config CONFIG_MU | ||
| 87 | bool "MU" | ||
| 88 | default n | ||
| 89 | help | ||
| 90 | Returns an indeterminate value. | ||
| 91 | |||
| 92 | |||
| 93 | Usage String(s) | ||
| 94 | --------------- | ||
| 95 | |||
| 96 | Next, add usage information for you applet to include/usage.h. | ||
| 97 | This should look like the following: | ||
| 98 | |||
| 99 | #define mu_trivial_usage \ | ||
| 100 | "-[abcde] FILES" | ||
| 101 | #define mu_full_usage \ | ||
| 102 | "Returns an indeterminate value.\n\n" \ | ||
| 103 | "Options:\n" \ | ||
| 104 | "\t-a\t\tfirst function\n" \ | ||
| 105 | "\t-b\t\tsecond function\n" \ | ||
| 106 | ... | ||
| 107 | |||
| 108 | If your program supports flags, the flags should be mentioned on the first | ||
| 109 | line (-[abcde]) and a detailed description of each flag should go in the | ||
| 110 | mu_full_usage section, one flag per line. (Numerous examples of this | ||
| 111 | currently exist in usage.h.) | ||
| 112 | |||
| 113 | |||
| 114 | Header Files | ||
| 115 | ------------ | ||
| 116 | |||
| 117 | Next, add an entry to include/applets.h. Be *sure* to keep the list | ||
| 118 | in alphabetical order, or else it will break the binary-search lookup | ||
| 119 | algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily: | ||
| 120 | |||
| 121 | /* all programs above here are alphabetically "less than" 'mu' */ | ||
| 122 | #ifdef CONFIG_MU | ||
| 123 | APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage) | ||
| 124 | #endif | ||
| 125 | /* all programs below here are alphabetically "greater than" 'mu' */ | ||
| 126 | |||
| 127 | |||
| 128 | Documentation | ||
| 129 | ------------- | ||
| 130 | |||
| 131 | If you're feeling especially nice, you should also document your applet in the | ||
| 132 | docs directory (but nobody ever does that). | ||
| 133 | |||
| 134 | Adding some text to docs/Configure.help is a nice start. | ||
| 135 | |||
| 136 | |||
| 137 | The Grand Announcement | ||
| 138 | ---------------------- | ||
| 139 | |||
| 140 | Then create a diff -urN of the files you added and/or modified. Typically: | ||
| 141 | <appletdir>/<applet>.c | ||
| 142 | include/usage.c | ||
| 143 | include/applets.h | ||
| 144 | <appletdir>/Makefile.in | ||
| 145 | <appletdir>/config.in | ||
| 146 | and send it to the mailing list: | ||
| 147 | busybox@busybox.net | ||
| 148 | http://busybox.net/mailman/listinfo/busybox | ||
| 149 | |||
| 150 | Sending patches as attachments is preferred, but not required. | ||
diff --git a/docs/sigint.htm b/docs/sigint.htm new file mode 100644 index 000000000..6fe76bbef --- /dev/null +++ b/docs/sigint.htm | |||
| @@ -0,0 +1,627 @@ | |||
| 1 | <HTML> | ||
| 2 | <HEAD> | ||
| 3 | <link rel="SHORTCUT ICON" href="http://www.cons.org/favicon.ico"> | ||
| 4 | <TITLE>Proper handling of SIGINT/SIGQUIT [http://www.cons.org/cracauer/sigint.html]</TITLE> | ||
| 5 | <!-- Created by: GNU m4 using $Revision: 1.20 $ of crawww.m4lib on 11-Feb-2005 --> | ||
| 6 | <BODY BGCOLOR="#fff8e1"> | ||
| 7 | <CENTER><H2>Proper handling of SIGINT/SIGQUIT</H2></CENTER> | ||
| 8 | <img src=linie.png width="100%" alt=" "> | ||
| 9 | <P> | ||
| 10 | |||
| 11 | <table border=1 cellpadding=4> | ||
| 12 | <tr><th valign=top align=left>Abstract: </th> | ||
| 13 | <td valign=top align=left> | ||
| 14 | In UNIX terminal sessions, you usually have a key like | ||
| 15 | <code>C-c</code> (Control-C) to immediately end whatever program you | ||
| 16 | have running in the foreground. This should work even when the program | ||
| 17 | you called has called other programs in turn. Everything should be | ||
| 18 | aborted, giving you your command prompt back, no matter how deep the | ||
| 19 | call stack is. | ||
| 20 | |||
| 21 | <p>Basically, it's trivial. But the existence of interactive | ||
| 22 | applications that use SIGINT and/or SIGQUIT for other purposes than a | ||
| 23 | complete immediate abort make matters complicated, and - as was to | ||
| 24 | expect - left us with several ways to solve the problems. Of course, | ||
| 25 | existing shells and applications follow different ways. | ||
| 26 | |||
| 27 | <P>This Web pages outlines different ways to solve the problem and | ||
| 28 | argues that only one of them can do everything right, although it | ||
| 29 | means that we have to fix some existing software. | ||
| 30 | |||
| 31 | |||
| 32 | |||
| 33 | </td></tr><tr><th valign=top align=left>Intended audience: </th> | ||
| 34 | <td valign=top align=left>Programmers who implement programs that catch SIGINT/SIGQUIT. | ||
| 35 | <BR>Programmers who implements shells or shell-like programs that | ||
| 36 | execute batches of programs. | ||
| 37 | |||
| 38 | <p>Users who have problems problems getting rid of runaway shell | ||
| 39 | scripts using <code>Control-C</code>. Or have interactive applications | ||
| 40 | that don't behave right when sending SIGINT. Examples are emacs'es | ||
| 41 | that die on Control-g or shellscript statements that sometimes are | ||
| 42 | executed and sometimes not, apparently not determined by the user's | ||
| 43 | intention. | ||
| 44 | |||
| 45 | |||
| 46 | </td></tr><tr><th valign=top align=left>Required knowledge: </th> | ||
| 47 | <td valign=top align=left>You have to know what it means to catch SIGINT or SIGQUIT and how | ||
| 48 | processes are waiting for other processes (childs) they spawned. | ||
| 49 | |||
| 50 | |||
| 51 | </td></tr></table> | ||
| 52 | <img src=linie.png width="100%" alt=" "> | ||
| 53 | |||
| 54 | |||
| 55 | <H3>Basic concepts</H3> | ||
| 56 | |||
| 57 | What technically happens when you press Control-C is that all programs | ||
| 58 | running in the foreground in your current terminal (or virtual | ||
| 59 | terminal) get the signal SIGINT sent. | ||
| 60 | |||
| 61 | <p>You may change the key that triggers the signal using | ||
| 62 | <code>stty</code> and running programs may remap the SIGINT-sending | ||
| 63 | key at any time they like, without your intervention and without | ||
| 64 | asking you first. | ||
| 65 | |||
| 66 | <p>The usual reaction of a running program to SIGINT is to exit. | ||
| 67 | However, not all program do an exit on SIGINT, programs are free to | ||
| 68 | use the signal for other actions or to ignore it at all. | ||
| 69 | |||
| 70 | <p>All programs running in the foreground receive the signal. This may | ||
| 71 | be a nested "stack" of programs: You started a program that started | ||
| 72 | another and the outer is waiting for the inner to exit. This nesting | ||
| 73 | may be arbitrarily deep. | ||
| 74 | |||
| 75 | <p>The innermost program is the one that decides what to do on SIGINT. | ||
| 76 | It may exit, do something else or do nothing. Still, when the user hit | ||
| 77 | SIGINT, all the outer programs are awaken, get the signal and may | ||
| 78 | react on it. | ||
| 79 | |||
| 80 | <H3>What we try to achieve</H3> | ||
| 81 | |||
| 82 | The problem is with shell scripts (or similar programs that call | ||
| 83 | several subprograms one after another). | ||
| 84 | |||
| 85 | <p>Let us consider the most basic script: | ||
| 86 | <PRE> | ||
| 87 | #! /bin/sh | ||
| 88 | program1 | ||
| 89 | program2 | ||
| 90 | </PRE> | ||
| 91 | and the usual run looks like this: | ||
| 92 | <PRE> | ||
| 93 | $ sh myscript | ||
| 94 | [output of program1] | ||
| 95 | [output of program2] | ||
| 96 | $ | ||
| 97 | </PRE> | ||
| 98 | |||
| 99 | <p>Let us assume that both programs do nothing special on SIGINT, they | ||
| 100 | just exit. | ||
| 101 | |||
| 102 | <p>Now imagine the user hits C-c while a shellscript is executing its | ||
| 103 | first program. The following programs receive SIGINT: program1 and | ||
| 104 | also the shell executing the script. program1 exits. | ||
| 105 | |||
| 106 | <p>But what should the shell do? If we say that it is only the | ||
| 107 | innermost's programs business to react on SIGINT, the shell will do | ||
| 108 | nothing special (not exit) and it will continue the execution of the | ||
| 109 | script and run program2. But this is wrong: The user's intention in | ||
| 110 | hitting C-c is to abort the whole script, to get his prompt back. If | ||
| 111 | he hits C-c while the first program is running, he does not want | ||
| 112 | program2 to be even started. | ||
| 113 | |||
| 114 | <p>here is what would happen if the shell doesn't do anything: | ||
| 115 | <PRE> | ||
| 116 | $ sh myscript | ||
| 117 | [first half of program1's output] | ||
| 118 | C-c [users presses C-c] | ||
| 119 | [second half of program1's output will not be displayed] | ||
| 120 | [output of program2 will appear] | ||
| 121 | </PRE> | ||
| 122 | |||
| 123 | |||
| 124 | <p>Consider a more annoying example: | ||
| 125 | <pre> | ||
| 126 | #! /bin/sh | ||
| 127 | # let's assume there are 300 *.dat files | ||
| 128 | for file in *.dat ; do | ||
| 129 | dat2ascii $dat | ||
| 130 | done | ||
| 131 | </pre> | ||
| 132 | |||
| 133 | If your shell wouldn't end if the user hits <code>C-c</code>, | ||
| 134 | <code>C-c</code> would just end <strong>one</strong> dat2ascii run and | ||
| 135 | the script would continue. Thus, you had to hit <code>C-c</code> up to | ||
| 136 | 300 times to end this script. | ||
| 137 | |||
| 138 | <H3>Alternatives to do so</H3> | ||
| 139 | |||
| 140 | <p>There are several ways to handle abortion of shell scripts when | ||
| 141 | SIGINT is received while a foreground child runs: | ||
| 142 | |||
| 143 | <menu> | ||
| 144 | |||
| 145 | <li>As just outlined, the shellscript may just continue, ignoring the | ||
| 146 | fact that the user hit <code>C-c</code>. That way, your shellscript - | ||
| 147 | including any loops - would continue and you had no chance of aborting | ||
| 148 | it except using the kill command after finding out the outermost | ||
| 149 | shell's PID. This "solution" will not be discussed further, as it is | ||
| 150 | obviously not desirable. | ||
| 151 | |||
| 152 | <p><li>The shell itself exits immediately when it receives SIGINT. Not | ||
| 153 | only the program called will exit, but the calling (the | ||
| 154 | script-executing) shell. The first variant is to exit the shell (and | ||
| 155 | therefore discontinuing execution of the script) immediately, while | ||
| 156 | the background program may still be executing (remember that although | ||
| 157 | the shell is just waiting for the called program to exit, it is woken | ||
| 158 | up and may act). I will call the way of doing things the "IUE" (for | ||
| 159 | "immediate unconditional exit") for the rest of this document. | ||
| 160 | |||
| 161 | <p><li>As a variant of the former, when the shell receives SIGINT | ||
| 162 | while it is waiting for a child to exit, the shell does not exit | ||
| 163 | immediately. but it remembers the fact that a SIGINT happened. After | ||
| 164 | the called program exits and the shell's wait ends, the shell will | ||
| 165 | exit itself and hence discontinue the script. I will call the way of | ||
| 166 | doing things the "WUE" (for "wait and unconditional exit") for the | ||
| 167 | rest of this document. | ||
| 168 | |||
| 169 | <p><li>There is also a way that the calling shell can tell whether the | ||
| 170 | called program exited on SIGINT and if it ignored SIGINT (or used it | ||
| 171 | for other purposes). As in the <sl>WUE</sl> way, the shell waits for | ||
| 172 | the child to complete. It figures whether the program was ended on | ||
| 173 | SIGINT and if so, it discontinue the script. If the program did any | ||
| 174 | other exit, the script will be continued. I will call the way of doing | ||
| 175 | things the "WCE" (for "wait and cooperative exit") for the rest of | ||
| 176 | this document. | ||
| 177 | |||
| 178 | </menu> | ||
| 179 | |||
| 180 | <H3>The problem</H3> | ||
| 181 | |||
| 182 | On first sight, all three solutions (IUE, WUE and WCE) all seem to do | ||
| 183 | what we want: If C-c is hit while the first program of the shell | ||
| 184 | script runs, the script is discontinued. The user gets his prompt back | ||
| 185 | immediately. So what are the difference between these way of handling | ||
| 186 | SIGINT? | ||
| 187 | |||
| 188 | <p>There are programs that use the signal SIGINT for other purposes | ||
| 189 | than exiting. They use it as a normal keystroke. The user is expected | ||
| 190 | to use the key that sends SIGINT during a perfectly normal program | ||
| 191 | run. As a result, the user sends SIGINT in situations where he/she | ||
| 192 | does not want the program or the script to end. | ||
| 193 | |||
| 194 | <p>The primary example is the emacs editor: C-g does what ESC does in | ||
| 195 | other applications: It cancels a partially executed or prepared | ||
| 196 | operation. Technically, emacs remaps the key that sends SIGINT from | ||
| 197 | C-c to C-g and catches SIGINT. | ||
| 198 | |||
| 199 | <p>Remember that the SIGINT is sent to all programs running in the | ||
| 200 | foreground. If emacs is executing from a shell script, both emacs and | ||
| 201 | the shell get SIGINT. emacs is the program that decides what to do: | ||
| 202 | Exit on SIGINT or not. emacs decides not to exit. The problem arises | ||
| 203 | when the shell draws its own conclusions from receiving SIGINT without | ||
| 204 | consulting emacs for its opinion. | ||
| 205 | |||
| 206 | <p>Consider this script: | ||
| 207 | <PRE> | ||
| 208 | #! /bin/sh | ||
| 209 | emacs /tmp/foo | ||
| 210 | cp /tmp/foo /home/user/mail/sent | ||
| 211 | </PRE> | ||
| 212 | |||
| 213 | <p>If C-g is used in emacs, both the shell and emacs will received | ||
| 214 | SIGINT. Emacs will not exit, the user used C-g as a normal editing | ||
| 215 | keystroke, he/she does not want the script to be aborted on C-g. | ||
| 216 | |||
| 217 | <p>The central problem is that the second command (cp) may | ||
| 218 | unintentionally be killed when the shell draws its own conclusion | ||
| 219 | about the user's intention. The innermost program is the only one to | ||
| 220 | judge. | ||
| 221 | |||
| 222 | <H3>One more example</H3> | ||
| 223 | |||
| 224 | <p>Imagine a mail session using a curses mailer in a tty. You called | ||
| 225 | your mailer and started to compose a message. Your mailer calls emacs. | ||
| 226 | <code>C-g</code> is a normal editing key in emacs. Technically it | ||
| 227 | sends SIGINT (it was <code>C-c</code>, but emacs remapped the key) to | ||
| 228 | <menu> | ||
| 229 | <li>emacs | ||
| 230 | <li>the shell between your mailer and emacs, the one from your mailers | ||
| 231 | system("emacs /tmp/bla.44") command | ||
| 232 | <li>the mailer itself | ||
| 233 | <li>possibly another shell if your mailer was called by a shell script | ||
| 234 | or from another application using system(3) | ||
| 235 | <li>your interactive shell (which ignores it since it is interactive | ||
| 236 | and hence is not relevant to this discussion) | ||
| 237 | </menu> | ||
| 238 | |||
| 239 | <p>If everyone just exits on SIGINT, you will be left with nothing but | ||
| 240 | your login shell, without asking. | ||
| 241 | |||
| 242 | <p>But for sure you don't want to be dropped out of your editor and | ||
| 243 | out of your mailer back to the commandline, having your edited data | ||
| 244 | and mailer status deleted. | ||
| 245 | |||
| 246 | <p>Understand the difference: While <code>C-g</code> is used an a kind | ||
| 247 | of abort key in emacs, it isn't the major "abort everything" key. When | ||
| 248 | you use <code>C-g</code> in emacs, you want to end some internal emacs | ||
| 249 | command. You don't want your whole emacs and mailer session to end. | ||
| 250 | |||
| 251 | <p>So, if the shell exits immediately if the user sends SIGINT (the | ||
| 252 | second of the four ways shown above), the parent of emacs would die, | ||
| 253 | leaving emacs without the controlling tty. The user will lose it's | ||
| 254 | editing session immediately and unrecoverable. If the "main" shell of | ||
| 255 | the operating system defaults to this behavior, every editor session | ||
| 256 | that is spawned from a mailer or such will break (because it is | ||
| 257 | usually executed by system(3), which calls /bin/sh). This was the case | ||
| 258 | in FreeBSD before I and Bruce Evans changed it in 1998. | ||
| 259 | |||
| 260 | <p>If the shell recognized that SIGINT was sent and exits after the | ||
| 261 | current foreground process exited (the third way of the four), the | ||
| 262 | editor session will not be disturbed, but things will still not work | ||
| 263 | right. | ||
| 264 | |||
| 265 | <H3>A further look at the alternatives</H3> | ||
| 266 | |||
| 267 | <p>Still considering this script to examine the shell's actions in the | ||
| 268 | IUE, WUE and ICE way of handling SIGINT: | ||
| 269 | <PRE> | ||
| 270 | #! /bin/sh | ||
| 271 | emacs /tmp/foo | ||
| 272 | cp /tmp/foo /home/user/mail/sent | ||
| 273 | </PRE> | ||
| 274 | |||
| 275 | <p>The IUE ("immediate unconditional exit") way does not work at all: | ||
| 276 | emacs wants to survive the SIGINT (it's a normal editing key for | ||
| 277 | emacs), but its parent shell unconditionally thinks "We received | ||
| 278 | SIGINT. Abort everything. Now.". The shell will exit even before emacs | ||
| 279 | exits. But this will leave emacs in an unusable state, since the death | ||
| 280 | of its calling shell will leave it without required resources (file | ||
| 281 | descriptors). This way does not work at all for shellscripts that call | ||
| 282 | programs that use SIGINT for other purposes than immediate exit. Even | ||
| 283 | for programs that exit on SIGINT, but want to do some cleanup between | ||
| 284 | the signal and the exit, may fail before they complete their cleanup. | ||
| 285 | |||
| 286 | <p>It should be noted that this way has one advantage: If a child | ||
| 287 | blocks SIGINT and does not exit at all, this way will get control back | ||
| 288 | to the user's terminal. Since such programs should be banned from your | ||
| 289 | system anyway, I don't think that weighs against the disadvantages. | ||
| 290 | |||
| 291 | <p>WUE ("wait and unconditional exit") is a little more clever: If C-g | ||
| 292 | was used in emacs, the shell will get SIGINT. It will not immediately | ||
| 293 | exit, but remember the fact that a SIGINT happened. When emacs ends | ||
| 294 | (maybe a long time after the SIGINT), it will say "Ok, a SIGINT | ||
| 295 | happened sometime while the child was executing, the user wants the | ||
| 296 | script to be discontinued". It will then exit. The cp will not be | ||
| 297 | executed. But that's bad. The "cp" will be executed when the emacs | ||
| 298 | session ended without the C-g key ever used, but it will not be | ||
| 299 | executed when the user used C-g at least one time. That is clearly not | ||
| 300 | desired. Since C-g is a normal editing key in emacs, the user expects | ||
| 301 | the rest of the script to behave identically no matter what keys he | ||
| 302 | used. | ||
| 303 | |||
| 304 | <p>As a result, the "WUE" way is better than the "IUE" way in that it | ||
| 305 | does not break SIGINT-using programs completely. The emacs session | ||
| 306 | will end undisturbed. But it still does not support scripts where | ||
| 307 | other actions should be performed after a program that use SIGINT for | ||
| 308 | non-exit purposes. Since the behavior is basically undeterminable for | ||
| 309 | the user, this can lead to nasty surprises. | ||
| 310 | |||
| 311 | <p>The "WCE" way fixes this by "asking" the called program whether it | ||
| 312 | exited on SIGINT or not. While emacs receives SIGINT, it does not exit | ||
| 313 | on it and a calling shell waiting for its exit will not be told that | ||
| 314 | it exited on SIGINT. (Although it receives SIGINT at some point in | ||
| 315 | time, the system does not enforce that emacs will exit with | ||
| 316 | "I-exited-on-SIGINT" status. This is under emacs' control, see below). | ||
| 317 | |||
| 318 | <p>this still work for the normal script without SIGINT-using | ||
| 319 | programs:</p> | ||
| 320 | <PRE> | ||
| 321 | #! /bin/sh | ||
| 322 | program1 | ||
| 323 | program2 | ||
| 324 | </PRE> | ||
| 325 | |||
| 326 | Unless program1 and program2 mess around with signal handling, the | ||
| 327 | system will tell the calling shell whether the programs exited | ||
| 328 | normally or as a result of SIGINT. | ||
| 329 | |||
| 330 | <p>The "WCE" way then has an easy way to things right: When one called | ||
| 331 | program exited with "I-exited-on-SIGINT" status, it will discontinue | ||
| 332 | the script after this program. If the program ends without this | ||
| 333 | status, the next command in the script is started. | ||
| 334 | |||
| 335 | <p>It is important to understand that a shell in "WCE" modus does not | ||
| 336 | need to listen to the SIGINT signal at all. Both in the | ||
| 337 | "emacs-then-cp" script and in the "several-normal-programs" script, it | ||
| 338 | will be woken up and receive SIGINT when the user hits the | ||
| 339 | corresponding key. But the shell does not need to react on this event | ||
| 340 | and it doesn't need to remember the event of any SIGINT, either. | ||
| 341 | Telling whether the user wants to end a script is done by asking that | ||
| 342 | program that has to decide, that program that interprets keystrokes | ||
| 343 | from the user, the innermost program. | ||
| 344 | |||
| 345 | <H3>So everything is well with WCE?</H3> | ||
| 346 | |||
| 347 | Well, almost. | ||
| 348 | |||
| 349 | <p>The problem with the "WCE" modus is that there are broken programs | ||
| 350 | that do not properly communicate the required information up to the | ||
| 351 | calling program. | ||
| 352 | |||
| 353 | <p>Unless a program messes with signal handling, the system does this | ||
| 354 | automatically. | ||
| 355 | |||
| 356 | <p>There are programs that want to exit on SIGINT, but they don't let | ||
| 357 | the system do the automatic exit, because they want to do some | ||
| 358 | cleanup. To do so, they catch SIGINT, do the cleanup and then exit by | ||
| 359 | themselves. | ||
| 360 | |||
| 361 | <p>And here is where the problem arises: Once they catch the signal, | ||
| 362 | the system will no longer communicate the "I-exited-on-SIGINT" status | ||
| 363 | to the calling program automatically. Even if the program exit | ||
| 364 | immediately in the signal handler of SIGINT. Once it catches the | ||
| 365 | signal, it has to take care of communicating the signal status | ||
| 366 | itself. | ||
| 367 | |||
| 368 | <p>Some programs don't do this. On SIGINT, they do cleanup and exit | ||
| 369 | immediatly, but the calling shell isn't told about the non-normal exit | ||
| 370 | and it will call the next program in the script. | ||
| 371 | |||
| 372 | <p>As a result, the user hits SIGINT and while one program exits, the | ||
| 373 | shellscript continues. To him/her it looks like the shell fails to | ||
| 374 | obey to his abortion command. | ||
| 375 | |||
| 376 | <p>Both IUE or WUE shell would not have this problem, since they | ||
| 377 | discontinue the script on their own. But as I said, they don't support | ||
| 378 | programs using SIGINT for non-exiting purposes, no matter whether | ||
| 379 | these programs properly communicate their signal status to the calling | ||
| 380 | shell or not. | ||
| 381 | |||
| 382 | <p>Since some shell in wide use implement the WUE way (and some even | ||
| 383 | IUE), there is a considerable number of broken programs out there that | ||
| 384 | break WCE shells. The programmers just don't recognize it if their | ||
| 385 | shell isn't WCE. | ||
| 386 | |||
| 387 | <H3>How to be a proper program</H3> | ||
| 388 | |||
| 389 | <p>(Short note in advance: What you need to achieve is that | ||
| 390 | WIFSIGNALED(status) is true in the calling program and that | ||
| 391 | WTERMSIG(status) returns SIGINT.) | ||
| 392 | |||
| 393 | <p>If you don't catch SIGINT, the system automatically does the right | ||
| 394 | thing for you: Your program exits and the calling program gets the | ||
| 395 | right "I-exited-on-SIGINT" status after waiting for your exit. | ||
| 396 | |||
| 397 | <p>But once you catch SIGINT, you have to act. | ||
| 398 | |||
| 399 | <p>Decide whether the SIGINT is used for exit/abort purposes and hence | ||
| 400 | a shellscript calling this program should discontinue. This is | ||
| 401 | hopefully obvious. If you just need to do some cleanup on SIGINT, but | ||
| 402 | then exit immediately, the answer is "yes". | ||
| 403 | |||
| 404 | <p>If so, you have to tell the calling program about it by exiting | ||
| 405 | with the "I-exited-on-SIGINT" status. | ||
| 406 | |||
| 407 | <p>There is no other way of doing this than to kill yourself with a | ||
| 408 | SIGINT signal. Do it by resetting the SIGINT handler to SIG_DFL, then | ||
| 409 | send yourself the signal. | ||
| 410 | |||
| 411 | <PRE> | ||
| 412 | void sigint_handler(int sig) | ||
| 413 | { | ||
| 414 | <do some cleanup> | ||
| 415 | signal(SIGINT, SIG_DFL); | ||
| 416 | kill(getpid(), SIGINT); | ||
| 417 | } | ||
| 418 | </PRE> | ||
| 419 | |||
| 420 | Notes: | ||
| 421 | |||
| 422 | <MENU> | ||
| 423 | |||
| 424 | <LI>You cannot "fake" the proper exit status by an exit(3) with a | ||
| 425 | special numeric value. People often assume this since the manuals for | ||
| 426 | shells often list some return value for exactly this. But this is just | ||
| 427 | a convention for your shell script. It does not work from one UNIX API | ||
| 428 | program to another. | ||
| 429 | |||
| 430 | <P>All that happens is that the shell sets the "$?" variable to a | ||
| 431 | special numeric value for the convenience of your script, because your | ||
| 432 | script does not have access to the lower-lever UNIX status evaluation | ||
| 433 | functions. This is just an agreement between your script and the | ||
| 434 | executing shell, it does not have any meaning in other contexts. | ||
| 435 | |||
| 436 | <P><LI>Do not use kill(0, SIGINT) without consulting the manul for | ||
| 437 | your OS implementation. I.e. on BSD, this would not send the signal to | ||
| 438 | the current process, but to all processes in the group. | ||
| 439 | |||
| 440 | <P><LI>POSIX 1003.1 allows all these calls to appear in signal | ||
| 441 | handlers, so it is portable. | ||
| 442 | |||
| 443 | </MENU> | ||
| 444 | |||
| 445 | <p>In a bourne shell script, you can catch signals using the | ||
| 446 | <code>trap</code> command. Here, the same as for C programs apply. If | ||
| 447 | the intention of SIGINT is to end your program, you have to exit in a | ||
| 448 | way that the calling programs "sees" that you have been killed. If | ||
| 449 | you don't catch SIGINT, this happend automatically, but of you catch | ||
| 450 | SIGINT, i.e. to do cleanup work, you have to end the program by | ||
| 451 | killing yourself, not by calling exit. | ||
| 452 | |||
| 453 | <p>Consider this example from FreeBSD's <code>mkdep</code>, which is a | ||
| 454 | bourne shell script. | ||
| 455 | |||
| 456 | <pre> | ||
| 457 | TMP=_mkdep$$ | ||
| 458 | trap 'rm -f $TMP ; trap 2 ; kill -2 $$' 1 2 3 13 15 | ||
| 459 | </pre> | ||
| 460 | |||
| 461 | Yes, you have to do it the hard way. It's even more annoying in shell | ||
| 462 | scripts than in C programs since you can't "pre-delete" temporary | ||
| 463 | files (which isn't really portable in C, though). | ||
| 464 | |||
| 465 | <P>All this applies to programs in all languages, not only C and | ||
| 466 | bourne shell. Every language implementation that lets you catch SIGINT | ||
| 467 | should also give you the option to reset the signal and kill yourself. | ||
| 468 | |||
| 469 | <P>It is always desireable to exit the right way, even if you don't | ||
| 470 | expect your usual callers to depend on it, some unusual one will come | ||
| 471 | along. This proper exit status will be needed for WCE and will not | ||
| 472 | hurt when the calling shell uses IUE or WUE. | ||
| 473 | |||
| 474 | <H3>How to be a proper shell</H3> | ||
| 475 | |||
| 476 | All this applies only for the script-executing case. Most shells will | ||
| 477 | also have interactive modes where things are different. | ||
| 478 | |||
| 479 | <MENU> | ||
| 480 | |||
| 481 | <LI>Do nothing special when SIGINT appears while you wait for a child. | ||
| 482 | You don't even have to remember that one happened. | ||
| 483 | |||
| 484 | <P><LI>Wait for child to exit, get the exit status. Do not truncate it | ||
| 485 | to type char. | ||
| 486 | |||
| 487 | <P><LI>Look at WIFSIGNALED(status) and WTERMSIG(status) to tell | ||
| 488 | whether the child says "I exited on SIGINT: in my opinion the user | ||
| 489 | wants the shellscript to be discontinued". | ||
| 490 | |||
| 491 | <P><LI>If the latter applies, discontinue the script. | ||
| 492 | |||
| 493 | <P><LI>Exit. But since a shellscript may in turn be called by a | ||
| 494 | shellscript, you need to make sure that you properly communicate the | ||
| 495 | discontinue intention to the calling program. As in any other program | ||
| 496 | (see above), do | ||
| 497 | |||
| 498 | <PRE> | ||
| 499 | signal(SIGINT, SIG_DFL); | ||
| 500 | kill(getpid(), SIGINT); | ||
| 501 | </PRE> | ||
| 502 | |||
| 503 | </MENU> | ||
| 504 | |||
| 505 | <H3>Other remarks</H3> | ||
| 506 | |||
| 507 | Although this web page talks about SIGINT only, almost the same issues | ||
| 508 | apply to SIGQUIT, including proper exiting by killing yourself after | ||
| 509 | catching the signal and proper reaction on the WIFSIGNALED(status) | ||
| 510 | value. One notable difference for SIGQUIT is that you have to make | ||
| 511 | sure that not the whole call tree dumps core. | ||
| 512 | |||
| 513 | <H3>What to fight</H3> | ||
| 514 | |||
| 515 | Make sure all programs <em>really</em> kill themselves if they react | ||
| 516 | to SIGINT or SIGQUIT and intend to abort their operation as a result | ||
| 517 | of this signal. Programs that don't use SIGINT/SIGQUIT as a | ||
| 518 | termination trigger - but as part of normal operation - don't kill | ||
| 519 | themselves, but do a normal exit instead. | ||
| 520 | |||
| 521 | <p>Make sure people understand why you can't fake an exit-on-signal by | ||
| 522 | doing exit(...) using any numerical status. | ||
| 523 | |||
| 524 | <p>Make sure you use a shell that behaves right. Especially if you | ||
| 525 | develop programs, since it will help seeing problems. | ||
| 526 | |||
| 527 | <H3>Concrete examples how to fix programs:</H3> | ||
| 528 | <ul> | ||
| 529 | |||
| 530 | <li>The fix for FreeBSD's | ||
| 531 | <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/src/usr.bin/time/time.c.diff?r1=1.10&r2=1.11">time(1)</A>. This fix is the best example, it's quite short and clear and | ||
| 532 | it fixes a case where someone tried to fake signal exit status by a | ||
| 533 | numerical value. And the complete program is small. | ||
| 534 | |||
| 535 | <p><li>Fix for FreeBSD's | ||
| 536 | <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/src/usr.bin/truss/main.c.diff?r1=1.9&r2=1.10">truss(1)</A>. | ||
| 537 | |||
| 538 | <p><li>The fix for FreeBSD's | ||
| 539 | <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/src/usr.bin/mkdep/mkdep.gcc.sh.diff?r1=1.8.2.1&r2=1.8.2.2">mkdep(1)</A>, a shell script. | ||
| 540 | |||
| 541 | |||
| 542 | <p><li>Fix for FreeBSD's make(1), <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/src/usr.bin/make/job.c.diff?r1=1.9&r2=1.10">part 1</A>, | ||
| 543 | <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/src/usr.bin/make/compat.c.diff?r1=1.10&r2=1.11">part 2</A>. | ||
| 544 | |||
| 545 | </ul> | ||
| 546 | |||
| 547 | <H3>Testsuite for shells</H3> | ||
| 548 | |||
| 549 | I have a collection of shellscripts that test shells for the | ||
| 550 | behavior. See my <A HREF="download/">download dir</A> to get the newest | ||
| 551 | "sh-interrupt" files, either as a tarfile or as individual file for | ||
| 552 | online browsing. This isn't really documented, besides from the | ||
| 553 | comments the scripts echo. | ||
| 554 | |||
| 555 | <H3>Appendix 1 - table of implementation choices</H3> | ||
| 556 | |||
| 557 | <table border cellpadding=2> | ||
| 558 | |||
| 559 | <tr valign=top> | ||
| 560 | <th>Method sign</th> | ||
| 561 | <th>Does what?</th> | ||
| 562 | <th>Example shells that implement it:</th> | ||
| 563 | <th>What happens when a shellscript called emacs, the user used | ||
| 564 | <code>C-g</code> and the script has additional commands in it?</th> | ||
| 565 | <th>What happens when a shellscript called emacs, the user did not use | ||
| 566 | <code>C-c</code> and the script has additional commands in it?</th> | ||
| 567 | <th>What happens if a non-interactive child catches SIGINT?</th> | ||
| 568 | <th>To behave properly, childs must do what?</th> | ||
| 569 | </tr> | ||
| 570 | |||
| 571 | <tr valign=top align=left> | ||
| 572 | <td>IUE</td> | ||
| 573 | <td>The shell executing a script exits immediately if it receives | ||
| 574 | SIGINT.</td> | ||
| 575 | <td>4.4BSD ash (ash), NetBSD, FreeBSD prior to 3.0/22.8</td> | ||
| 576 | <td>The editor session is lost and subsequent commands are not | ||
| 577 | executed.</td> | ||
| 578 | <td>The editor continues as normal and the subsequent commands are | ||
| 579 | executed. </td> | ||
| 580 | <td>The scripts ends immediately, returning to the caller even before | ||
| 581 | the current foreground child of the shell exits. </td> | ||
| 582 | <td>It doesn't matter what the child does or how it exits, even if the | ||
| 583 | child continues to operate, the shell returns. </td> | ||
| 584 | </tr> | ||
| 585 | |||
| 586 | <tr valign=top align=left> | ||
| 587 | <td>WUE</td> | ||
| 588 | <td>If the shell executing a script received SIGINT while a foreground | ||
| 589 | process was running, it will exit after that child's exit.</td> | ||
| 590 | <td>pdksh (OpenBSD /bin/sh)</td> | ||
| 591 | <td>The editor continues as normal, but subsequent commands from the | ||
| 592 | script are not executed.</td> | ||
| 593 | <td>The editor continues as normal and subsequent commands are | ||
| 594 | executed. </td> | ||
| 595 | <td>The scripts returns to its caller after the current foreground | ||
| 596 | child exits, no matter how the child exited. </td> | ||
| 597 | <td>It doesn't matter how the child exits (signal status or not), but | ||
| 598 | if it doesn't return at all, the shell will not return. In no case | ||
| 599 | will further commands from the script be executed. </td> | ||
| 600 | </tr> | ||
| 601 | |||
| 602 | <tr valign=top align=left> | ||
| 603 | <td>WCE</td> | ||
| 604 | <td>The shell exits if a child signaled that it was killed on a | ||
| 605 | signal (either it had the default handler for SIGINT or it killed | ||
| 606 | itself). </td> | ||
| 607 | <td>bash (Linux /bin/sh), most commercial /bin/sh, FreeBSD /bin/sh | ||
| 608 | from 3.0/2.2.8.</td> | ||
| 609 | <td>The editor continues as normal and subsequent commands are | ||
| 610 | executed. </td> | ||
| 611 | <td>The editor continues as normal and subsequent commands are | ||
| 612 | executed. </td> | ||
| 613 | <td>The scripts returns to its caller after the current foreground | ||
| 614 | child exits, but only if the child exited with signal status. If | ||
| 615 | the child did a normal exit (even if it received SIGINT, but catches | ||
| 616 | it), the script will continue. </td> | ||
| 617 | <td>The child must be implemented right, or the user will not be able | ||
| 618 | to break shell scripts reliably.</td> | ||
| 619 | </tr> | ||
| 620 | |||
| 621 | </table> | ||
| 622 | |||
| 623 | <P><img src=linie.png width="100%" alt=" "> | ||
| 624 | <BR>©2005 Martin Cracauer <cracauer @ cons.org> | ||
| 625 | <A HREF="http://www.cons.org/cracauer/">http://www.cons.org/cracauer/</A> | ||
| 626 | <BR>Last changed: $Date: 2005/02/11 21:44:43 $ | ||
| 627 | </BODY></HTML> | ||
diff --git a/docs/style-guide.txt b/docs/style-guide.txt new file mode 100644 index 000000000..ba0cdbaa4 --- /dev/null +++ b/docs/style-guide.txt | |||
| @@ -0,0 +1,689 @@ | |||
| 1 | Busybox Style Guide | ||
| 2 | =================== | ||
| 3 | |||
| 4 | This document describes the coding style conventions used in Busybox. If you | ||
| 5 | add a new file to Busybox or are editing an existing file, please format your | ||
| 6 | code according to this style. If you are the maintainer of a file that does | ||
| 7 | not follow these guidelines, please -- at your own convenience -- modify the | ||
| 8 | file(s) you maintain to bring them into conformance with this style guide. | ||
| 9 | Please note that this is a low priority task. | ||
| 10 | |||
| 11 | To help you format the whitespace of your programs, an ".indent.pro" file is | ||
| 12 | included in the main Busybox source directory that contains option flags to | ||
| 13 | format code as per this style guide. This way you can run GNU indent on your | ||
| 14 | files by typing 'indent myfile.c myfile.h' and it will magically apply all the | ||
| 15 | right formatting rules to your file. Please _do_not_ run this on all the files | ||
| 16 | in the directory, just your own. | ||
| 17 | |||
| 18 | |||
| 19 | |||
| 20 | Declaration Order | ||
| 21 | ----------------- | ||
| 22 | |||
| 23 | Here is the order in which code should be laid out in a file: | ||
| 24 | |||
| 25 | - commented program name and one-line description | ||
| 26 | - commented author name and email address(es) | ||
| 27 | - commented GPL boilerplate | ||
| 28 | - commented longer description / notes for the program (if needed) | ||
| 29 | - #includes of .h files with angle brackets (<>) around them | ||
| 30 | - #includes of .h files with quotes ("") around them | ||
| 31 | - #defines (if any, note the section below titled "Avoid the Preprocessor") | ||
| 32 | - const and global variables | ||
| 33 | - function declarations (if necessary) | ||
| 34 | - function implementations | ||
| 35 | |||
| 36 | |||
| 37 | |||
| 38 | Whitespace and Formatting | ||
| 39 | ------------------------- | ||
| 40 | |||
| 41 | This is everybody's favorite flame topic so let's get it out of the way right | ||
| 42 | up front. | ||
| 43 | |||
| 44 | |||
| 45 | Tabs vs. Spaces in Line Indentation | ||
| 46 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 47 | |||
| 48 | The preference in Busybox is to indent lines with tabs. Do not indent lines | ||
| 49 | with spaces and do not indents lines using a mixture of tabs and spaces. (The | ||
| 50 | indentation style in the Apache and Postfix source does this sort of thing: | ||
| 51 | \s\s\s\sif (expr) {\n\tstmt; --ick.) The only exception to this rule is | ||
| 52 | multi-line comments that use an asterisk at the beginning of each line, i.e.: | ||
| 53 | |||
| 54 | \t/* | ||
| 55 | \t * This is a block comment. | ||
| 56 | \t * Note that it has multiple lines | ||
| 57 | \t * and that the beginning of each line has a tab plus a space | ||
| 58 | \t * except for the opening '/*' line where the slash | ||
| 59 | \t * is used instead of a space. | ||
| 60 | \t */ | ||
| 61 | |||
| 62 | Furthermore, The preference is that tabs be set to display at four spaces | ||
| 63 | wide, but the beauty of using only tabs (and not spaces) at the beginning of | ||
| 64 | lines is that you can set your editor to display tabs at *whatever* number of | ||
| 65 | spaces is desired and the code will still look fine. | ||
| 66 | |||
| 67 | |||
| 68 | Operator Spacing | ||
| 69 | ~~~~~~~~~~~~~~~~ | ||
| 70 | |||
| 71 | Put spaces between terms and operators. Example: | ||
| 72 | |||
| 73 | Don't do this: | ||
| 74 | |||
| 75 | for(i=0;i<num_items;i++){ | ||
| 76 | |||
| 77 | Do this instead: | ||
| 78 | |||
| 79 | for (i = 0; i < num_items; i++) { | ||
| 80 | |||
| 81 | While it extends the line a bit longer, the spaced version is more | ||
| 82 | readable. An allowable exception to this rule is the situation where | ||
| 83 | excluding the spacing makes it more obvious that we are dealing with a | ||
| 84 | single term (even if it is a compound term) such as: | ||
| 85 | |||
| 86 | if (str[idx] == '/' && str[idx-1] != '\\') | ||
| 87 | |||
| 88 | or | ||
| 89 | |||
| 90 | if ((argc-1) - (optind+1) > 0) | ||
| 91 | |||
| 92 | |||
| 93 | Bracket Spacing | ||
| 94 | ~~~~~~~~~~~~~~~ | ||
| 95 | |||
| 96 | If an opening bracket starts a function, it should be on the | ||
| 97 | next line with no spacing before it. However, if a bracket follows an opening | ||
| 98 | control block, it should be on the same line with a single space (not a tab) | ||
| 99 | between it and the opening control block statement. Examples: | ||
| 100 | |||
| 101 | Don't do this: | ||
| 102 | |||
| 103 | while (!done) | ||
| 104 | { | ||
| 105 | |||
| 106 | do | ||
| 107 | { | ||
| 108 | |||
| 109 | Don't do this either: | ||
| 110 | |||
| 111 | while (!done){ | ||
| 112 | |||
| 113 | do{ | ||
| 114 | |||
| 115 | And for heaven's sake, don't do this: | ||
| 116 | |||
| 117 | while (!done) | ||
| 118 | { | ||
| 119 | |||
| 120 | do | ||
| 121 | { | ||
| 122 | |||
| 123 | Do this instead: | ||
| 124 | |||
| 125 | while (!done) { | ||
| 126 | |||
| 127 | do { | ||
| 128 | |||
| 129 | Exceptions: | ||
| 130 | |||
| 131 | - if you have long logic statements that need to be wrapped, then uncuddling | ||
| 132 | the bracket to improve readability is allowed: | ||
| 133 | |||
| 134 | if (some_really_long_checks && some_other_really_long_checks \ | ||
| 135 | && some_more_really_long_checks) | ||
| 136 | { | ||
| 137 | do_foo_now; | ||
| 138 | |||
| 139 | Spacing around Parentheses | ||
| 140 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 141 | |||
| 142 | Put a space between C keywords and left parens, but not between function names | ||
| 143 | and the left paren that starts it's parameter list (whether it is being | ||
| 144 | declared or called). Examples: | ||
| 145 | |||
| 146 | Don't do this: | ||
| 147 | |||
| 148 | while(foo) { | ||
| 149 | for(i = 0; i < n; i++) { | ||
| 150 | |||
| 151 | Do this instead: | ||
| 152 | |||
| 153 | while (foo) { | ||
| 154 | for (i = 0; i < n; i++) { | ||
| 155 | |||
| 156 | But do functions like this: | ||
| 157 | |||
| 158 | static int my_func(int foo, char bar) | ||
| 159 | ... | ||
| 160 | baz = my_func(1, 2); | ||
| 161 | |||
| 162 | Also, don't put a space between the left paren and the first term, nor between | ||
| 163 | the last arg and the right paren. | ||
| 164 | |||
| 165 | Don't do this: | ||
| 166 | |||
| 167 | if ( x < 1 ) | ||
| 168 | strcmp( thisstr, thatstr ) | ||
| 169 | |||
| 170 | Do this instead: | ||
| 171 | |||
| 172 | if (x < 1) | ||
| 173 | strcmp(thisstr, thatstr) | ||
| 174 | |||
| 175 | |||
| 176 | Cuddled Elses | ||
| 177 | ~~~~~~~~~~~~~ | ||
| 178 | |||
| 179 | Also, please "cuddle" your else statements by putting the else keyword on the | ||
| 180 | same line after the right bracket that closes an 'if' statement. | ||
| 181 | |||
| 182 | Don't do this: | ||
| 183 | |||
| 184 | if (foo) { | ||
| 185 | stmt; | ||
| 186 | } | ||
| 187 | else { | ||
| 188 | stmt; | ||
| 189 | } | ||
| 190 | |||
| 191 | Do this instead: | ||
| 192 | |||
| 193 | if (foo) { | ||
| 194 | stmt; | ||
| 195 | } else { | ||
| 196 | stmt; | ||
| 197 | } | ||
| 198 | |||
| 199 | The exception to this rule is if you want to include a comment before the else | ||
| 200 | block. Example: | ||
| 201 | |||
| 202 | if (foo) { | ||
| 203 | stmts... | ||
| 204 | } | ||
| 205 | /* otherwise, we're just kidding ourselves, so re-frob the input */ | ||
| 206 | else { | ||
| 207 | other_stmts... | ||
| 208 | } | ||
| 209 | |||
| 210 | |||
| 211 | |||
| 212 | Variable and Function Names | ||
| 213 | --------------------------- | ||
| 214 | |||
| 215 | Use the K&R style with names in all lower-case and underscores occasionally | ||
| 216 | used to separate words (e.g., "variable_name" and "numchars" are both | ||
| 217 | acceptable). Using underscores makes variable and function names more readable | ||
| 218 | because it looks like whitespace; using lower-case is easy on the eyes. | ||
| 219 | |||
| 220 | Frowned upon: | ||
| 221 | |||
| 222 | hitList | ||
| 223 | TotalChars | ||
| 224 | szFileName | ||
| 225 | pf_Nfol_TriState | ||
| 226 | |||
| 227 | Preferred: | ||
| 228 | |||
| 229 | hit_list | ||
| 230 | total_chars | ||
| 231 | file_name | ||
| 232 | sensible_name | ||
| 233 | |||
| 234 | Exceptions: | ||
| 235 | |||
| 236 | - Enums, macros, and constant variables are occasionally written in all | ||
| 237 | upper-case with words optionally seperatedy by underscores (i.e. FIFOTYPE, | ||
| 238 | ISBLKDEV()). | ||
| 239 | |||
| 240 | - Nobody is going to get mad at you for using 'pvar' as the name of a | ||
| 241 | variable that is a pointer to 'var'. | ||
| 242 | |||
| 243 | |||
| 244 | Converting to K&R | ||
| 245 | ~~~~~~~~~~~~~~~~~ | ||
| 246 | |||
| 247 | The Busybox codebase is very much a mixture of code gathered from a variety of | ||
| 248 | sources. This explains why the current codebase contains such a hodge-podge of | ||
| 249 | different naming styles (Java, Pascal, K&R, just-plain-weird, etc.). The K&R | ||
| 250 | guideline explained above should therefore be used on new files that are added | ||
| 251 | to the repository. Furthermore, the maintainer of an existing file that uses | ||
| 252 | alternate naming conventions should, at his own convenience, convert those | ||
| 253 | names over to K&R style. Converting variable names is a very low priority | ||
| 254 | task. | ||
| 255 | |||
| 256 | If you want to do a search-and-replace of a single variable name in different | ||
| 257 | files, you can do the following in the busybox directory: | ||
| 258 | |||
| 259 | $ perl -pi -e 's/\bOldVar\b/new_var/g' *.[ch] | ||
| 260 | |||
| 261 | If you want to convert all the non-K&R vars in your file all at once, follow | ||
| 262 | these steps: | ||
| 263 | |||
| 264 | - In the busybox directory type 'examples/mk2knr.pl files-to-convert'. This | ||
| 265 | does not do the actual conversion, rather, it generates a script called | ||
| 266 | 'convertme.pl' that shows what will be converted, giving you a chance to | ||
| 267 | review the changes beforehand. | ||
| 268 | |||
| 269 | - Review the 'convertme.pl' script that gets generated in the busybox | ||
| 270 | directory and remove / edit any of the substitutions in there. Please | ||
| 271 | especially check for false positives (strings that should not be | ||
| 272 | converted). | ||
| 273 | |||
| 274 | - Type './convertme.pl same-files-as-before' to perform the actual | ||
| 275 | conversion. | ||
| 276 | |||
| 277 | - Compile and see if everything still works. | ||
| 278 | |||
| 279 | Please be aware of changes that have cascading effects into other files. For | ||
| 280 | example, if you're changing the name of something in, say utility.c, you | ||
| 281 | should probably run 'examples/mk2knr.pl utility.c' at first, but when you run | ||
| 282 | the 'convertme.pl' script you should run it on _all_ files like so: | ||
| 283 | './convertme.pl *.[ch]'. | ||
| 284 | |||
| 285 | |||
| 286 | |||
| 287 | Avoid The Preprocessor | ||
| 288 | ---------------------- | ||
| 289 | |||
| 290 | At best, the preprocessor is a necessary evil, helping us account for platform | ||
| 291 | and architecture differences. Using the preprocessor unnecessarily is just | ||
| 292 | plain evil. | ||
| 293 | |||
| 294 | |||
| 295 | The Folly of #define | ||
| 296 | ~~~~~~~~~~~~~~~~~~~~ | ||
| 297 | |||
| 298 | Use 'const <type> var' for declaring constants. | ||
| 299 | |||
| 300 | Don't do this: | ||
| 301 | |||
| 302 | #define var 80 | ||
| 303 | |||
| 304 | Do this instead, when the variable is in a header file and will be used in | ||
| 305 | several source files: | ||
| 306 | |||
| 307 | const int var = 80; | ||
| 308 | |||
| 309 | Or do this when the variable is used only in a single source file: | ||
| 310 | |||
| 311 | static const int var = 80; | ||
| 312 | |||
| 313 | Declaring variables as '[static] const' gives variables an actual type and | ||
| 314 | makes the compiler do type checking for you; the preprocessor does _no_ type | ||
| 315 | checking whatsoever, making it much more error prone. Declaring variables with | ||
| 316 | '[static] const' also makes debugging programs much easier since the value of | ||
| 317 | the variable can be easily queried and displayed. | ||
| 318 | |||
| 319 | |||
| 320 | The Folly of Macros | ||
| 321 | ~~~~~~~~~~~~~~~~~~~ | ||
| 322 | |||
| 323 | Use 'static inline' instead of a macro. | ||
| 324 | |||
| 325 | Don't do this: | ||
| 326 | |||
| 327 | #define mini_func(param1, param2) (param1 << param2) | ||
| 328 | |||
| 329 | Do this instead: | ||
| 330 | |||
| 331 | static inline int mini_func(int param1, param2) | ||
| 332 | { | ||
| 333 | return (param1 << param2); | ||
| 334 | } | ||
| 335 | |||
| 336 | Static inline functions are greatly preferred over macros. They provide type | ||
| 337 | safety, have no length limitations, no formatting limitations, have an actual | ||
| 338 | return value, and under gcc they are as cheap as macros. Besides, really long | ||
| 339 | macros with backslashes at the end of each line are ugly as sin. | ||
| 340 | |||
| 341 | |||
| 342 | The Folly of #ifdef | ||
| 343 | ~~~~~~~~~~~~~~~~~~~ | ||
| 344 | |||
| 345 | Code cluttered with ifdefs is difficult to read and maintain. Don't do it. | ||
| 346 | Instead, put your ifdefs at the top of your .c file (or in a header), and | ||
| 347 | conditionally define 'static inline' functions, (or *maybe* macros), which are | ||
| 348 | used in the code. | ||
| 349 | |||
| 350 | Don't do this: | ||
| 351 | |||
| 352 | ret = my_func(bar, baz); | ||
| 353 | if (!ret) | ||
| 354 | return -1; | ||
| 355 | #ifdef CONFIG_FEATURE_FUNKY | ||
| 356 | maybe_do_funky_stuff(bar, baz); | ||
| 357 | #endif | ||
| 358 | |||
| 359 | Do this instead: | ||
| 360 | |||
| 361 | (in .h header file) | ||
| 362 | |||
| 363 | #ifdef CONFIG_FEATURE_FUNKY | ||
| 364 | static inline void maybe_do_funky_stuff (int bar, int baz) | ||
| 365 | { | ||
| 366 | /* lotsa code in here */ | ||
| 367 | } | ||
| 368 | #else | ||
| 369 | static inline void maybe_do_funky_stuff (int bar, int baz) {} | ||
| 370 | #endif | ||
| 371 | |||
| 372 | (in the .c source file) | ||
| 373 | |||
| 374 | ret = my_func(bar, baz); | ||
| 375 | if (!ret) | ||
| 376 | return -1; | ||
| 377 | maybe_do_funky_stuff(bar, baz); | ||
| 378 | |||
| 379 | The great thing about this approach is that the compiler will optimize away | ||
| 380 | the "no-op" case (the empty function) when the feature is turned off. | ||
| 381 | |||
| 382 | Note also the use of the word 'maybe' in the function name to indicate | ||
| 383 | conditional execution. | ||
| 384 | |||
| 385 | |||
| 386 | |||
| 387 | Notes on Strings | ||
| 388 | ---------------- | ||
| 389 | |||
| 390 | Strings in C can get a little thorny. Here's some guidelines for dealing with | ||
| 391 | strings in Busybox. (There is surely more that could be added to this | ||
| 392 | section.) | ||
| 393 | |||
| 394 | |||
| 395 | String Files | ||
| 396 | ~~~~~~~~~~~~ | ||
| 397 | |||
| 398 | Put all help/usage messages in usage.c. Put other strings in messages.c. | ||
| 399 | Putting these strings into their own file is a calculated decision designed to | ||
| 400 | confine spelling errors to a single place and aid internationalization | ||
| 401 | efforts, if needed. (Side Note: we might want to use a single file - maybe | ||
| 402 | called 'strings.c' - instead of two, food for thought). | ||
| 403 | |||
| 404 | |||
| 405 | Testing String Equivalence | ||
| 406 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 407 | |||
| 408 | There's a right way and a wrong way to test for sting equivalence with | ||
| 409 | strcmp(): | ||
| 410 | |||
| 411 | The wrong way: | ||
| 412 | |||
| 413 | if (!strcmp(string, "foo")) { | ||
| 414 | ... | ||
| 415 | |||
| 416 | The right way: | ||
| 417 | |||
| 418 | if (strcmp(string, "foo") == 0){ | ||
| 419 | ... | ||
| 420 | |||
| 421 | The use of the "equals" (==) operator in the latter example makes it much more | ||
| 422 | obvious that you are testing for equivalence. The former example with the | ||
| 423 | "not" (!) operator makes it look like you are testing for an error. In a more | ||
| 424 | perfect world, we would have a streq() function in the string library, but | ||
| 425 | that ain't the world we're living in. | ||
| 426 | |||
| 427 | |||
| 428 | Avoid Dangerous String Functions | ||
| 429 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 430 | |||
| 431 | Unfortunately, the way C handles strings makes them prone to overruns when | ||
| 432 | certain library functions are (mis)used. The following table offers a summary | ||
| 433 | of some of the more notorious troublemakers: | ||
| 434 | |||
| 435 | function overflows preferred | ||
| 436 | ---------------------------------------- | ||
| 437 | strcpy dest string strncpy | ||
| 438 | strcat dest string strncat | ||
| 439 | gets string it gets fgets | ||
| 440 | getwd buf string getcwd | ||
| 441 | [v]sprintf str buffer [v]snprintf | ||
| 442 | realpath path buffer use with pathconf | ||
| 443 | [vf]scanf its arguments just avoid it | ||
| 444 | |||
| 445 | |||
| 446 | The above is by no means a complete list. Be careful out there. | ||
| 447 | |||
| 448 | |||
| 449 | |||
| 450 | Avoid Big Static Buffers | ||
| 451 | ------------------------ | ||
| 452 | |||
| 453 | First, some background to put this discussion in context: Static buffers look | ||
| 454 | like this in code: | ||
| 455 | |||
| 456 | /* in a .c file outside any functions */ | ||
| 457 | static char buffer[BUFSIZ]; /* happily used by any function in this file, | ||
| 458 | but ick! big! */ | ||
| 459 | |||
| 460 | The problem with these is that any time any busybox app is run, you pay a | ||
| 461 | memory penalty for this buffer, even if the applet that uses said buffer is | ||
| 462 | not run. This can be fixed, thusly: | ||
| 463 | |||
| 464 | static char *buffer; | ||
| 465 | ... | ||
| 466 | other_func() | ||
| 467 | { | ||
| 468 | strcpy(buffer, lotsa_chars); /* happily uses global *buffer */ | ||
| 469 | ... | ||
| 470 | foo_main() | ||
| 471 | { | ||
| 472 | buffer = xmalloc(sizeof(char)*BUFSIZ); | ||
| 473 | ... | ||
| 474 | |||
| 475 | However, this approach trades bss segment for text segment. Rather than | ||
| 476 | mallocing the buffers (and thus growing the text size), buffers can be | ||
| 477 | declared on the stack in the *_main() function and made available globally by | ||
| 478 | assigning them to a global pointer thusly: | ||
| 479 | |||
| 480 | static char *pbuffer; | ||
| 481 | ... | ||
| 482 | other_func() | ||
| 483 | { | ||
| 484 | strcpy(pbuffer, lotsa_chars); /* happily uses global *pbuffer */ | ||
| 485 | ... | ||
| 486 | foo_main() | ||
| 487 | { | ||
| 488 | char *buffer[BUFSIZ]; /* declared locally, on stack */ | ||
| 489 | pbuffer = buffer; /* but available globally */ | ||
| 490 | ... | ||
| 491 | |||
| 492 | This last approach has some advantages (low code size, space not used until | ||
| 493 | it's needed), but can be a problem in some low resource machines that have | ||
| 494 | very limited stack space (e.g., uCLinux). | ||
| 495 | |||
| 496 | A macro is declared in busybox.h that implements compile-time selection | ||
| 497 | between xmalloc() and stack creation, so you can code the line in question as | ||
| 498 | |||
| 499 | RESERVE_CONFIG_BUFFER(buffer, BUFSIZ); | ||
| 500 | |||
| 501 | and the right thing will happen, based on your configuration. | ||
| 502 | |||
| 503 | |||
| 504 | |||
| 505 | Miscellaneous Coding Guidelines | ||
| 506 | ------------------------------- | ||
| 507 | |||
| 508 | The following are important items that don't fit into any of the above | ||
| 509 | sections. | ||
| 510 | |||
| 511 | |||
| 512 | Model Busybox Applets After GNU Counterparts | ||
| 513 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 514 | |||
| 515 | When in doubt about the proper behavior of a Busybox program (output, | ||
| 516 | formatting, options, etc.), model it after the equivalent GNU program. | ||
| 517 | Doesn't matter how that program behaves on some other flavor of *NIX; doesn't | ||
| 518 | matter what the POSIX standard says or doesn't say, just model Busybox | ||
| 519 | programs after their GNU counterparts and it will make life easier on (nearly) | ||
| 520 | everyone. | ||
| 521 | |||
| 522 | The only time we deviate from emulating the GNU behavior is when: | ||
| 523 | |||
| 524 | - We are deliberately not supporting a feature (such as a command line | ||
| 525 | switch) | ||
| 526 | - Emulating the GNU behavior is prohibitively expensive (lots more code | ||
| 527 | would be required, lots more memory would be used, etc.) | ||
| 528 | - The difference is minor or cosmetic | ||
| 529 | |||
| 530 | A note on the 'cosmetic' case: Output differences might be considered | ||
| 531 | cosmetic, but if the output is significant enough to break other scripts that | ||
| 532 | use the output, it should really be fixed. | ||
| 533 | |||
| 534 | |||
| 535 | Scope | ||
| 536 | ~~~~~ | ||
| 537 | |||
| 538 | If a const variable is used only in a single source file, put it in the source | ||
| 539 | file and not in a header file. Likewise, if a const variable is used in only | ||
| 540 | one function, do not make it global to the file. Instead, declare it inside | ||
| 541 | the function body. Bottom line: Make a conscious effort to limit declarations | ||
| 542 | to the smallest scope possible. | ||
| 543 | |||
| 544 | Inside applet files, all functions should be declared static so as to keep the | ||
| 545 | global name space clean. The only exception to this rule is the "applet_main" | ||
| 546 | function which must be declared extern. | ||
| 547 | |||
| 548 | If you write a function that performs a task that could be useful outside the | ||
| 549 | immediate file, turn it into a general-purpose function with no ties to any | ||
| 550 | applet and put it in the utility.c file instead. | ||
| 551 | |||
| 552 | |||
| 553 | Brackets Are Your Friends | ||
| 554 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 555 | |||
| 556 | Please use brackets on all if and else statements, even if it is only one | ||
| 557 | line. Example: | ||
| 558 | |||
| 559 | Don't do this: | ||
| 560 | |||
| 561 | if (foo) | ||
| 562 | stmt1; | ||
| 563 | stmt2 | ||
| 564 | stmt3; | ||
| 565 | |||
| 566 | Do this instead: | ||
| 567 | |||
| 568 | if (foo) { | ||
| 569 | stmt1; | ||
| 570 | } | ||
| 571 | stmt2 | ||
| 572 | stmt3; | ||
| 573 | |||
| 574 | The "bracketless" approach is error prone because someday you might add a line | ||
| 575 | like this: | ||
| 576 | |||
| 577 | if (foo) | ||
| 578 | stmt1; | ||
| 579 | new_line(); | ||
| 580 | stmt2 | ||
| 581 | stmt3; | ||
| 582 | |||
| 583 | And the resulting behavior of your program would totally bewilder you. (Don't | ||
| 584 | laugh, it happens to us all.) Remember folks, this is C, not Python. | ||
| 585 | |||
| 586 | |||
| 587 | Function Declarations | ||
| 588 | ~~~~~~~~~~~~~~~~~~~~~ | ||
| 589 | |||
| 590 | Do not use old-style function declarations that declare variable types between | ||
| 591 | the parameter list and opening bracket. Example: | ||
| 592 | |||
| 593 | Don't do this: | ||
| 594 | |||
| 595 | int foo(parm1, parm2) | ||
| 596 | char parm1; | ||
| 597 | float parm2; | ||
| 598 | { | ||
| 599 | .... | ||
| 600 | |||
| 601 | Do this instead: | ||
| 602 | |||
| 603 | int foo(char parm1, float parm2) | ||
| 604 | { | ||
| 605 | .... | ||
| 606 | |||
| 607 | The only time you would ever need to use the old declaration syntax is to | ||
| 608 | support ancient, antediluvian compilers. To our good fortune, we have access | ||
| 609 | to more modern compilers and the old declaration syntax is neither necessary | ||
| 610 | nor desired. | ||
| 611 | |||
| 612 | |||
| 613 | Emphasizing Logical Blocks | ||
| 614 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 615 | |||
| 616 | Organization and readability are improved by putting extra newlines around | ||
| 617 | blocks of code that perform a single task. These are typically blocks that | ||
| 618 | begin with a C keyword, but not always. | ||
| 619 | |||
| 620 | Furthermore, you should put a single comment (not necessarily one line, just | ||
| 621 | one comment) before the block, rather than commenting each and every line. | ||
| 622 | There is an optimal amount of commenting that a program can have; you can | ||
| 623 | comment too much as well as too little. | ||
| 624 | |||
| 625 | A picture is really worth a thousand words here, the following example | ||
| 626 | illustrates how to emphasize logical blocks: | ||
| 627 | |||
| 628 | while (line = get_line_from_file(fp)) { | ||
| 629 | |||
| 630 | /* eat the newline, if any */ | ||
| 631 | chomp(line); | ||
| 632 | |||
| 633 | /* ignore blank lines */ | ||
| 634 | if (strlen(file_to_act_on) == 0) { | ||
| 635 | continue; | ||
| 636 | } | ||
| 637 | |||
| 638 | /* if the search string is in this line, print it, | ||
| 639 | * unless we were told to be quiet */ | ||
| 640 | if (strstr(line, search) && !be_quiet) { | ||
| 641 | puts(line); | ||
| 642 | } | ||
| 643 | |||
| 644 | /* clean up */ | ||
| 645 | free(line); | ||
| 646 | } | ||
| 647 | |||
| 648 | |||
| 649 | Processing Options with getopt | ||
| 650 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 651 | |||
| 652 | If your applet needs to process command-line switches, please use getopt() to | ||
| 653 | do so. Numerous examples can be seen in many of the existing applets, but | ||
| 654 | basically it boils down to two things: at the top of the .c file, have this | ||
| 655 | line in the midst of your #includes: | ||
| 656 | |||
| 657 | #include <getopt.h> | ||
| 658 | |||
| 659 | And a code block similar to the following near the top of your applet_main() | ||
| 660 | routine: | ||
| 661 | |||
| 662 | while ((opt = getopt(argc, argv, "abc")) > 0) { | ||
| 663 | switch (opt) { | ||
| 664 | case 'a': | ||
| 665 | do_a_opt = 1; | ||
| 666 | break; | ||
| 667 | case 'b': | ||
| 668 | do_b_opt = 1; | ||
| 669 | break; | ||
| 670 | case 'c': | ||
| 671 | do_c_opt = 1; | ||
| 672 | break; | ||
| 673 | default: | ||
| 674 | show_usage(); /* in utility.c */ | ||
| 675 | } | ||
| 676 | } | ||
| 677 | |||
| 678 | If your applet takes no options (such as 'init'), there should be a line | ||
| 679 | somewhere in the file reads: | ||
| 680 | |||
| 681 | /* no options, no getopt */ | ||
| 682 | |||
| 683 | That way, when people go grepping to see which applets need to be converted to | ||
| 684 | use getopt, they won't get false positives. | ||
| 685 | |||
| 686 | Additional Note: Do not use the getopt_long library function and do not try to | ||
| 687 | hand-roll your own long option parsing. Busybox applets should only support | ||
| 688 | short options. Explanations and examples of the short options should be | ||
| 689 | documented in usage.h. | ||
diff --git a/docs/tar_pax.txt b/docs/tar_pax.txt new file mode 100644 index 000000000..8a3f1e755 --- /dev/null +++ b/docs/tar_pax.txt | |||
| @@ -0,0 +1,239 @@ | |||
| 1 | 'pax headers' is POSIX 2003 (iirc) addition designed to fix | ||
| 2 | tar format limitations - older tar format has fixed fields | ||
| 3 | for everything (filename, uid, filesize etc) which can overflow. | ||
| 4 | |||
| 5 | pax Header Block | ||
| 6 | |||
| 7 | The pax header block shall be identical to the ustar header block | ||
| 8 | described in ustar Interchange Format, except that two additional | ||
| 9 | typeflag values are defined: | ||
| 10 | |||
| 11 | x | ||
| 12 | Represents extended header records for the following file in | ||
| 13 | the archive (which shall have its own ustar header block). | ||
| 14 | |||
| 15 | g | ||
| 16 | Represents global extended header records for the following | ||
| 17 | files in the archive. Each value shall affect all subsequent files | ||
| 18 | that do not override that value in their own extended header | ||
| 19 | record and until another global extended header record is reached | ||
| 20 | that provides another value for the same field. The typeflag g | ||
| 21 | global headers should not be used with interchange media that | ||
| 22 | could suffer partial data loss in transporting the archive. | ||
| 23 | |||
| 24 | For both of these types, the size field shall be the size of the | ||
| 25 | extended header records in octets. The other fields in the header | ||
| 26 | block are not meaningful to this version of the pax utility. | ||
| 27 | However, if this archive is read by a pax utility conforming to | ||
| 28 | the ISO POSIX-2:1993 standard, the header block fields are used to | ||
| 29 | create a regular file that contains the extended header records as | ||
| 30 | data. Therefore, header block field values should be selected to | ||
| 31 | provide reasonable file access to this regular file. | ||
| 32 | |||
| 33 | A further difference from the ustar header block is that data | ||
| 34 | blocks for files of typeflag 1 (the digit one) (hard link) may be | ||
| 35 | included, which means that the size field may be greater than | ||
| 36 | zero. | ||
| 37 | |||
| 38 | pax Extended Header | ||
| 39 | |||
| 40 | An extended header shall consist of one or more records, each | ||
| 41 | constructed as follows: | ||
| 42 | |||
| 43 | "%d %s=%s\n", <length>, <keyword>, <value> | ||
| 44 | |||
| 45 | The <length> field shall be the decimal length of the extended | ||
| 46 | header record in octets, including length string itself and the | ||
| 47 | trailing <newline>. | ||
| 48 | |||
| 49 | [skip] | ||
| 50 | |||
| 51 | atime | ||
| 52 | The file access time for the following file(s), equivalent to | ||
| 53 | the value of the st_atime member of the stat structure for a file, | ||
| 54 | as described by the stat() function. The access time shall be | ||
| 55 | restored if the process has the appropriate privilege required to | ||
| 56 | do so. The format of the <value> shall be as described in pax | ||
| 57 | Extended Header File Times. | ||
| 58 | |||
| 59 | charset | ||
| 60 | The name of the character set used to encode the data in the | ||
| 61 | following file(s). | ||
| 62 | |||
| 63 | The encoding is included in an extended header for information | ||
| 64 | only; when pax is used as described in IEEE Std 1003.1-2001, it | ||
| 65 | shall not translate the file data into any other encoding. The | ||
| 66 | BINARY entry indicates unencoded binary data. | ||
| 67 | |||
| 68 | When used in write or copy mode, it is implementation-defined | ||
| 69 | whether pax includes a charset extended header record for a file. | ||
| 70 | |||
| 71 | comment | ||
| 72 | A series of characters used as a comment. All characters in | ||
| 73 | the <value> field shall be ignored by pax. | ||
| 74 | |||
| 75 | gid | ||
| 76 | The group ID of the group that owns the file, expressed as a | ||
| 77 | decimal number using digits from the ISO/IEC 646:1991 standard. | ||
| 78 | This record shall override the gid field in the following header | ||
| 79 | block(s). When used in write or copy mode, pax shall include a gid | ||
| 80 | extended header record for each file whose group ID is greater | ||
| 81 | than 2097151 (octal 7777777). | ||
| 82 | |||
| 83 | gname | ||
| 84 | The group of the file(s), formatted as a group name in the | ||
| 85 | group database. This record shall override the gid and gname | ||
| 86 | fields in the following header block(s), and any gid extended | ||
| 87 | header record. When used in read, copy, or list mode, pax shall | ||
| 88 | translate the name from the UTF-8 encoding in the header record to | ||
| 89 | the character set appropriate for the group database on the | ||
| 90 | receiving system. If any of the UTF-8 characters cannot be | ||
| 91 | translated, and if the -o invalid= UTF-8 option is not specified, | ||
| 92 | the results are implementation-defined. When used in write or copy | ||
| 93 | mode, pax shall include a gname extended header record for each | ||
| 94 | file whose group name cannot be represented entirely with the | ||
| 95 | letters and digits of the portable character set. | ||
| 96 | |||
| 97 | linkpath | ||
| 98 | The pathname of a link being created to another file, of any | ||
| 99 | type, previously archived. This record shall override the linkname | ||
| 100 | field in the following ustar header block(s). The following ustar | ||
| 101 | header block shall determine the type of link created. If typeflag | ||
| 102 | of the following header block is 1, it shall be a hard link. If | ||
| 103 | typeflag is 2, it shall be a symbolic link and the linkpath value | ||
| 104 | shall be the contents of the symbolic link. The pax utility shall | ||
| 105 | translate the name of the link (contents of the symbolic link) | ||
| 106 | from the UTF-8 encoding to the character set appropriate for the | ||
| 107 | local file system. When used in write or copy mode, pax shall | ||
| 108 | include a linkpath extended header record for each link whose | ||
| 109 | pathname cannot be represented entirely with the members of the | ||
| 110 | portable character set other than NUL. | ||
| 111 | |||
| 112 | mtime | ||
| 113 | The file modification time of the following file(s), | ||
| 114 | equivalent to the value of the st_mtime member of the stat | ||
| 115 | structure for a file, as described in the stat() function. This | ||
| 116 | record shall override the mtime field in the following header | ||
| 117 | block(s). The modification time shall be restored if the process | ||
| 118 | has the appropriate privilege required to do so. The format of the | ||
| 119 | <value> shall be as described in pax Extended Header File Times. | ||
| 120 | |||
| 121 | path | ||
| 122 | The pathname of the following file(s). This record shall | ||
| 123 | override the name and prefix fields in the following header | ||
| 124 | block(s). The pax utility shall translate the pathname of the file | ||
| 125 | from the UTF-8 encoding to the character set appropriate for the | ||
| 126 | local file system. | ||
| 127 | |||
| 128 | When used in write or copy mode, pax shall include a path | ||
| 129 | extended header record for each file whose pathname cannot be | ||
| 130 | represented entirely with the members of the portable character | ||
| 131 | set other than NUL. | ||
| 132 | |||
| 133 | realtime.any | ||
| 134 | The keywords prefixed by "realtime." are reserved for future | ||
| 135 | standardization. | ||
| 136 | |||
| 137 | security.any | ||
| 138 | The keywords prefixed by "security." are reserved for future | ||
| 139 | standardization. | ||
| 140 | |||
| 141 | size | ||
| 142 | The size of the file in octets, expressed as a decimal number | ||
| 143 | using digits from the ISO/IEC 646:1991 standard. This record shall | ||
| 144 | override the size field in the following header block(s). When | ||
| 145 | used in write or copy mode, pax shall include a size extended | ||
| 146 | header record for each file with a size value greater than | ||
| 147 | 8589934591 (octal 77777777777). | ||
| 148 | |||
| 149 | uid | ||
| 150 | The user ID of the file owner, expressed as a decimal number | ||
| 151 | using digits from the ISO/IEC 646:1991 standard. This record shall | ||
| 152 | override the uid field in the following header block(s). When used | ||
| 153 | in write or copy mode, pax shall include a uid extended header | ||
| 154 | record for each file whose owner ID is greater than 2097151 (octal | ||
| 155 | 7777777). | ||
| 156 | |||
| 157 | uname | ||
| 158 | The owner of the following file(s), formatted as a user name | ||
| 159 | in the user database. This record shall override the uid and uname | ||
| 160 | fields in the following header block(s), and any uid extended | ||
| 161 | header record. When used in read, copy, or list mode, pax shall | ||
| 162 | translate the name from the UTF-8 encoding in the header record to | ||
| 163 | the character set appropriate for the user database on the | ||
| 164 | receiving system. If any of the UTF-8 characters cannot be | ||
| 165 | translated, and if the -o invalid= UTF-8 option is not specified, | ||
| 166 | the results are implementation-defined. When used in write or copy | ||
| 167 | mode, pax shall include a uname extended header record for each | ||
| 168 | file whose user name cannot be represented entirely with the | ||
| 169 | letters and digits of the portable character set. | ||
| 170 | |||
| 171 | If the <value> field is zero length, it shall delete any header | ||
| 172 | block field, previously entered extended header value, or global | ||
| 173 | extended header value of the same name. | ||
| 174 | |||
| 175 | If a keyword in an extended header record (or in a -o | ||
| 176 | option-argument) overrides or deletes a corresponding field in the | ||
| 177 | ustar header block, pax shall ignore the contents of that header | ||
| 178 | block field. | ||
| 179 | |||
| 180 | Unlike the ustar header block fields, NULs shall not delimit | ||
| 181 | <value>s; all characters within the <value> field shall be | ||
| 182 | considered data for the field. None of the length limitations of | ||
| 183 | the ustar header block fields in ustar Header Block shall apply to | ||
| 184 | the extended header records. | ||
| 185 | |||
| 186 | pax Extended Header File Times | ||
| 187 | |||
| 188 | Time records shall be formatted as a decimal representation of the | ||
| 189 | time in seconds since the Epoch. If a period ( '.' ) decimal point | ||
| 190 | character is present, the digits to the right of the point shall | ||
| 191 | represent the units of a subsecond timing granularity. In read or | ||
| 192 | copy mode, the pax utility shall truncate the time of a file to | ||
| 193 | the greatest value that is not greater than the input header | ||
| 194 | file time. In write or copy mode, the pax utility shall output a | ||
| 195 | time exactly if it can be represented exactly as a decimal number, | ||
| 196 | and otherwise shall generate only enough digits so that the same | ||
| 197 | time shall be recovered if the file is extracted on a system whose | ||
| 198 | underlying implementation supports the same time granularity. | ||
| 199 | |||
| 200 | Example from Linux kernel archive tarball: | ||
| 201 | |||
| 202 | 00000000 70 61 78 5f 67 6c 6f 62 61 6c 5f 68 65 61 64 65 |pax_global_heade| | ||
| 203 | 00000010 72 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |r...............| | ||
| 204 | 00000020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 205 | 00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 206 | 00000040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 207 | 00000050 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 208 | 00000060 00 00 00 00 30 30 30 30 36 36 36 00 30 30 30 30 |....0000666.0000| | ||
| 209 | 00000070 30 30 30 00 30 30 30 30 30 30 30 00 30 30 30 30 |000.0000000.0000| | ||
| 210 | 00000080 30 30 30 30 30 36 34 00 30 30 30 30 30 30 30 30 |0000064.00000000| | ||
| 211 | 00000090 30 30 30 00 30 30 31 34 30 35 33 00 67 00 00 00 |000.0014053.g...| | ||
| 212 | 000000a0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 213 | 000000b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 214 | 000000c0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 215 | 000000d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 216 | 000000e0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 217 | 000000f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 218 | 00000100 00 75 73 74 61 72 00 30 30 67 69 74 00 00 00 00 |.ustar.00git....| | ||
| 219 | 00000110 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 220 | 00000120 00 00 00 00 00 00 00 00 00 67 69 74 00 00 00 00 |.........git....| | ||
| 221 | 00000130 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 222 | 00000140 00 00 00 00 00 00 00 00 00 30 30 30 30 30 30 30 |.........0000000| | ||
| 223 | 00000150 00 30 30 30 30 30 30 30 00 00 00 00 00 00 00 00 |.0000000........| | ||
| 224 | 00000160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 225 | 00000170 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 226 | 00000180 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 227 | 00000190 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 228 | 000001a0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 229 | 000001b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 230 | 000001c0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 231 | 000001d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 232 | 000001e0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 233 | 000001f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 234 | 00000200 35 32 20 63 6f 6d 6d 65 6e 74 3d 62 31 30 35 30 |52 comment=b1050| | ||
| 235 | 00000210 32 62 32 32 61 31 32 30 39 64 36 62 34 37 36 33 |2b22a1209d6b4763| | ||
| 236 | 00000220 39 64 38 38 62 38 31 32 62 32 31 66 62 35 39 34 |9d88b812b21fb594| | ||
| 237 | 00000230 39 65 34 0a 00 00 00 00 00 00 00 00 00 00 00 00 |9e4.............| | ||
| 238 | 00000240 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| | ||
| 239 | ... | ||
