blob: 608a31615e8e6e86676b00e032f84a4ed1710042 [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
Eric Andersene5d58c32001-11-10 10:46:42 +000042 glibc-2.0.x, glibc-2.1.x, glibc-2.2.x, Linux-libc5, uClibc. People
43 are looking at newlib and diet-libc, but consider them unsupported,
44 untested, or worse.
Mark Whitley3654ca52001-01-26 20:58:23 +000045
46Supported kernels:
47
48 Full functionality requires Linux 2.0.x, 2.2.x, or 2.4.x. A large fraction
49 of the code should run on just about anything.
50
51----------------
Eric Andersen235f66d2000-12-13 18:07:38 +000052
Matt Kraai2d91deb2001-08-01 17:21:35 +000053Shells:
54
55lash is the very smallest shell (adds just 10k) and it is quite usable as
56a command prompt, but it is not suitable for any but the most trivial
57scripting (such as an initrd that calls insmod a few times) since it does
58not understand Bourne shell grammer. It does handle pipes, redirects, and
Eric Andersen9e6089e2001-08-02 19:31:08 +000059job control though. Adding in command editing makes it a very nice
Matt Kraai2d91deb2001-08-01 17:21:35 +000060lightweight command prompt.
61
62hush is also quite small (just 18k) and it has very complete Bourne shell
63grammer. It handles if/then/else/fi just fine, but doesn't handle loops
64like for/do/done or case/esac and such. It also currently has a problem
Eric Andersen9e6089e2001-08-02 19:31:08 +000065with job control. Using hush is not yet recommended.
Matt Kraai2d91deb2001-08-01 17:21:35 +000066
67msh: The minix shell (adds just 30k) is quite complete and handles things
68like for/do/done, case/esac and all the things you expect a Bourne shell to
69do. It is not always pedantically correct about Bourne shell grammer (try
70running the shell testscript "tests/sh.testcases" on it and compare vs bash)
71but for most things it works quite well. It also uses only vfork, so it can
72be used on uClinux systems. This was only recently added, so there is still
73room to shrink it further...
74
75ash: This adds about 60k in the default configuration and is the most
76complete and most pedantically correct shell included with busybox. This
77shell was also recently added, and several people (mainly Vladimir and Erik)
78have been working on it. There are a number of configurable things at the
Eric Andersen9e6089e2001-08-02 19:31:08 +000079top of ash.c as well, so check those out if you want to tweak things.
Matt Kraai2d91deb2001-08-01 17:21:35 +000080
81----------------
82
Eric Andersena29dec22000-06-22 00:19:33 +000083Getting help:
Eric Andersen235f66d2000-12-13 18:07:38 +000084
Eric Andersena29dec22000-06-22 00:19:33 +000085When you find you need help, you can check out the BusyBox mailing list
Eric Andersenbdfd0d72001-10-24 05:00:29 +000086archives at http://oss.lineo.com/lists/busybox/ or even join
Eric Andersena29dec22000-06-22 00:19:33 +000087the mailing list if you are interested.
88
89----------------
Eric Andersen235f66d2000-12-13 18:07:38 +000090
Eric Andersena29dec22000-06-22 00:19:33 +000091Bugs:
Eric Andersen235f66d2000-12-13 18:07:38 +000092
93If you find bugs, please submit a bug report. Full instructions on how to
94report a bug are found at http://bugs.lineo.com/Reporting.html.
95
96For the impatient: To submit a bug, simply send an email describing the problem
97to submit@bugs.lineo.com. Bug reports should look something like this:
98
99 To: submit@bugs.lineo.com
100 From: diligent@testing.linux.org
101 Subject: /bin/true doesn't work
102
103 Package: busybox
Eric Andersen09580932001-04-10 20:10:55 +0000104 Version: 0.51
Eric Andersen235f66d2000-12-13 18:07:38 +0000105
106 When I invoke '/bin/true' it doesn't work. I expected it to return
107 a "0" but it returned a "1" instead. Here is the transcript:
108 $ /bin/true ; echo $?
109 1
110 With GNU /bin/true, I get the following output:
111 $ /bin/true ; echo $?
112 0
113 I am using Debian 2.2r2, kernel version 2.2.18, and the latest
114 uClibc from CVS. Thanks for the wonderful program!
115 -Diligent
116
117Note the careful description and use of examples showing not only what BusyBox
118does, but also a counter example showing what an equivalent GNU app does. Bug
119reports lacking such detail may take a _long_ time to be fixed... Thanks for
120understanding.
Eric Andersena29dec22000-06-22 00:19:33 +0000121
122----------------
Eric Andersen235f66d2000-12-13 18:07:38 +0000123
Eric Andersena29dec22000-06-22 00:19:33 +0000124FTP:
Eric Andersen235f66d2000-12-13 18:07:38 +0000125
Eric Andersena29dec22000-06-22 00:19:33 +0000126Source for the latest released version can always be downloaded from
127 ftp://ftp.lineo.com/pub/busybox.
128
129----------------
Eric Andersen235f66d2000-12-13 18:07:38 +0000130
Eric Andersena29dec22000-06-22 00:19:33 +0000131CVS:
Eric Andersen235f66d2000-12-13 18:07:38 +0000132
Eric Andersen07309432000-11-29 22:12:19 +0000133BusyBox now has its own publicly browsable CVS tree at:
Eric Andersenbdfd0d72001-10-24 05:00:29 +0000134 http://oss.lineo.com/cgi-bin/cvsweb/busybox/
Eric Andersena29dec22000-06-22 00:19:33 +0000135
136Anonymous CVS access is available. For instructions, check out:
Eric Andersenbdfd0d72001-10-24 05:00:29 +0000137 http://oss.lineo.com/cvs_anon.html
Eric Andersena29dec22000-06-22 00:19:33 +0000138
139For those that are actively contributing there is even CVS write access:
Eric Andersenbdfd0d72001-10-24 05:00:29 +0000140 http://oss.lineo.com/cvs_write.html
Eric Andersena29dec22000-06-22 00:19:33 +0000141
Eric Andersena29dec22000-06-22 00:19:33 +0000142----------------
143
Eric Andersended62591999-11-18 00:19:26 +0000144Please feed suggestions, bug reports, insults, and bribes back to:
145 Erik Andersen
Eric Andersenbdfd0d72001-10-24 05:00:29 +0000146 <andersen@codepoet.org>
Eric Andersen664584b1999-12-11 23:25:59 +0000147 <andersee@debian.org>
Eric Andersen84b00921999-12-11 04:16:51 +0000148