platform/external/busybox.git - Unnamed repository; edit this file 'description' to name the repository.

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
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