diff options
author | Rob Landley <rob@landley.net> | 2005-10-09 18:20:54 +0000 |
---|---|---|
committer | Rob Landley <rob@landley.net> | 2005-10-09 18:20:54 +0000 |
commit | d27d3be6cdf177b8b75e5159f246a87a41b7276a (patch) | |
tree | 5a76ab5cdd8f695a542fcc9241d239110c1314d0 /README | |
parent | 61e45dbb2f55dfcebf874c6ec3d41f50b284590f (diff) | |
download | busybox-w32-d27d3be6cdf177b8b75e5159f246a87a41b7276a.tar.gz busybox-w32-d27d3be6cdf177b8b75e5159f246a87a41b7276a.tar.bz2 busybox-w32-d27d3be6cdf177b8b75e5159f246a87a41b7276a.zip |
The readme in 1.0 is more up to date than the 1.1 version...
Diffstat (limited to 'README')
-rw-r--r-- | README | 244 |
1 files changed, 163 insertions, 81 deletions
@@ -1,119 +1,201 @@ | |||
1 | Please see the LICENSE file for details on copying and usage. | 1 | Please see the LICENSE file for details on copying and usage. |
2 | Please refer to the INSTALL file for instructions on how to build. | ||
3 | |||
4 | BusyBox combines tiny versions of many common UNIX utilities into a single | ||
5 | small executable. It provides minimalist replacements for most of the utilities | ||
6 | you usually find in GNU coreutils, util-linux, etc. The utilities in BusyBox | ||
7 | generally have fewer options than their full-featured GNU cousins; however, the | ||
8 | options that are included provide the expected functionality and behave very | ||
9 | much like their GNU counterparts. | ||
10 | |||
11 | BusyBox has been written with size-optimization and limited resources in mind. | ||
12 | It is also extremely modular so you can easily include or exclude commands (or | ||
13 | features) at compile time. This makes it easy to customize your embedded | ||
14 | systems. To create a working system, just add /dev, /etc, and a Linux kernel. | ||
15 | BusyBox provides a fairly complete POSIX environment for any small or embedded | ||
16 | system. | ||
17 | |||
18 | BusyBox is extremely configurable. This allows you to include only the | ||
19 | components you need, thereby reducing binary size. See the file INSTALL | ||
20 | for details. | ||
21 | 2 | ||
22 | ---------------- | 3 | What is busybox: |
23 | 4 | ||
24 | Supported architectures: | 5 | BusyBox combines tiny versions of many common UNIX utilities into a single |
6 | small executable. It provides minimalist replacements for most of the | ||
7 | utilities you usually find in bzip2, coreutils, file, findutils, gawk, grep, | ||
8 | inetutils, modutils, net-tools, procps, sed, shadow, sysklogd, sysvinit, tar, | ||
9 | util-linux, and vim. The utilities in BusyBox often have fewer options than | ||
10 | their full-featured cousins; however, the options that are included provide | ||
11 | the expected functionality and behave very much like their larger | ||
12 | counterparts. | ||
13 | |||
14 | BusyBox has been written with size-optimization and limited resources in | ||
15 | mind, both to produce small binaries and to reduce run-time memory usage. | ||
16 | Busybox is also extremely modular so you can easily include or exclude | ||
17 | commands (or features) at compile time. This makes it easy to customize | ||
18 | embedded systems; to create a working system, just add /dev, /etc, and a | ||
19 | Linux kernel. Busybox (usually together with uClibc) has also been used as | ||
20 | a component of "thin client" desktop systems, live-CD distributions, rescue | ||
21 | disks, installers, and so on. | ||
22 | |||
23 | BusyBox provides a fairly complete POSIX environment for any small system, | ||
24 | both embedded environments and more full featured systems concerned about | ||
25 | space. Busybox is slowly working towards implementing the full Single Unix | ||
26 | Specification V3 (http://www.opengroup.org/onlinepubs/009695399/), but isn't | ||
27 | there yet (and for size reasons will probably support at most UTF-8 for | ||
28 | internationalization). We are also interested in passing the Linux Test | ||
29 | Project (http://ltp.sourceforge.net). | ||
25 | 30 | ||
26 | BusyBox in general will build on any architecture supported by gcc. | 31 | ---------------- |
27 | Kernel module loading for 2.2 and 2.4 Linux kernels is currently | ||
28 | limited to ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC, | ||
29 | S390, SH3/4/5, Sparc, v850e, and x86_64 for 2.4.x kernels. For 2.6.x | ||
30 | kernels, kernel module loading support should work on all architectures. | ||
31 | 32 | ||
33 | Using busybox: | ||
32 | 34 | ||
33 | Supported C Libraries: | 35 | BusyBox is extremely configurable. This allows you to include only the |
36 | components and options you need, thereby reducing binary size. Run 'make | ||
37 | config' or 'make menuconfig' to select the functionality that you wish to | ||
38 | enable. (See 'make help' for more commands.) | ||
34 | 39 | ||
35 | uClibc and glibc are supported. People have been looking at newlib and | 40 | The behavior of busybox is determined by the name it's called under: as |
36 | dietlibc, but they are currently considered unsupported, untested, or | 41 | "cp" it behaves like cp, as "sed" it behaves like sed, and so on. Called |
37 | worse. Linux-libc5 is no longer supported -- you should probably use uClibc | 42 | as "busybox" it takes the second argument as the name of the applet to |
38 | instead if you want a small C library. | 43 | run (I.E. "./busybox ls -l /proc"). |
39 | 44 | ||
40 | Supported kernels: | 45 | The "standalone shell" mode is an easy way to try out busybox; this is a |
46 | command shell that calls the builtin applets without needing them to be | ||
47 | installed in the path. (Note that this requires /proc to be mounted, if | ||
48 | testing from a boot floppy or in a chroot environment.) | ||
41 | 49 | ||
42 | Full functionality requires Linux 2.2.x or better. A large fraction of the | 50 | The build automatically generates a file "busybox.links", which is used by |
43 | code should run on just about anything. While the current code is fairly | 51 | 'make install' to create symlinks to the BusyBox binary for all compiled in |
44 | Linux specific, it should be fairly easy to port the majority of the code | 52 | commands. Use the PREFIX environment variable to specify where to install |
45 | to support, say, FreeBSD or Solaris, or Mac OS X, or even Windows (if you | 53 | the busybox binary and symlink forest. (i.e., 'make PREFIX=/tmp/foo install', |
46 | are into that sort of thing). | 54 | or 'make PREFIX=/tmp/foo install-hardlinks' if you prefer hard links.) |
47 | 55 | ||
48 | ---------------- | 56 | ---------------- |
49 | 57 | ||
50 | Getting help: | 58 | Downloading the current source code: |
51 | 59 | ||
52 | When you find you need help, you can check out the BusyBox mailing list | 60 | Source for the latest released version, as well as daily snapshots, can always |
53 | archives at http://busybox.net/lists/busybox/ or even join | 61 | be downloaded from |
54 | the mailing list if you are interested. | ||
55 | 62 | ||
56 | ---------------- | 63 | http://busybox.net/downloads/ |
57 | 64 | ||
58 | Bugs: | 65 | You can browse the up to the minute source code and change history online. |
66 | The "stable" series is at: | ||
59 | 67 | ||
60 | If you find bugs, please submit a detailed bug report to the BusyBox mailing | 68 | http://www.busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_00_stable/busybox/ |
61 | list at busybox@mail.busybox.net. A well-written bug report should include a | ||
62 | transcript of a shell session that demonstrates the bad behavior and enables | ||
63 | anyone else to duplicate the bug on their own machine. The following is such | ||
64 | an example: | ||
65 | 69 | ||
66 | To: busybox@mail.busybox.net | 70 | And the development series is at: |
67 | From: diligent@testing.linux.org | ||
68 | Subject: /bin/date doesn't work | ||
69 | 71 | ||
70 | Package: BusyBox | 72 | http://www.busybox.net/cgi-bin/viewcvs.cgi/trunk/busybox/ |
71 | Version: 1.00 | ||
72 | 73 | ||
73 | When I execute BusyBox 'date' it produces unexpected results. | 74 | Anonymous SVN access is available. For instructions, check out: |
74 | With GNU date I get the following output: | ||
75 | 75 | ||
76 | $ date | 76 | http://busybox.net/subversion.html |
77 | Fri Oct 8 14:19:41 MDT 2004 | ||
78 | 77 | ||
79 | But when I use BusyBox date I get this instead: | 78 | For those that are actively contributing and would like to check files in, |
79 | see: | ||
80 | 80 | ||
81 | $ date | 81 | http://busybox.net/developer.html |
82 | illegal instruction | ||
83 | 82 | ||
84 | I am using Debian unstable, kernel version 2.4.25-vrs2 on a Netwinder, | 83 | The developers also have a bug and patch tracking system |
85 | and the latest uClibc from CVS. Thanks for the wonderful program! | 84 | (http://bugs.busybox.net) although posting a bug/patch to the mailing list |
85 | is generally a faster way of getting it fixed, and the complete archive of | ||
86 | what happened is the subversion changelog. | ||
86 | 87 | ||
87 | -Diligent | 88 | ---------------- |
88 | 89 | ||
89 | Note the careful description and use of examples showing not only what BusyBox | 90 | getting help: |
90 | does, but also a counter example showing what an equivalent GNU app does. Bug | 91 | |
91 | reports lacking such detail may never be fixed... Thanks for understanding. | 92 | when you find you need help, you can check out the busybox mailing list |
93 | archives at http://busybox.net/lists/busybox/ or even join | ||
94 | the mailing list if you are interested. | ||
92 | 95 | ||
93 | ---------------- | 96 | ---------------- |
94 | 97 | ||
95 | Downloads: | 98 | bugs: |
96 | 99 | ||
97 | Source for the latest released version, as well as daily snapshots, can always | 100 | if you find bugs, please submit a detailed bug report to the busybox mailing |
98 | be downloaded from | 101 | list at busybox@busybox.net. a well-written bug report should include a |
99 | http://busybox.net/downloads/ | 102 | transcript of a shell session that demonstrates the bad behavior and enables |
103 | anyone else to duplicate the bug on their own machine. the following is such | ||
104 | an example: | ||
100 | 105 | ||
101 | ---------------- | 106 | to: busybox@busybox.net |
107 | from: diligent@testing.linux.org | ||
108 | subject: /bin/date doesn't work | ||
102 | 109 | ||
103 | CVS: | 110 | package: busybox |
111 | version: 1.00 | ||
104 | 112 | ||
105 | BusyBox now has its own publicly browsable SVN tree at: | 113 | when i execute busybox 'date' it produces unexpected results. |
106 | http://busybox.net/cgi-bin/viewcvs.cgi/trunk/busybox/ | 114 | with gnu date i get the following output: |
107 | 115 | ||
108 | Anonymous SVN access is available. For instructions, check out: | 116 | $ date |
109 | http://busybox.net/subversion.html | 117 | fri oct 8 14:19:41 mdt 2004 |
110 | 118 | ||
111 | For those that are actively contributing there is even SVN write access: | 119 | but when i use busybox date i get this instead: |
112 | http://busybox.net/developer.html | 120 | |
121 | $ date | ||
122 | illegal instruction | ||
123 | |||
124 | i am using debian unstable, kernel version 2.4.25-vrs2 on a netwinder, | ||
125 | and the latest uclibc from cvs. thanks for the wonderful program! | ||
126 | |||
127 | -diligent | ||
128 | |||
129 | note the careful description and use of examples showing not only what | ||
130 | busybox does, but also a counter example showing what an equivalent app | ||
131 | does (or pointing to the text of a relevant standard). Bug reports lacking | ||
132 | such detail may never be fixed... Thanks for understanding. | ||
133 | |||
134 | ---------------- | ||
135 | |||
136 | Portability: | ||
137 | |||
138 | Busybox is developed and tested on Linux 2.4 and 2.6 kernels, compiled | ||
139 | with gcc (the unit-at-a-time optimizations in version 3.4 and later are | ||
140 | worth upgrading to get, but older versions should work), and linked against | ||
141 | uClibc (0.9.27 or greater) or glibc (2.2 or greater). In such an | ||
142 | environment, the full set of busybox features should work, and if | ||
143 | anything doesn't we want to know about it so we can fix it. | ||
144 | |||
145 | There are many other environments out there, in which busybox may build | ||
146 | and run just fine. We just don't test them. Since busybox consists of a | ||
147 | large number of more or less independent applets, portability is a question | ||
148 | of which features work where. Some busybox applets (such as cat and rm) are | ||
149 | highly portable and likely to work just about anywhere, while others (such as | ||
150 | insmod and losetup) require recent Linux kernels with recent C libraries. | ||
151 | |||
152 | Earlier versions of Linux and glibc may or may not work, for any given | ||
153 | configuration. Linux 2.2 or earlier should mostly work (there's still | ||
154 | some support code in things like mount.c) but this is no longer regularly | ||
155 | tested, and inherently won't support certain features (such as long files | ||
156 | and --bind mounts). The same is true for glibc 2.0 and 2.1: expect a higher | ||
157 | testing and debugging burden using such old infrastructure. (The busybox | ||
158 | developers are not very interested in supporting these older versions, but | ||
159 | will probably accept small self-contained patches to fix simple problems.) | ||
160 | |||
161 | Some environments are not recommended. Early versions of uClibc were buggy | ||
162 | and missing many features: upgrade. Linking against libc5 or dietlibc is | ||
163 | not supported and not interesting to the busybox developers. (The first is | ||
164 | obsolete and has no known size or feature advantages over uClibc, the second | ||
165 | has known bugs that its developers have actively refused to fix.) Ancient | ||
166 | Linux kernels (2.0.x and earlier) are similarly uninteresting. | ||
167 | |||
168 | In theory it's possible to use Busybox under other operating systems (such as | ||
169 | MacOS X, Solaris, Cygwin, or the BSD Fork Du Jour). This generally involves | ||
170 | a different kernel and a different C library at the same time. While it | ||
171 | should be possible to port the majority of the code to work in one of | ||
172 | these environments, don't be suprised if it doesn't work out of the box. If | ||
173 | you're into that sort of thing, start small (selecting just a few applets) | ||
174 | and work your way up. | ||
175 | |||
176 | Shaun Jackman has recently (2005) ported busybox to a combination of newlib | ||
177 | and libgloss, and some of his patches have been integrated. This platform | ||
178 | may join glibc/uclibc and Linux as a supported combination with the 1.1 | ||
179 | release, but is not supported in 1.0. | ||
180 | |||
181 | Supported hardware: | ||
182 | |||
183 | BusyBox in general will build on any architecture supported by gcc. We | ||
184 | support both 32 and 64 bit platforms, and both big and little endian | ||
185 | systems. | ||
186 | |||
187 | Under 2.4 Linux kernels, kernel module loading was implemented in a | ||
188 | platform-specific manner. Busybox's insmod utility has been reported to | ||
189 | work under ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC, S390, | ||
190 | SH3/4/5, Sparc, v850e, and x86_64. Anything else probably won't work. | ||
191 | |||
192 | The module loading mechanism for the 2.6 kernel is much more generic, and | ||
193 | we believe 2.6.x kernel module loading support should work on all | ||
194 | architectures supported by the kernel. | ||
113 | 195 | ||
114 | ---------------- | 196 | ---------------- |
115 | 197 | ||
116 | Please feed suggestions, bug reports, insults, and bribes back to: | 198 | Please feed suggestions, bug reports, insults, and bribes back to the busybox |
199 | maintainer: | ||
117 | Erik Andersen | 200 | Erik Andersen |
118 | <andersen@codepoet.org> | 201 | <andersen@codepoet.org> |
119 | |||