blob: ebdda736c10c0e0ad5ec18d7e6968f0ceee5df8e
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 | ---------------- |
5 | Note about this Android Variant : |
6 | |
7 | WARNING : THIS IS A BIONIC VERSION OF BUSYBOX, DO NOT USE "make" IN THIS TREE |
8 | |
9 | This tree has multiple configurations (busybox and recovery lib), |
10 | |
11 | - lunch your device to prepare the environment |
12 | - edit the wanted config profile (ie busybox-full.config) |
13 | |
14 | - type "mma" in external/busybox to build with the dependencies |
15 | |
16 | Finally copy $OUT/obj/busybox/full/.config to the source tree without |
17 | the CONFIG_CROSS_COMPILER_PREFIX line! (to stay compatible with x86 targets) |
18 | |
19 | bb_obj=$OUT/obj/busybox/full |
20 | cat $bb_obj/.config | grep -v CROSS_COMPILER_ > busybox-full.config |
21 | |
22 | bb_obj=$OUT/obj/busybox/minimal |
23 | cat $bb_obj/.config | grep -v CROSS_COMPILER_ > busybox-minimal.config |
24 | |
25 | If you add or remove some applets, |
26 | please also update busybox-<profile>.links and busybox-<profile>.sources |
27 | |
28 | ---------------- |
29 | |
30 | What is busybox: |
31 | |
32 | BusyBox combines tiny versions of many common UNIX utilities into a single |
33 | small executable. It provides minimalist replacements for most of the |
34 | utilities you usually find in bzip2, coreutils, dhcp, diffutils, e2fsprogs, |
35 | file, findutils, gawk, grep, inetutils, less, modutils, net-tools, procps, |
36 | sed, shadow, sysklogd, sysvinit, tar, util-linux, and vim. The utilities |
37 | in BusyBox often have fewer options than their full-featured cousins; |
38 | however, the options that are included provide the expected functionality |
39 | and behave very much like their larger counterparts. |
40 | |
41 | BusyBox has been written with size-optimization and limited resources in |
42 | mind, both to produce small binaries and to reduce run-time memory usage. |
43 | Busybox is also extremely modular so you can easily include or exclude |
44 | commands (or features) at compile time. This makes it easy to customize |
45 | embedded systems; to create a working system, just add /dev, /etc, and a |
46 | Linux kernel. Busybox (usually together with uClibc) has also been used as |
47 | a component of "thin client" desktop systems, live-CD distributions, rescue |
48 | disks, installers, and so on. |
49 | |
50 | BusyBox provides a fairly complete POSIX environment for any small system, |
51 | both embedded environments and more full featured systems concerned about |
52 | space. Busybox is slowly working towards implementing the full Single Unix |
53 | Specification V3 (http://www.opengroup.org/onlinepubs/009695399/), but isn't |
54 | there yet (and for size reasons will probably support at most UTF-8 for |
55 | internationalization). We are also interested in passing the Linux Test |
56 | Project (http://ltp.sourceforge.net). |
57 | |
58 | ---------------- |
59 | |
60 | Using busybox: |
61 | |
62 | BusyBox is extremely configurable. This allows you to include only the |
63 | components and options you need, thereby reducing binary size. Run 'make |
64 | config' or 'make menuconfig' to select the functionality that you wish to |
65 | enable. (See 'make help' for more commands.) |
66 | |
67 | The behavior of busybox is determined by the name it's called under: as |
68 | "cp" it behaves like cp, as "sed" it behaves like sed, and so on. Called |
69 | as "busybox" it takes the second argument as the name of the applet to |
70 | run (I.E. "./busybox ls -l /proc"). |
71 | |
72 | The "standalone shell" mode is an easy way to try out busybox; this is a |
73 | command shell that calls the built-in applets without needing them to be |
74 | installed in the path. (Note that this requires /proc to be mounted, if |
75 | testing from a boot floppy or in a chroot environment.) |
76 | |
77 | The build automatically generates a file "busybox.links", which is used by |
78 | 'make install' to create symlinks to the BusyBox binary for all compiled in |
79 | commands. This uses the CONFIG_PREFIX environment variable to specify |
80 | where to install, and installs hardlinks or symlinks depending |
81 | on the configuration preferences. (You can also manually run |
82 | the install script at "applets/install.sh"). |
83 | |
84 | ---------------- |
85 | |
86 | Downloading the current source code: |
87 | |
88 | Source for the latest released version, as well as daily snapshots, can always |
89 | be downloaded from |
90 | |
91 | http://busybox.net/downloads/ |
92 | |
93 | You can browse the up to the minute source code and change history online. |
94 | |
95 | http://git.busybox.net/busybox/ |
96 | |
97 | Anonymous GIT access is available. For instructions, check out: |
98 | |
99 | http://www.busybox.net/source.html |
100 | |
101 | For those that are actively contributing and would like to check files in, |
102 | see: |
103 | |
104 | http://busybox.net/developer.html |
105 | |
106 | The developers also have a bug and patch tracking system |
107 | (https://bugs.busybox.net) although posting a bug/patch to the mailing list |
108 | is generally a faster way of getting it fixed, and the complete archive of |
109 | what happened is the git changelog. |
110 | |
111 | Note: if you want to compile busybox in a busybox environment you must |
112 | select CONFIG_DESKTOP. |
113 | |
114 | ---------------- |
115 | |
116 | Getting help: |
117 | |
118 | when you find you need help, you can check out the busybox mailing list |
119 | archives at http://busybox.net/lists/busybox/ or even join |
120 | the mailing list if you are interested. |
121 | |
122 | ---------------- |
123 | |
124 | Bugs: |
125 | |
126 | if you find bugs, please submit a detailed bug report to the busybox mailing |
127 | list at busybox@busybox.net. a well-written bug report should include a |
128 | transcript of a shell session that demonstrates the bad behavior and enables |
129 | anyone else to duplicate the bug on their own machine. the following is such |
130 | an example: |
131 | |
132 | to: busybox@busybox.net |
133 | from: diligent@testing.linux.org |
134 | subject: /bin/date doesn't work |
135 | |
136 | package: busybox |
137 | version: 1.00 |
138 | |
139 | when i execute busybox 'date' it produces unexpected results. |
140 | with gnu date i get the following output: |
141 | |
142 | $ date |
143 | fri oct 8 14:19:41 mdt 2004 |
144 | |
145 | but when i use busybox date i get this instead: |
146 | |
147 | $ date |
148 | illegal instruction |
149 | |
150 | i am using debian unstable, kernel version 2.4.25-vrs2 on a netwinder, |
151 | and the latest uclibc from cvs. |
152 | |
153 | -diligent |
154 | |
155 | note the careful description and use of examples showing not only what |
156 | busybox does, but also a counter example showing what an equivalent app |
157 | does (or pointing to the text of a relevant standard). Bug reports lacking |
158 | such detail may never be fixed... Thanks for understanding. |
159 | |
160 | ---------------- |
161 | |
162 | Portability: |
163 | |
164 | Busybox is developed and tested on Linux 2.4 and 2.6 kernels, compiled |
165 | with gcc (the unit-at-a-time optimizations in version 3.4 and later are |
166 | worth upgrading to get, but older versions should work), and linked against |
167 | uClibc (0.9.27 or greater) or glibc (2.2 or greater). In such an |
168 | environment, the full set of busybox features should work, and if |
169 | anything doesn't we want to know about it so we can fix it. |
170 | |
171 | There are many other environments out there, in which busybox may build |
172 | and run just fine. We just don't test them. Since busybox consists of a |
173 | large number of more or less independent applets, portability is a question |
174 | of which features work where. Some busybox applets (such as cat and rm) are |
175 | highly portable and likely to work just about anywhere, while others (such as |
176 | insmod and losetup) require recent Linux kernels with recent C libraries. |
177 | |
178 | Earlier versions of Linux and glibc may or may not work, for any given |
179 | configuration. Linux 2.2 or earlier should mostly work (there's still |
180 | some support code in things like mount.c) but this is no longer regularly |
181 | tested, and inherently won't support certain features (such as long files |
182 | and --bind mounts). The same is true for glibc 2.0 and 2.1: expect a higher |
183 | testing and debugging burden using such old infrastructure. (The busybox |
184 | developers are not very interested in supporting these older versions, but |
185 | will probably accept small self-contained patches to fix simple problems.) |
186 | |
187 | Some environments are not recommended. Early versions of uClibc were buggy |
188 | and missing many features: upgrade. Linking against libc5 or dietlibc is |
189 | not supported and not interesting to the busybox developers. (The first is |
190 | obsolete and has no known size or feature advantages over uClibc, the second |
191 | has known bugs that its developers have actively refused to fix.) Ancient |
192 | Linux kernels (2.0.x and earlier) are similarly uninteresting. |
193 | |
194 | In theory it's possible to use Busybox under other operating systems (such as |
195 | MacOS X, Solaris, Cygwin, or the BSD Fork Du Jour). This generally involves |
196 | a different kernel and a different C library at the same time. While it |
197 | should be possible to port the majority of the code to work in one of |
198 | these environments, don't be surprised if it doesn't work out of the box. If |
199 | you're into that sort of thing, start small (selecting just a few applets) |
200 | and work your way up. |
201 | |
202 | In 2005 Shaun Jackman has ported busybox to a combination of newlib |
203 | and libgloss, and some of his patches have been integrated. |
204 | |
205 | Supported hardware: |
206 | |
207 | BusyBox in general will build on any architecture supported by gcc. We |
208 | support both 32 and 64 bit platforms, and both big and little endian |
209 | systems. |
210 | |
211 | Under 2.4 Linux kernels, kernel module loading was implemented in a |
212 | platform-specific manner. Busybox's insmod utility has been reported to |
213 | work under ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC, S390, |
214 | SH3/4/5, Sparc, and v850e. Anything else probably won't work. |
215 | |
216 | The module loading mechanism for the 2.6 kernel is much more generic, and |
217 | we believe 2.6.x kernel module loading support should work on all |
218 | architectures supported by the kernel. |
219 | |
220 | ---------------- |
221 | |
222 | Please feed suggestions, bug reports, insults, and bribes back to the busybox |
223 | mailing list: |
224 | |
225 | busybox@busybox.net |
226 | |
227 | and/or maintainer: |
228 | |
229 | Denys Vlasenko |
230 | <vda.linux@googlemail.com> |
231 |