-Please see the LICENSE file for copyright information.
-
-BusyBox combines tiny versions of many common UNIX utilities into a single
-small executable. It provides minimalist replacements for most of the utilities
-you usually find in fileutils, shellutils, findutils, textutils, grep, gzip,
-tar, etc. BusyBox provides a fairly complete POSIX environment for any small or
-embedded system. The utilities in BusyBox generally have fewer options than
-their full featured GNU cousins; however, the options that are included provide
-the expected functionality and behave very much like their GNU counterparts.
-
-BusyBox has been written with size-optimization and limited resources in mind.
-It is also extremely modular so you can easily include or exclude commands (or
-features) at compile time. This makes it easy to customize your embedded
-systems. To create a working system, just add /dev, /etc, and a kernel.
-
-BusyBox was originally written to support the Debian Rescue/Install disks, but
-it also makes an excellent environment for any small or embedded system.
-
-As of version 0.20 there is now a version number. : ) Also as of version 0.20,
-BusyBox is now modularized to easily allow you to build only the components you
-need, thereby reducing binary size. To turn off unwanted BusyBox components,
-simply edit the file "Config.h" and comment out the components you do not need
-using C++ style (//) comments.
-
-After the build is complete, a busybox.links file is generated. This is
-used by 'make install' to create symlinks to the busybox binary for all
-compiled in functions. By default, 'make install' will place the symlink
-forest into `pwd`/_install unless you have defined the PREFIX environment
-variable (i.e., 'make PREFIX=/tmp/foo install')
+Please see the LICENSE file for details on copying and usage.
+Please refer to the INSTALL file for instructions on how to build.
+
+What is busybox:
+
+ BusyBox combines tiny versions of many common UNIX utilities into a single
+ small executable. It provides minimalist replacements for most of the
+ utilities you usually find in bzip2, coreutils, dhcp, diffutils, e2fsprogs,
+ file, findutils, gawk, grep, inetutils, less, modutils, net-tools, procps,
+ sed, shadow, sysklogd, sysvinit, tar, util-linux, and vim. The utilities
+ in BusyBox often have fewer options than their full-featured cousins;
+ however, the options that are included provide the expected functionality
+ and behave very much like their larger counterparts.
+
+ BusyBox has been written with size-optimization and limited resources in
+ mind, both to produce small binaries and to reduce run-time memory usage.
+ Busybox is also extremely modular so you can easily include or exclude
+ commands (or features) at compile time. This makes it easy to customize
+ embedded systems; to create a working system, just add /dev, /etc, and a
+ Linux kernel. Busybox (usually together with uClibc) has also been used as
+ a component of "thin client" desktop systems, live-CD distributions, rescue
+ disks, installers, and so on.
+
+ BusyBox provides a fairly complete POSIX environment for any small system,
+ both embedded environments and more full featured systems concerned about
+ space. Busybox is slowly working towards implementing the full Single Unix
+ Specification V3 (http://www.opengroup.org/onlinepubs/009695399/), but isn't
+ there yet (and for size reasons will probably support at most UTF-8 for
+ internationalization). We are also interested in passing the Linux Test
+ Project (http://ltp.sourceforge.net).
----------------
-
-Supported architectures:
- Busybox in general will build on any architecture supported by gcc. It has
- a few specialized features added for __sparc__ and __alpha__. insmod
- functionality is currently limited to x86, ARM, SH3/4, powerpc, m68k,
- and MIPS.
+Using busybox:
-Supported libcs:
+ BusyBox is extremely configurable. This allows you to include only the
+ components and options you need, thereby reducing binary size. Run 'make
+ config' or 'make menuconfig' to select the functionality that you wish to
+ enable. (See 'make help' for more commands.)
- glibc-2.0.x, glibc-2.1.x, glibc-2.2.x, Linux-libc5, uClibc. People
- are looking at newlib and diet-libc, but consider them unsupported,
- untested, or worse.
+ The behavior of busybox is determined by the name it's called under: as
+ "cp" it behaves like cp, as "sed" it behaves like sed, and so on. Called
+ as "busybox" it takes the second argument as the name of the applet to
+ run (I.E. "./busybox ls -l /proc").
-Supported kernels:
+ The "standalone shell" mode is an easy way to try out busybox; this is a
+ command shell that calls the builtin applets without needing them to be
+ installed in the path. (Note that this requires /proc to be mounted, if
+ testing from a boot floppy or in a chroot environment.)
- Full functionality requires Linux 2.0.x, 2.2.x, or 2.4.x. A large fraction
- of the code should run on just about anything.
+ The build automatically generates a file "busybox.links", which is used by
+ 'make install' to create symlinks to the BusyBox binary for all compiled in
+ commands. This uses the CONFIG_PREFIX environment variable to specify
+ where to install, and installs hardlinks or symlinks depending
+ on the configuration preferences. (You can also manually run
+ the install script at "applets/install.sh").
----------------
-Shells:
-
-lash is the very smallest shell (adds just 10k) and it is quite usable as
-a command prompt, but it is not suitable for any but the most trivial
-scripting (such as an initrd that calls insmod a few times) since it does
-not understand Bourne shell grammer. It does handle pipes, redirects, and
-job control though. Adding in command editing makes it a very nice
-lightweight command prompt.
-
-hush is also quite small (just 18k) and it has very complete Bourne shell
-grammer. It handles if/then/else/fi just fine, but doesn't handle loops
-like for/do/done or case/esac and such. It also currently has a problem
-with job control. Using hush is not yet recommended.
-
-msh: The minix shell (adds just 30k) is quite complete and handles things
-like for/do/done, case/esac and all the things you expect a Bourne shell to
-do. It is not always pedantically correct about Bourne shell grammer (try
-running the shell testscript "tests/sh.testcases" on it and compare vs bash)
-but for most things it works quite well. It also uses only vfork, so it can
-be used on uClinux systems. This was only recently added, so there is still
-room to shrink it further...
-
-ash: This adds about 60k in the default configuration and is the most
-complete and most pedantically correct shell included with busybox. This
-shell was also recently added, and several people (mainly Vladimir and Erik)
-have been working on it. There are a number of configurable things at the
-top of ash.c as well, so check those out if you want to tweak things.
+Downloading the current source code:
+
+ Source for the latest released version, as well as daily snapshots, can always
+ be downloaded from
+
+ http://busybox.net/downloads/
+
+ You can browse the up to the minute source code and change history online.
+
+ http://git.busybox.net/busybox/
+
+ Anonymous GIT access is available. For instructions, check out:
+
+ http://www.busybox.net/source.html
+
+ For those that are actively contributing and would like to check files in,
+ see:
+
+ http://busybox.net/developer.html
+
+ The developers also have a bug and patch tracking system
+ (https://bugs.busybox.net) although posting a bug/patch to the mailing list
+ is generally a faster way of getting it fixed, and the complete archive of
+ what happened is the subversion changelog.
+
+ Note: if you want to compile busybox in a busybox environment you must
+ select CONFIG_DESKTOP.
----------------
Getting help:
-When you find you need help, you can check out the BusyBox mailing list
-archives at http://busybox.net/lists/busybox/ or even join
-the mailing list if you are interested.
+ when you find you need help, you can check out the busybox mailing list
+ archives at http://busybox.net/lists/busybox/ or even join
+ the mailing list if you are interested.
----------------
Bugs:
-If you find bugs, please submit a bug report. Full instructions on how to
-report a bug are found at http://bugs.busybox.net/Reporting.html.
+ if you find bugs, please submit a detailed bug report to the busybox mailing
+ list at busybox@busybox.net. a well-written bug report should include a
+ transcript of a shell session that demonstrates the bad behavior and enables
+ anyone else to duplicate the bug on their own machine. the following is such
+ an example:
-For the impatient: To submit a bug, simply send an email describing the problem
-to submit@bugs.busybox.net. Bug reports should look something like this:
+ to: busybox@busybox.net
+ from: diligent@testing.linux.org
+ subject: /bin/date doesn't work
- To: submit@bugs.busybox.net
- From: diligent@testing.linux.org
- Subject: /bin/true doesn't work
+ package: busybox
+ version: 1.00
- Package: busybox
- Version: 0.51
+ when i execute busybox 'date' it produces unexpected results.
+ with gnu date i get the following output:
- When I invoke '/bin/true' it doesn't work. I expected it to return
- a "0" but it returned a "1" instead. Here is the transcript:
- $ /bin/true ; echo $?
- 1
- With GNU /bin/true, I get the following output:
- $ /bin/true ; echo $?
- 0
- I am using Debian 2.2r2, kernel version 2.2.18, and the latest
- uClibc from CVS. Thanks for the wonderful program!
- -Diligent
+ $ date
+ fri oct 8 14:19:41 mdt 2004
-Note the careful description and use of examples showing not only what BusyBox
-does, but also a counter example showing what an equivalent GNU app does. Bug
-reports lacking such detail may take a _long_ time to be fixed... Thanks for
-understanding.
+ but when i use busybox date i get this instead:
-----------------
+ $ date
+ illegal instruction
-FTP:
+ i am using debian unstable, kernel version 2.4.25-vrs2 on a netwinder,
+ and the latest uclibc from cvs.
-Source for the latest released version, as well as daily snapshots, can always
-be downloaded from
- http://busybox.net/downloads/
+ -diligent
-----------------
+ note the careful description and use of examples showing not only what
+ busybox does, but also a counter example showing what an equivalent app
+ does (or pointing to the text of a relevant standard). Bug reports lacking
+ such detail may never be fixed... Thanks for understanding.
-CVS:
+----------------
-BusyBox now has its own publicly browsable CVS tree at:
- http://busybox.net/cgi-bin/cvsweb/busybox/
+Portability:
+
+ Busybox is developed and tested on Linux 2.4 and 2.6 kernels, compiled
+ with gcc (the unit-at-a-time optimizations in version 3.4 and later are
+ worth upgrading to get, but older versions should work), and linked against
+ uClibc (0.9.27 or greater) or glibc (2.2 or greater). In such an
+ environment, the full set of busybox features should work, and if
+ anything doesn't we want to know about it so we can fix it.
+
+ There are many other environments out there, in which busybox may build
+ and run just fine. We just don't test them. Since busybox consists of a
+ large number of more or less independent applets, portability is a question
+ of which features work where. Some busybox applets (such as cat and rm) are
+ highly portable and likely to work just about anywhere, while others (such as
+ insmod and losetup) require recent Linux kernels with recent C libraries.
+
+ Earlier versions of Linux and glibc may or may not work, for any given
+ configuration. Linux 2.2 or earlier should mostly work (there's still
+ some support code in things like mount.c) but this is no longer regularly
+ tested, and inherently won't support certain features (such as long files
+ and --bind mounts). The same is true for glibc 2.0 and 2.1: expect a higher
+ testing and debugging burden using such old infrastructure. (The busybox
+ developers are not very interested in supporting these older versions, but
+ will probably accept small self-contained patches to fix simple problems.)
+
+ Some environments are not recommended. Early versions of uClibc were buggy
+ and missing many features: upgrade. Linking against libc5 or dietlibc is
+ not supported and not interesting to the busybox developers. (The first is
+ obsolete and has no known size or feature advantages over uClibc, the second
+ has known bugs that its developers have actively refused to fix.) Ancient
+ Linux kernels (2.0.x and earlier) are similarly uninteresting.
+
+ In theory it's possible to use Busybox under other operating systems (such as
+ MacOS X, Solaris, Cygwin, or the BSD Fork Du Jour). This generally involves
+ a different kernel and a different C library at the same time. While it
+ should be possible to port the majority of the code to work in one of
+ these environments, don't be suprised if it doesn't work out of the box. If
+ you're into that sort of thing, start small (selecting just a few applets)
+ and work your way up.
+
+ In 2005 Shaun Jackman has ported busybox to a combination of newlib
+ and libgloss, and some of his patches have been integrated.
+
+Supported hardware:
+
+ BusyBox in general will build on any architecture supported by gcc. We
+ support both 32 and 64 bit platforms, and both big and little endian
+ systems.
+
+ Under 2.4 Linux kernels, kernel module loading was implemented in a
+ platform-specific manner. Busybox's insmod utility has been reported to
+ work under ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC, S390,
+ SH3/4/5, Sparc, v850e, and x86_64. Anything else probably won't work.
+
+ The module loading mechanism for the 2.6 kernel is much more generic, and
+ we believe 2.6.x kernel module loading support should work on all
+ architectures supported by the kernel.
-Anonymous CVS access is available. For instructions, check out:
- http://busybox.net/cvs_anon.html
+----------------
-For those that are actively contributing there is even CVS write access:
- http://busybox.net/cvs_write.html
+Please feed suggestions, bug reports, insults, and bribes back to the busybox
+mailing list:
-----------------
+ busybox@busybox.net
-Please feed suggestions, bug reports, insults, and bribes back to:
- Erik Andersen
- <andersen@codepoet.org>
- <andersee@debian.org>
+and/or maintainer:
+ Denys Vlasenko
+ <vda.linux@googlemail.com>