From: Rob Landley Date: Sun, 14 Aug 2005 00:19:32 +0000 (-0000) Subject: A complete rewrite of the README. Probably broke stuff, but it's unlikely X-Git-Tag: 1_01~4 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=045dedad91253de03cfe4b68b763e5e94b913b81;p=oweals%2Fbusybox.git A complete rewrite of the README. Probably broke stuff, but it's unlikely to affect the compile, now is it? --- diff --git a/busybox/README b/busybox/README index bf2ae6f3f..df5c3cd9c 100644 --- a/busybox/README +++ b/busybox/README @@ -1,127 +1,196 @@ 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 GNU coreutils, util-linux, etc. 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 Linux kernel. -BusyBox provides a fairly complete POSIX environment for any small or embedded -system. - -BusyBox is extremely configurable. This allows you to include only the -components you need, thereby reducing binary size. Run 'make config' or -'make menuconfig' to 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 hard links, rather than symlinks, you can use -'make PREFIX=/tmp/foo install-hardlinks' instead. +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, file, findutils, gawk, grep, + inetutils, 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: +Using busybox: - BusyBox in general will build on any architecture supported by gcc. - Kernel module loading for 2.2 and 2.4 Linux kernels is currently - limited to ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC, - S390, SH3/4/5, Sparc, v850e, and x86_64 for 2.4.x kernels. For 2.6.x - kernels, kernel module loading support should work on all architectures. + 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. + 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 C Libraries: + 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.) - uClibc and glibc are supported. People have been looking at newlib and - dietlibc, but they are currently considered unsupported, untested, or - worse. Linux-libc5 is no longer supported -- you should probably use uClibc - instead if you want a small C library. + 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. Use the PREFIX environment variable to specify where to install + the busybox binary and symlink forest. (i.e., 'make PREFIX=/tmp/foo install', + or 'make PREFIX=/tmp/foo install-hardlinks' if you prefer hard links.) -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 support, say, FreeBSD or Solaris, or Mac OS X, or even Windows (if you - are into that sort of thing). +Downloading the current source code: ----------------- + Source for the latest released version, as well as daily snapshots, can always + be downloaded from -Getting help: + http://busybox.net/downloads/ -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. + You can browse the up to the minute source code and change history online + at: ----------------- +http://www.busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_00_stable/busybox/ -Bugs: + Anonymous SVN access is available. For instructions, check out: -If you find bugs, please submit a detailed bug report to the BusyBox mailing -list at busybox@mail.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: + http://busybox.net/subversion.html - To: busybox@mail.busybox.net - From: diligent@testing.linux.org - Subject: /bin/date doesn't work + For those that are actively contributing and would like to check files in, + see: - Package: BusyBox - Version: 1.00 + http://busybox.net/developer.html - When I execute BusyBox 'date' it produces unexpected results. - With GNU date I get the following output: + The developers also have a bug and patch tracking system + (http://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. - $ date - Fri Oct 8 14:19:41 MDT 2004 +---------------- - But when I use BusyBox date I get this instead: +getting help: - $ date - illegal instruction + 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. - I am using Debian unstable, kernel version 2.4.25-vrs2 on a Netwinder, - and the latest uClibc from CVS. Thanks for the wonderful program! +---------------- - -Diligent +bugs: -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. + 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@mail.busybox.net + from: diligent@testing.linux.org + subject: /bin/date doesn't work -Downloads: + package: busybox + version: 1.00 -Source for the latest released version, as well as daily snapshots, can always -be downloaded from - http://busybox.net/downloads/ + when i execute busybox 'date' it produces unexpected results. + with gnu date i get the following output: ----------------- + $ date + fri oct 8 14:19:41 mdt 2004 + + but when i use busybox date i get this instead: + + $ date + illegal instruction -CVS: + i am using debian unstable, kernel version 2.4.25-vrs2 on a netwinder, + and the latest uclibc from cvs. thanks for the wonderful program! -BusyBox now has its own publicly browsable CVS tree at: - http://busybox.net/cgi-bin/cvsweb/busybox/ + -diligent -Anonymous CVS access is available. For instructions, check out: - http://busybox.net/cvs_anon.html + 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. -For those that are actively contributing there is even CVS write access: - http://busybox.net/cvs_write.html +---------------- + +Portability: + + Busybox is developed and tested on Linux 2.4 and 2.6 kernels, linked + against uClibc (0.9.27 or greater) and 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). Note that + the 2.6 kernel can be trimmed down considerably with the aid of Matt + Mackall's -tiny work (http://www.selenic.com/tiny-about/). + + 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) are only + likely to work under fairly 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, 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 can probably be talked into accepting small 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. + + Shaun Jackman has recently (2005) ported busybox to a combination of newlib + and libgloss, and some of his patches have been integrated. This platform + may join glibc/uclibc and Linux as a supported combination with the 1.1 + release, but is not supported in 1.0. + +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. ---------------- -Please feed suggestions, bug reports, insults, and bribes back to: +Please feed suggestions, bug reports, insults, and bribes back to the busybox +maintainer: Erik Andersen -