X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=README;h=ceda825df36b3cd9c514c19e06945dd363887b1d;hb=a1ed06b04739d85389fe23e78e97556864b77c64;hp=118e14590d35e6fd34595b338a5b3bac2f4c33e4;hpb=61677feff7f549a48267c2c0c50a7420de6e2599;p=oweals%2Fbusybox.git diff --git a/README b/README index 118e14590..ceda825df 100644 --- a/README +++ b/README @@ -1,30 +1,159 @@ -Please see the LICENSE file for copyright information. - -BusyBox is a suite of "tiny" Unix utilities in a multi-call binary. It -provides a pretty complete POSIX environment in a very small package. -Just add a kernel, "ash" (Keith Almquists tiny Bourne shell clone), and -an editor such as "elvis-tiny" or "ae", and you have a working system. -Busybox was begun 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 a version number. : ) Also as of version 0.20, BB -is now modularized to easily allow you to build only the BB parts you need, -thereby reducing binary size. To turn off unwanted Busybox components, simply -edit the file busybox.def.h and comment out the parts you do not need using C++ -style (//) comments. - -After the build is complete a busybox.links file is generated which is -then 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. + +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 was originally written to support the Debian Rescue/Install disks, but +it also makes an excellent environment for any small or embedded system. + +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. + +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. Run 'make config' or 'make menuconfig' +for select the functionality that you wish to enable. + +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') + +If you wish to install hardlinks, rather than symlinks, you can use +'make install-hardlinks' instead. + +---------------- + +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, + MIPS, and v850e. + +Supported libcs: + + glibc-2.0.x, glibc-2.1.x, glibc-2.2.x, glibc-2.3.x, uClibc. People + are looking at newlib and diet-libc, but consider them unsupported, + untested, or worse. Linux-libc5 is no longer supported -- you + should probably use uClibc instead if you want a small C library. + +Supported kernels: + + Full functionality requires Linux 2.2.x or better. A large fraction of the + code should run on just about anything. While the current code is fairly + Linux specific, it should be fairly easy to port the majority of the code + to, say, FreeBSD or Solaris, or MacOsX, or even Windows (if you are into that + sortof thing). + +---------------- + +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. + +---------------- + +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. + +---------------- + +Bugs: + +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: + + To: busybox@busybox.net + From: diligent@testing.linux.org + Subject: /bin/date doesn't work + + Package: busybox + Version: 1.00 + + When I execute Busybox 'date' it produces unexpected results. + With GNU date I get the following output: + + $ date + Wed Mar 21 14:19:41 MST 2001 + + But when I use BusyBox date I get this instead: + + $ date + llegal instruction + + I am using Debian unstable, kernel version 2.4.19-rmk1 on an Netwinder, + and the latest uClibc from CVS. Thanks for the wonderful program! + + -Diligent + +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 never be fixed... Thanks for understanding. + +---------------- + +FTP: + +Source for the latest released version, as well as daily snapshots, can always +be downloaded from + http://busybox.net/downloads/ + +---------------- + +CVS: + +BusyBox now has its own publicly browsable CVS tree at: + http://busybox.net/cgi-bin/cvsweb/busybox/ + +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: Erik Andersen - - - - -Many thanks to go to Lineo for paying me to work on busybox. - + +