Annotation of /tags/mkinitrd-6_3_2/busybox/README
Parent Directory | Revision Log
Revision 1164 -
(hide annotations)
(download)
Tue Sep 14 20:33:28 2010 UTC (14 years ago) by niro
File size: 8768 byte(s)
Tue Sep 14 20:33:28 2010 UTC (14 years ago) by niro
File size: 8768 byte(s)
tagged 'mkinitrd-6_3_2'
1 | niro | 532 | 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 | niro | 816 | 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 | niro | 532 | |
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 | niro | 1123 | http://git.busybox.net/busybox/ |
70 | niro | 532 | |
71 | niro | 984 | Anonymous GIT access is available. For instructions, check out: |
72 | niro | 532 | |
73 | niro | 984 | http://www.busybox.net/source.html |
74 | niro | 532 | |
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 | niro | 984 | (https://bugs.busybox.net) although posting a bug/patch to the mailing list |
82 | niro | 532 | is generally a faster way of getting it fixed, and the complete archive of |
83 | what happened is the subversion changelog. | ||
84 | |||
85 | niro | 816 | Note: if you want to compile busybox in a busybox environment you must |
86 | niro | 1123 | select CONFIG_DESKTOP. |
87 | niro | 816 | |
88 | niro | 532 | ---------------- |
89 | |||
90 | niro | 1123 | Getting help: |
91 | niro | 532 | |
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 | niro | 1123 | Bugs: |
99 | niro | 532 | |
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 | niro | 816 | and the latest uclibc from cvs. |
126 | niro | 532 | |
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 | niro | 816 | In 2005 Shaun Jackman has ported busybox to a combination of newlib |
177 | and libgloss, and some of his patches have been integrated. | ||
178 | niro | 532 | |
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 | niro | 1123 | mailing list: |
198 | |||
199 | busybox@busybox.net | ||
200 | |||
201 | and/or maintainer: | ||
202 | |||
203 | niro | 816 | Denys Vlasenko |
204 | niro | 1123 | <vda.linux@googlemail.com> |