Contents of /tags/mkinitrd-6_5_2/busybox/README
Parent Directory | Revision Log
Revision 1522 -
(show annotations)
(download)
Wed Sep 7 18:40:16 2011 UTC (13 years ago) by niro
File size: 8768 byte(s)
Wed Sep 7 18:40:16 2011 UTC (13 years ago) by niro
File size: 8768 byte(s)
tagged 'mkinitrd-6_5_2'
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 | What is busybox: |
5 | |
6 | BusyBox combines tiny versions of many common UNIX utilities into a single |
7 | small executable. It provides minimalist replacements for most of the |
8 | utilities you usually find in bzip2, coreutils, dhcp, diffutils, e2fsprogs, |
9 | file, findutils, gawk, grep, inetutils, less, modutils, net-tools, procps, |
10 | sed, shadow, sysklogd, sysvinit, tar, util-linux, and vim. The utilities |
11 | in BusyBox often have fewer options than their full-featured cousins; |
12 | however, the options that are included provide the expected functionality |
13 | and behave very much like their larger counterparts. |
14 | |
15 | BusyBox has been written with size-optimization and limited resources in |
16 | mind, both to produce small binaries and to reduce run-time memory usage. |
17 | Busybox is also extremely modular so you can easily include or exclude |
18 | commands (or features) at compile time. This makes it easy to customize |
19 | embedded systems; to create a working system, just add /dev, /etc, and a |
20 | Linux kernel. Busybox (usually together with uClibc) has also been used as |
21 | a component of "thin client" desktop systems, live-CD distributions, rescue |
22 | disks, installers, and so on. |
23 | |
24 | BusyBox provides a fairly complete POSIX environment for any small system, |
25 | both embedded environments and more full featured systems concerned about |
26 | space. Busybox is slowly working towards implementing the full Single Unix |
27 | Specification V3 (http://www.opengroup.org/onlinepubs/009695399/), but isn't |
28 | there yet (and for size reasons will probably support at most UTF-8 for |
29 | internationalization). We are also interested in passing the Linux Test |
30 | Project (http://ltp.sourceforge.net). |
31 | |
32 | ---------------- |
33 | |
34 | Using busybox: |
35 | |
36 | BusyBox is extremely configurable. This allows you to include only the |
37 | components and options you need, thereby reducing binary size. Run 'make |
38 | config' or 'make menuconfig' to select the functionality that you wish to |
39 | enable. (See 'make help' for more commands.) |
40 | |
41 | The behavior of busybox is determined by the name it's called under: as |
42 | "cp" it behaves like cp, as "sed" it behaves like sed, and so on. Called |
43 | as "busybox" it takes the second argument as the name of the applet to |
44 | run (I.E. "./busybox ls -l /proc"). |
45 | |
46 | The "standalone shell" mode is an easy way to try out busybox; this is a |
47 | command shell that calls the builtin applets without needing them to be |
48 | installed in the path. (Note that this requires /proc to be mounted, if |
49 | testing from a boot floppy or in a chroot environment.) |
50 | |
51 | The build automatically generates a file "busybox.links", which is used by |
52 | 'make install' to create symlinks to the BusyBox binary for all compiled in |
53 | commands. This uses the CONFIG_PREFIX environment variable to specify |
54 | where to install, and installs hardlinks or symlinks depending |
55 | on the configuration preferences. (You can also manually run |
56 | the install script at "applets/install.sh"). |
57 | |
58 | ---------------- |
59 | |
60 | Downloading the current source code: |
61 | |
62 | Source for the latest released version, as well as daily snapshots, can always |
63 | be downloaded from |
64 | |
65 | http://busybox.net/downloads/ |
66 | |
67 | You can browse the up to the minute source code and change history online. |
68 | |
69 | http://git.busybox.net/busybox/ |
70 | |
71 | Anonymous GIT access is available. For instructions, check out: |
72 | |
73 | http://www.busybox.net/source.html |
74 | |
75 | For those that are actively contributing and would like to check files in, |
76 | see: |
77 | |
78 | http://busybox.net/developer.html |
79 | |
80 | The developers also have a bug and patch tracking system |
81 | (https://bugs.busybox.net) although posting a bug/patch to the mailing list |
82 | is generally a faster way of getting it fixed, and the complete archive of |
83 | what happened is the subversion changelog. |
84 | |
85 | Note: if you want to compile busybox in a busybox environment you must |
86 | select CONFIG_DESKTOP. |
87 | |
88 | ---------------- |
89 | |
90 | Getting help: |
91 | |
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. |
95 | |
96 | ---------------- |
97 | |
98 | Bugs: |
99 | |
100 | if you find bugs, please submit a detailed bug report to the busybox mailing |
101 | list at busybox@busybox.net. a well-written bug report should include a |
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: |
105 | |
106 | to: busybox@busybox.net |
107 | from: diligent@testing.linux.org |
108 | subject: /bin/date doesn't work |
109 | |
110 | package: busybox |
111 | version: 1.00 |
112 | |
113 | when i execute busybox 'date' it produces unexpected results. |
114 | with gnu date i get the following output: |
115 | |
116 | $ date |
117 | fri oct 8 14:19:41 mdt 2004 |
118 | |
119 | but when i use busybox date i get this instead: |
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. |
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 | In 2005 Shaun Jackman has ported busybox to a combination of newlib |
177 | and libgloss, and some of his patches have been integrated. |
178 | |
179 | Supported hardware: |
180 | |
181 | BusyBox in general will build on any architecture supported by gcc. We |
182 | support both 32 and 64 bit platforms, and both big and little endian |
183 | systems. |
184 | |
185 | Under 2.4 Linux kernels, kernel module loading was implemented in a |
186 | platform-specific manner. Busybox's insmod utility has been reported to |
187 | work under ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC, S390, |
188 | SH3/4/5, Sparc, v850e, and x86_64. Anything else probably won't work. |
189 | |
190 | The module loading mechanism for the 2.6 kernel is much more generic, and |
191 | we believe 2.6.x kernel module loading support should work on all |
192 | architectures supported by the kernel. |
193 | |
194 | ---------------- |
195 | |
196 | Please feed suggestions, bug reports, insults, and bribes back to the busybox |
197 | mailing list: |
198 | |
199 | busybox@busybox.net |
200 | |
201 | and/or maintainer: |
202 | |
203 | Denys Vlasenko |
204 | <vda.linux@googlemail.com> |