<h2>General questions</h2>
<ol>
-<li><a href="#getting_started">How can I get started using BusyBox?</a>
-<li><a href="#build_system">How do I build a BusyBox-based system?</a>
-<li><a href="#kernel">Which Linux kernel versions are supported?</a>
-<li><a href="#arch">Which architectures does BusyBox run on?</a>
-<li><a href="#libc">Which C libraries are supported?</a>
-<li><a href="#commercial">Can I include BusyBox as part of the software on my device?</a>
-<li><a href="#external">Where can I find other small utilities since busybox does not include the features I want?</a></li>
-<li><a href="#demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a>
-<li><a href="#helpme">I need help with BusyBox! What should I do?</a>
-<li><a href="#contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a>
+<li><a href="#getting_started">How can I get started using BusyBox?</a></li>
+<li><a href="#configure">How do I configure busybox?</a></li>
+<li><a href="#build_system">How do I build a BusyBox-based system?</a></li>
+<li><a href="#kernel">Which Linux kernel versions are supported?</a></li>
+<li><a href="#arch">Which architectures does BusyBox run on?</a></li>
+<li><a href="#libc">Which C libraries are supported?</a></li>
+<li><a href="#commercial">Can I include BusyBox as part of the software on my device?</a></li>
+<li><a href="#external">Where can I find other small utilities since busybox does not include the features I want?</a></li></li>
+<li><a href="#demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a></li>
+<li><a href="#helpme">I need help with BusyBox! What should I do?</a></li>
+<li><a href="#contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a></li>
</ol>
<h2>Troubleshooting</h2>
<ol>
<li><a href="#bugs">I think I found a bug in BusyBox! What should I do?!</a></li>
+<li><a href="#backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</a></li>
<li><a href="#init">Busybox init isn't working!</a></li>
<li><a href="#sed">I can't configure busybox on my system.</a></li>
<li><a href="#job_control">Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?</a></li>
<p>
<h2><a name="getting_started">How can I get started using BusyBox?</a></h2>
<p> If you just want to try out busybox without installing it, download the
- tarball, extract it, run "make allyesconfig", and then run "make".
+ tarball, extract it, run "make defconfig", and then run "make".
</p>
<p>
- This will create a busybox binary with all features enabled. To try
+ This will create a busybox binary with almost all features enabled. To try
out a busybox applet, type "./busybox [appletname] [options]", for
example "./busybox ls -l" or "./busybox cat LICENSE". Type "./busybox"
to see a command list, and "busybox appletname --help" to see a brief
to determine which applet to run, as shown above.
</p>
<p>
- BusyBox also has a feature called the "standalone shell", where the busybox
+ BusyBox also has a feature called the
+ <a name="standalone_shell">"standalone shell"</a>, where the busybox
shell runs any built-in applets before checking the command path. This
feature is also enabled by "make allyesconfig", and to try it out run
the command line "PATH= ./busybox ash". This will blank your command path
and run busybox as your command shell, so the only commands it can find
(without an explicit path such as /bin/ls) are the built-in busybox ones.
- This is another good way to see what's built into busybox. (Note that the
- standalone shell is dependent on the existence of /proc/self/exe, so before
- using it in a chroot environment you must mount /proc.)
+ This is another good way to see what's built into busybox.
+ Note that the standalone shell requires CONFIG_BUSYBOX_EXEC_PATH
+ to be set appropriately, depending on whether or not /proc/self/exe is
+ available or not. If you do not have /proc, then point that config option
+ to the location of your busybox binary, usually /bin/busybox.
+ (So if you set it to /proc/self/exe, and happen to be able to chroot into
+ your rootfs, you must mount /proc beforehand.)
</p>
+<p>
+ A typical indication that you set CONFIG_BUSYBOX_EXEC_PATH to proc but
+ forgot to mount proc is:
+<pre>
+$ /bin/echo $PATH
+/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11
+$ echo $PATH
+/bin/sh: echo: not found
+</pre>
+<hr />
+<p>
+<h2><a name="configure">How do I configure busybox?</a></h2>
+<p> Busybox is configured similarly to the linux kernel. Create a default
+ configuration and then run "make menuconfig" to modify it. The end
+ result is a .config file that tells the busybox build process what features
+ to include. So instead of "./configure; make; make install" the equivalent
+ busybox build would be "make defconfig; make; make install".
+</p>
+
+<p> Busybox configured with all features enabled is a little under a megabyte
+ dynamically linked on x86. To create a smaller busybox, configure it with
+ fewer features. Individual busybox applets cost anywhere from a few
+ hundred bytes to tens of kilobytes. Disable unneeded applets to save,
+ space, using menuconfig.
+</p>
+
+<p>The most important busybox configurators are:</p>
+
+<ul>
+<li><p>make <b>defconfig</b> - Create the maximum "sane" configuration. This
+enables almost all features, minus things like debugging options and features
+that require changes to the rest of the system to work (such as selinux or
+devfs device names). Use this if you want to start from a full-featured
+busybox and remove features until it's small enough.</p></li>
+<li><p>make <b>allnoconfig</b> - Disable everything. This creates a tiny version
+of busybox that doesn't do anything. Start here if you know exactly what
+you want and would like to select only those features.</p></li>
+<li><p>make <b>menuconfig</b> - Interactively modify a .config file through a
+multi-level menu interface. Use this after one of the previous two.</p></li>
+</ul>
+
+<p>Some other configuration options are:</p>
+<ul>
+<li><p>make <b>oldconfig</b> - Update an old .config file for a newer version
+of busybox.</p></li>
+<li><p>make <b>allyesconfig</b> - Select absolutely everything. This creates
+a statically linked version of busybox full of debug code, with dependencies on
+selinux, using devfs names... This makes sure everything compiles. Whether
+or not the result would do anything useful is an open question.</p></li>
+<li><p>make <b>allbareconfig</b> - Select all applets but disable all sub-features
+within each applet. More build coverage testing.</p></li>
+<li><p>make <b>randconfig</b> - Create a random configuration for test purposes.</p></li>
+</ul>
+
+<p> Menuconfig modifies your .config file through an interactive menu where you can enable or disable
+ busybox features, and get help about each feature.
+
+
+
<p>
To build a smaller busybox binary, run "make menuconfig" and disable the
features you don't need. (Or run "make allnoconfig" and then use
<hr />
<p>
-<h2><a name="external">where can i find other small utilities since busybox
+<h2><a name="external">where can i find other small utilities since busybox
does not include the features i want?</a></h2>
<p>
we maintain such a <a href="tinyutils.html">list</a> on this site!
</p>
<p>
- The developers of BusyBox are busy people, and have only so much they can
- keep in their brains at a time. As a result, bug reports and new feature
- patches sometimes get lost when posted to the mailing list. To prevent
- your bug report from getting lost, if you find a bug in BusyBox that isn't
- immediately addressed, please use the <a
- href="http://bugs.busybox.net/">BusyBox Bug and Patch Tracking System</a>
- to submit a detailed explanation and we'll get to it as soon as we can.
+ Bug reports and new feature patches sometimes get lost when posted to the
+ mailing list, because the developers of BusyBox are busy people and have
+ only so much they can keep in their brains at a time. You can post a
+ polite reminder after 2-3 days without offending anybody. If that doesn't
+ result in a solution, please use the
+ <a href="http://bugs.busybox.net/">BusyBox Bug
+ and Patch Tracking System</a> to submit a detailed explanation and we'll
+ get to it as soon as we can.
</p>
+<p>
+ Note that bugs entered into the bug system without being mentioned on the
+ mailing list first may languish there for months before anyone even notices
+ them. We generally go through the bug system when preparing for new
+ development releases, to see what fell through the cracks while we were
+ off writing new features. (It's a fast/unreliable vs slow/reliable thing.
+ Saves retransits, but the latency sucks.)
+</p>
+
+<hr />
+<p></p>
+<h2><a name="backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</h2>
+
+<p>Variants of this one get asked a lot.</p>
+
+<p>The purpose of the BusyBox mailing list is to develop and improve BusyBox,
+and we're happy to respond to our users' needs. But if you're coming to the
+list for free tech support we're going to ask you to upgrade to a current
+version before we try to diagnose your problem.</p>
+
+<p>If you're building BusyBox 0.50 with uClibc 0.9.19 and gcc 0.9.26 there's a
+fairly large chance that whatever problem you're seeing has already been fixed.
+To get that fix, all you have to do is upgrade to a newer version. If you
+don't at least _try_ that, you're wasting our time.</p>
+
+<p>The volunteers are happy to fix any bugs you point out in the current
+versions because doing so helps everybody and makes the project better. We
+want to make the current version work for you. But diagnosing, debugging, and
+backporting fixes to old versions isn't something we do for free, because it
+doesn't help anybody but you. The cost of volunteer tech support is using a
+reasonably current version of the project.</p>
+
+<p>If you don't want to upgrade, you have the complete source code and thus
+the ability to fix it yourself, or hire a consultant to do it for you. If you
+got your version from a vendor who still supports the older version, they can
+help you. But there are limits as to what the volunteers will feel obliged to
+do for you.</p>
+
+<p>As a rule of thumb, volunteers will generally answer polite questions about
+a given version for about three years after its release before it's so old
+we don't remember the answer off the top of our head. And if you want us to
+put any _effort_ into tracking it down, we want you to put in a little effort
+of your own by confirming it's still a problem with the current version. It's
+also hard for us to fix a problem of yours if we can't reproduce it because
+we don't have any systems running an environment that old.</p>
+
+<p>A consultant will happily set up a special environment just to reproduce
+your problem, and you can always ask on the list if any of the developers
+have consulting rates.</p>
+
<hr />
<p>
<h2><a name="init">Busybox init isn't working!</a></h2>
<p>
- Build a statically linked version of the following "hello world" program
- with your cross compiler toolchain.
+ Init is the first program that runs, so it might be that no programs are
+ working on your new system because of a problem with your cross-compiler,
+ kernel, console settings, shared libraries, root filesystem... To rule all
+ that out, first build a statically linked version of the following "hello
+ world" program with your cross compiler toolchain:
</p>
<pre>
#include <stdio.h>
<p>
Once you've got it working statically linked, try getting it to work
dynamically linked. Then read the FAQ entry <a href="#build_system">How
- do I build a BusyBox-based system?</a>
+ do I build a BusyBox-based system?</a>, and the
+ <a href="/downloads/BusyBox.html#item_init">documentation for BusyBox
+ init</a>.
</p>
<hr />
applets.</p>
<p>Busybox execution starts with the main() function in applets/busybox.c,
-which sets the global variable bb_applet_name to argv[0] and calls
+which sets the global variable applet_name to argv[0] and calls
run_applet_by_name() in applets/applets.c. That uses the applets[] array
(defined in include/busybox.h and filled out in include/applets.h) to
transfer control to the appropriate APPLET_main() function (such as
have to test the return value (xmalloc(), xstrdup(), etc), wrapped versions
of open(), close(), read(), and write() that test for their own failures
and/or retry automatically, linked list management functions (llist.c),
-command line argument parsing (getopt_ulflags.c), and a whole lot more.</p>
+command line argument parsing (getopt32.c), and a whole lot more.</p>
<hr />
<p>
<p> The <b>"make bloatcheck"</b> option uses Matt Mackall's bloat-o-meter
script to compare two versions of busybox (busybox_unstripped vs
busybox_old), and report which symbols changed size and by how much.
- To use it, first build a base version, rename busybox_unstripped to
- busybox_old, and then build a new version with your changes and run
- "make bloatcheck" to see the size differences from the old version.
+ To use it, first build a base version with <b>"make baseline"</b>.
+ (This creates busybox_old, which should have the original sizes for
+ comparison purposes.) Then build the new version with your changes
+ and run "make bloatcheck" to see the size differences from the old
+ version.
</p>
<p>
The first line of output has totals: how many symbols were added or
<p>So will data always be read from the far end of a pipe at the
same chunk sizes it was written in? Nope. Don't rely on that. For one
-counterexample, see <a href="http://www.faqs.org/rfcs/rfc896.html">rfc 896
+counterexample, see <a href="http://www.faqs.org/rfcs/rfc896.html">rfc 896
for Nagle's algorithm</a>, which waits a fraction of a second or so before
sending out small amounts of data through a TCP/IP connection in case more
data comes in that can be merged into the same packet. (In case you were
<pre>
aldot :Bernhard Fischer
-andersen :Erik Andersen <- uClibc and BuildRoot maintainer.
+andersen :Erik Andersen - uClibc and BuildRoot maintainer.
bug1 :Glenn McGrath
davidm :David McCullough
-gkajmowi :Garrett Kajmowicz <- uClibc++ maintainer
+gkajmowi :Garrett Kajmowicz - uClibc++ maintainer
jbglaw :Jan-Benedict Glaw
jocke :Joakim Tjernlund
-landley :Rob Landley <- BusyBox maintainer
+landley :Rob Landley - BusyBox maintainer
lethal :Paul Mundt
mjn3 :Manuel Novoa III
osuadmin :osuadmin
</pre>
<p>The following accounts used to exist on busybox.net, but don't anymore so
-I can't ask /etc/passwd for their names. (If anybody would like to make
-a stab at it...)</p>
+I can't ask /etc/passwd for their names. Rob Wentworth <robwen@gmail.com>
+asked Google and recovered the names:</p>
<pre>
-aaronl
-beppu
-dwhedon
-erik : Also Erik Andersen?
-gfeldman
-jimg
-kraai
-markw
-miles
-proski
-rjune
-tausq
-vodz :Vladimir N. Oleynik
+aaronl :Aaron Lehmann
+beppu :John Beppu
+dwhedon :David Whedon
+erik :Erik Andersen
+gfeldman :Gennady Feldman
+jimg :Jim Gleason
+kraai :Matt Kraai
+markw :Mark Whitley
+miles :Miles Bader
+proski :Pavel Roskin
+rjune :Richard June
+tausq :Randolph Chung
+vodz :Vladimir N. Oleynik
</pre>
projects / oweals / busybox.git / blobdiff