blob: b45ef57f46b85ffbe443c260e9bb469e05d0d3de [file] [log] [blame]
Eric Andersencc8ed391999-10-05 16:24:54 +00001Please see the LICENSE file for copyright information.
Erik Andersen330fd2b2000-05-19 05:35:19 +00002
3BusyBox combines tiny versions of many common UNIX utilities into a single
4small executable. It provides minimalist replacements for most of the utilities
5you usually find in fileutils, shellutils, findutils, textutils, grep, gzip,
6tar, etc. BusyBox provides a fairly complete POSIX environment for any small or
Eric Andersen07309432000-11-29 22:12:19 +00007embedded system. The utilities in BusyBox generally have fewer options than
Erik Andersen330fd2b2000-05-19 05:35:19 +00008their full featured GNU cousins; however, the options that are included provide
9the expected functionality and behave very much like their GNU counterparts.
Eric Andersencc8ed391999-10-05 16:24:54 +000010
Erik Andersen330fd2b2000-05-19 05:35:19 +000011BusyBox has been written with size-optimization and limited resources in mind.
12It is also extremely modular so you can easily include or exclude commands (or
13features) at compile time. This makes it easy to customize your embedded
Eric Andersen9e6089e2001-08-02 19:31:08 +000014systems. To create a working system, just add /dev, /etc, and a kernel.
Eric Andersencc8ed391999-10-05 16:24:54 +000015
Eric Andersen07309432000-11-29 22:12:19 +000016BusyBox was originally written to support the Debian Rescue/Install disks, but
Erik Andersen330fd2b2000-05-19 05:35:19 +000017it also makes an excellent environment for any small or embedded system.
Eric Andersencc8ed391999-10-05 16:24:54 +000018
Eric Andersen235f66d2000-12-13 18:07:38 +000019As of version 0.20 there is now a version number. : ) Also as of version 0.20,
Erik Andersen330fd2b2000-05-19 05:35:19 +000020BusyBox is now modularized to easily allow you to build only the components you
Eric Andersen07309432000-11-29 22:12:19 +000021need, thereby reducing binary size. To turn off unwanted BusyBox components,
Eric Andersen235f66d2000-12-13 18:07:38 +000022simply edit the file "Config.h" and comment out the components you do not need
23using C++ style (//) comments.
Erik Andersen330fd2b2000-05-19 05:35:19 +000024
Eric Andersen07309432000-11-29 22:12:19 +000025After the build is complete, a busybox.links file is generated. This is
Erik Andersen330fd2b2000-05-19 05:35:19 +000026used by 'make install' to create symlinks to the busybox binary for all
27compiled in functions. By default, 'make install' will place the symlink
28forest into `pwd`/_install unless you have defined the PREFIX environment
Eric Andersen8ec10a92001-01-27 09:33:39 +000029variable (i.e., 'make PREFIX=/tmp/foo install')
Eric Andersencc8ed391999-10-05 16:24:54 +000030
Eric Andersena29dec22000-06-22 00:19:33 +000031----------------
Mark Whitley3654ca52001-01-26 20:58:23 +000032
33Supported architectures:
34
35 Busybox in general will build on any architecture supported by gcc. It has
36 a few specialized features added for __sparc__ and __alpha__. insmod
Eric Andersen2835efe2001-07-25 16:58:58 +000037 functionality is currently limited to x86, ARM, SH3/4, powerpc, m68k,
38 and MIPS.
Mark Whitley3654ca52001-01-26 20:58:23 +000039
40Supported libcs:
41
42 glibc-2.0.x, glibc-2.1.x, Linux-libc5, uClibc. People are looking at
43 newlib and diet-libc, but consider them unsupported, untested, or worse.
44
45Supported kernels:
46
47 Full functionality requires Linux 2.0.x, 2.2.x, or 2.4.x. A large fraction
48 of the code should run on just about anything.
49
50----------------
Eric Andersen235f66d2000-12-13 18:07:38 +000051
Matt Kraai2d91deb2001-08-01 17:21:35 +000052Shells:
53
54lash is the very smallest shell (adds just 10k) and it is quite usable as
55a command prompt, but it is not suitable for any but the most trivial
56scripting (such as an initrd that calls insmod a few times) since it does
57not understand Bourne shell grammer. It does handle pipes, redirects, and
Eric Andersen9e6089e2001-08-02 19:31:08 +000058job control though. Adding in command editing makes it a very nice
Matt Kraai2d91deb2001-08-01 17:21:35 +000059lightweight command prompt.
60
61hush is also quite small (just 18k) and it has very complete Bourne shell
62grammer. It handles if/then/else/fi just fine, but doesn't handle loops
63like for/do/done or case/esac and such. It also currently has a problem
Eric Andersen9e6089e2001-08-02 19:31:08 +000064with job control. Using hush is not yet recommended.
Matt Kraai2d91deb2001-08-01 17:21:35 +000065
66msh: The minix shell (adds just 30k) is quite complete and handles things
67like for/do/done, case/esac and all the things you expect a Bourne shell to
68do. It is not always pedantically correct about Bourne shell grammer (try
69running the shell testscript "tests/sh.testcases" on it and compare vs bash)
70but for most things it works quite well. It also uses only vfork, so it can
71be used on uClinux systems. This was only recently added, so there is still
72room to shrink it further...
73
74ash: This adds about 60k in the default configuration and is the most
75complete and most pedantically correct shell included with busybox. This
76shell was also recently added, and several people (mainly Vladimir and Erik)
77have been working on it. There are a number of configurable things at the
Eric Andersen9e6089e2001-08-02 19:31:08 +000078top of ash.c as well, so check those out if you want to tweak things.
Matt Kraai2d91deb2001-08-01 17:21:35 +000079
80----------------
81
Eric Andersena29dec22000-06-22 00:19:33 +000082Getting help:
Eric Andersen235f66d2000-12-13 18:07:38 +000083
Eric Andersena29dec22000-06-22 00:19:33 +000084When you find you need help, you can check out the BusyBox mailing list
85archives at http://opensource.lineo.com/lists/busybox/ or even join
86the mailing list if you are interested.
87
88----------------
Eric Andersen235f66d2000-12-13 18:07:38 +000089
Eric Andersena29dec22000-06-22 00:19:33 +000090Bugs:
Eric Andersen235f66d2000-12-13 18:07:38 +000091
92If you find bugs, please submit a bug report. Full instructions on how to
93report a bug are found at http://bugs.lineo.com/Reporting.html.
94
95For the impatient: To submit a bug, simply send an email describing the problem
96to submit@bugs.lineo.com. Bug reports should look something like this:
97
98 To: submit@bugs.lineo.com
99 From: diligent@testing.linux.org
100 Subject: /bin/true doesn't work
101
102 Package: busybox
Eric Andersen09580932001-04-10 20:10:55 +0000103 Version: 0.51
Eric Andersen235f66d2000-12-13 18:07:38 +0000104
105 When I invoke '/bin/true' it doesn't work. I expected it to return
106 a "0" but it returned a "1" instead. Here is the transcript:
107 $ /bin/true ; echo $?
108 1
109 With GNU /bin/true, I get the following output:
110 $ /bin/true ; echo $?
111 0
112 I am using Debian 2.2r2, kernel version 2.2.18, and the latest
113 uClibc from CVS. Thanks for the wonderful program!
114 -Diligent
115
116Note the careful description and use of examples showing not only what BusyBox
117does, but also a counter example showing what an equivalent GNU app does. Bug
118reports lacking such detail may take a _long_ time to be fixed... Thanks for
119understanding.
Eric Andersena29dec22000-06-22 00:19:33 +0000120
121----------------
Eric Andersen235f66d2000-12-13 18:07:38 +0000122
Eric Andersena29dec22000-06-22 00:19:33 +0000123FTP:
Eric Andersen235f66d2000-12-13 18:07:38 +0000124
Eric Andersena29dec22000-06-22 00:19:33 +0000125Source for the latest released version can always be downloaded from
126 ftp://ftp.lineo.com/pub/busybox.
127
128----------------
Eric Andersen235f66d2000-12-13 18:07:38 +0000129
Eric Andersena29dec22000-06-22 00:19:33 +0000130CVS:
Eric Andersen235f66d2000-12-13 18:07:38 +0000131
Eric Andersen07309432000-11-29 22:12:19 +0000132BusyBox now has its own publicly browsable CVS tree at:
Eric Andersena29dec22000-06-22 00:19:33 +0000133 http://opensource.lineo.com/cgi-bin/cvsweb/busybox/
134
135Anonymous CVS access is available. For instructions, check out:
136 http://opensource.lineo.com/cvs_anon.html
137
138For those that are actively contributing there is even CVS write access:
139 http://opensource.lineo.com/cvs_write.html
140
Eric Andersena29dec22000-06-22 00:19:33 +0000141----------------
142
Eric Andersended62591999-11-18 00:19:26 +0000143Please feed suggestions, bug reports, insults, and bribes back to:
144 Erik Andersen
145 <andersen@lineo.com>
Eric Andersen664584b1999-12-11 23:25:59 +0000146 <andersee@debian.org>
Eric Andersen09580932001-04-10 20:10:55 +0000147 <andersee@codepoet.org>
Eric Andersencc8ed391999-10-05 16:24:54 +0000148
Eric Andersen07309432000-11-29 22:12:19 +0000149<blatant plug>
Eric Andersen84b00921999-12-11 04:16:51 +0000150Many thanks to go to Lineo for paying me to work on busybox.
Eric Andersen07309432000-11-29 22:12:19 +0000151</blatant plug>
Eric Andersen84b00921999-12-11 04:16:51 +0000152