Eric Andersen | cb81e64 | 2003-07-14 21:21:08 +0000 | [diff] [blame] | 1 | Please see the LICENSE file for details on copying and usage. |
Rob Landley | ff9f2f6 | 2005-10-09 20:18:32 +0000 | [diff] [blame] | 2 | Please refer to the INSTALL file for instructions on how to build. |
Eric Andersen | c7bda1c | 2004-03-15 08:29:22 +0000 | [diff] [blame] | 3 | |
Tanguy Pruvot | 8aeb371 | 2011-06-30 08:59:26 +0200 | [diff] [blame] | 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 | |
maxwen | 27116ba | 2015-08-14 21:41:28 +0200 | [diff] [blame] | 9 | This tree has multiple configurations (busybox and recovery lib), |
Tanguy Pruvot | 8aeb371 | 2011-06-30 08:59:26 +0200 | [diff] [blame] | 10 | |
maxwen | 27116ba | 2015-08-14 21:41:28 +0200 | [diff] [blame] | 11 | - lunch your device to prepare the environment |
| 12 | - edit the wanted config profile (ie busybox-full.config) |
Tanguy Pruvot | 8aeb371 | 2011-06-30 08:59:26 +0200 | [diff] [blame] | 13 | |
maxwen | 27116ba | 2015-08-14 21:41:28 +0200 | [diff] [blame] | 14 | - type "mma" in external/busybox to build with the dependencies |
Tanguy Pruvot | 8aeb371 | 2011-06-30 08:59:26 +0200 | [diff] [blame] | 15 | |
maxwen | 27116ba | 2015-08-14 21:41:28 +0200 | [diff] [blame] | 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) |
Tanguy Pruvot | 8aeb371 | 2011-06-30 08:59:26 +0200 | [diff] [blame] | 18 | |
maxwen | 27116ba | 2015-08-14 21:41:28 +0200 | [diff] [blame] | 19 | bb_obj=$OUT/obj/busybox/full |
| 20 | cat $bb_obj/.config | grep -v CROSS_COMPILER_ > busybox-full.config |
Tanguy Pruvot | 8aeb371 | 2011-06-30 08:59:26 +0200 | [diff] [blame] | 21 | |
maxwen | 27116ba | 2015-08-14 21:41:28 +0200 | [diff] [blame] | 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 |
Tanguy Pruvot | 8aeb371 | 2011-06-30 08:59:26 +0200 | [diff] [blame] | 27 | |
| 28 | ---------------- |
| 29 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 30 | What is busybox: |
Eric Andersen | cb81e64 | 2003-07-14 21:21:08 +0000 | [diff] [blame] | 31 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 32 | BusyBox combines tiny versions of many common UNIX utilities into a single |
| 33 | small executable. It provides minimalist replacements for most of the |
Rob Landley | 19d42df | 2006-05-19 22:14:19 +0000 | [diff] [blame] | 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. |
Eric Andersen | cc8ed39 | 1999-10-05 16:24:54 +0000 | [diff] [blame] | 40 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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). |
Eric Andersen | cb81e64 | 2003-07-14 21:21:08 +0000 | [diff] [blame] | 57 | |
Eric Andersen | a29dec2 | 2000-06-22 00:19:33 +0000 | [diff] [blame] | 58 | ---------------- |
Eric Andersen | c7bda1c | 2004-03-15 08:29:22 +0000 | [diff] [blame] | 59 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 60 | Using busybox: |
Mark Whitley | 3654ca5 | 2001-01-26 20:58:23 +0000 | [diff] [blame] | 61 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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.) |
Eric Andersen | fdfa09b | 2004-10-08 10:52:08 +0000 | [diff] [blame] | 66 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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 |
Tim Riker | c1ef7bd | 2006-01-25 00:08:53 +0000 | [diff] [blame] | 70 | run (I.E. "./busybox ls -l /proc"). |
Mark Whitley | 3654ca5 | 2001-01-26 20:58:23 +0000 | [diff] [blame] | 71 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 72 | The "standalone shell" mode is an easy way to try out busybox; this is a |
Dan Fandrich | b5de0c1 | 2011-07-08 05:47:49 +0200 | [diff] [blame] | 73 | command shell that calls the built-in applets without needing them to be |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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.) |
Mark Whitley | 3654ca5 | 2001-01-26 20:58:23 +0000 | [diff] [blame] | 76 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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 |
Denis Vlasenko | e8ce062 | 2007-02-03 17:29:14 +0000 | [diff] [blame] | 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"). |
Mark Whitley | 3654ca5 | 2001-01-26 20:58:23 +0000 | [diff] [blame] | 83 | |
| 84 | ---------------- |
Eric Andersen | 235f66d | 2000-12-13 18:07:38 +0000 | [diff] [blame] | 85 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 86 | Downloading the current source code: |
Eric Andersen | 235f66d | 2000-12-13 18:07:38 +0000 | [diff] [blame] | 87 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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. |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 94 | |
Denys Vlasenko | b702d9a | 2010-02-24 06:59:54 +0100 | [diff] [blame] | 95 | http://git.busybox.net/busybox/ |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 96 | |
Denys Vlasenko | 5370bfb | 2009-09-06 02:58:59 +0200 | [diff] [blame] | 97 | Anonymous GIT access is available. For instructions, check out: |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 98 | |
Denys Vlasenko | 5370bfb | 2009-09-06 02:58:59 +0200 | [diff] [blame] | 99 | http://www.busybox.net/source.html |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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 |
Bernhard Reutner-Fischer | f0dc2c1 | 2009-01-10 11:36:38 +0000 | [diff] [blame] | 107 | (https://bugs.busybox.net) although posting a bug/patch to the mailing list |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 108 | is generally a faster way of getting it fixed, and the complete archive of |
Dan Fandrich | 9669363 | 2010-08-10 23:45:27 -0700 | [diff] [blame] | 109 | what happened is the git changelog. |
Eric Andersen | a29dec2 | 2000-06-22 00:19:33 +0000 | [diff] [blame] | 110 | |
Denis Vlasenko | 97bd0e0 | 2008-02-08 15:41:01 +0000 | [diff] [blame] | 111 | Note: if you want to compile busybox in a busybox environment you must |
Denys Vlasenko | b702d9a | 2010-02-24 06:59:54 +0100 | [diff] [blame] | 112 | select CONFIG_DESKTOP. |
Denis Vlasenko | 97bd0e0 | 2008-02-08 15:41:01 +0000 | [diff] [blame] | 113 | |
Eric Andersen | a29dec2 | 2000-06-22 00:19:33 +0000 | [diff] [blame] | 114 | ---------------- |
Eric Andersen | 235f66d | 2000-12-13 18:07:38 +0000 | [diff] [blame] | 115 | |
Denys Vlasenko | b702d9a | 2010-02-24 06:59:54 +0100 | [diff] [blame] | 116 | Getting help: |
Eric Andersen | 235f66d | 2000-12-13 18:07:38 +0000 | [diff] [blame] | 117 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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. |
Eric Andersen | 235f66d | 2000-12-13 18:07:38 +0000 | [diff] [blame] | 121 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 122 | ---------------- |
Eric Andersen | 235f66d | 2000-12-13 18:07:38 +0000 | [diff] [blame] | 123 | |
Denys Vlasenko | b702d9a | 2010-02-24 06:59:54 +0100 | [diff] [blame] | 124 | Bugs: |
Eric Andersen | 235f66d | 2000-12-13 18:07:38 +0000 | [diff] [blame] | 125 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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: |
Eric Andersen | cb81e64 | 2003-07-14 21:21:08 +0000 | [diff] [blame] | 141 | |
| 142 | $ date |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 143 | fri oct 8 14:19:41 mdt 2004 |
Eric Andersen | cb81e64 | 2003-07-14 21:21:08 +0000 | [diff] [blame] | 144 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 145 | but when i use busybox date i get this instead: |
Eric Andersen | cb81e64 | 2003-07-14 21:21:08 +0000 | [diff] [blame] | 146 | |
| 147 | $ date |
Eric Andersen | fbcf06d | 2004-03-27 09:40:15 +0000 | [diff] [blame] | 148 | illegal instruction |
Eric Andersen | cb81e64 | 2003-07-14 21:21:08 +0000 | [diff] [blame] | 149 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 150 | i am using debian unstable, kernel version 2.4.25-vrs2 on a netwinder, |
Denis Vlasenko | 18875bf | 2008-07-17 18:33:35 +0000 | [diff] [blame] | 151 | and the latest uclibc from cvs. |
Eric Andersen | cb81e64 | 2003-07-14 21:21:08 +0000 | [diff] [blame] | 152 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 153 | -diligent |
Eric Andersen | 235f66d | 2000-12-13 18:07:38 +0000 | [diff] [blame] | 154 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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. |
Eric Andersen | a29dec2 | 2000-06-22 00:19:33 +0000 | [diff] [blame] | 159 | |
| 160 | ---------------- |
Eric Andersen | 235f66d | 2000-12-13 18:07:38 +0000 | [diff] [blame] | 161 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 162 | Portability: |
Eric Andersen | 235f66d | 2000-12-13 18:07:38 +0000 | [diff] [blame] | 163 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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 |
Dan Fandrich | b5de0c1 | 2011-07-08 05:47:49 +0200 | [diff] [blame] | 198 | these environments, don't be surprised if it doesn't work out of the box. If |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 199 | you're into that sort of thing, start small (selecting just a few applets) |
| 200 | and work your way up. |
| 201 | |
Denis Vlasenko | 18875bf | 2008-07-17 18:33:35 +0000 | [diff] [blame] | 202 | In 2005 Shaun Jackman has ported busybox to a combination of newlib |
| 203 | and libgloss, and some of his patches have been integrated. |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 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, v850e, and x86_64. 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. |
Eric Andersen | a29dec2 | 2000-06-22 00:19:33 +0000 | [diff] [blame] | 219 | |
| 220 | ---------------- |
Eric Andersen | 235f66d | 2000-12-13 18:07:38 +0000 | [diff] [blame] | 221 | |
Rob Landley | d27d3be | 2005-10-09 18:20:54 +0000 | [diff] [blame] | 222 | Please feed suggestions, bug reports, insults, and bribes back to the busybox |
Denys Vlasenko | b702d9a | 2010-02-24 06:59:54 +0100 | [diff] [blame] | 223 | mailing list: |
| 224 | |
| 225 | busybox@busybox.net |
| 226 | |
| 227 | and/or maintainer: |
| 228 | |
Denis Vlasenko | 18875bf | 2008-07-17 18:33:35 +0000 | [diff] [blame] | 229 | Denys Vlasenko |
Denys Vlasenko | b702d9a | 2010-02-24 06:59:54 +0100 | [diff] [blame] | 230 | <vda.linux@googlemail.com> |