Start of developer documentation for busybox.

[oweals/busybox.git] / docs / busybox.net / FAQ.html

<!--#include file="header.html" -->


<h3>Frequently Asked Questions</h3>

This is a collection of some of the more frequently asked questions
about BusyBox.  Some of the questions even have answers. If you
have additions to this FAQ document, we would love to add them,

<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="#bugs">I think I found a bug in BusyBox!  What should I do?!</a>
<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><a href="#demanding">I demand that you to add &lt;favorite feature&gt; 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 &lt;favorite feature&gt;!  Are the BusyBox developers willing to
        be paid in order to fix bugs or add in &lt;favorite feature&gt;?  Are you willing to provide
        support contracts?</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="#support">I think you guys are great and I want to help support your work!</a>
<li><a href="#optimize">I want to make busybox even smaller, how do I go about it?</a>



</ol>

<hr />
<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".
</p>
<p>
    This will create a busybox binary with 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
    usage message for a given applet.
</p>
<p>
    BusyBox uses the name it was invoked under to determine which applet is
    being invoked.  (Try "mv busybox ls" and then "./ls -l".)  Installing
    busybox consists of creating symlinks (or hardlinks) to the busybox
    binary for each applet in busybox, and making sure these links are in
    the shell's command $PATH.  The special applet name "busybox" (or with
    any optional suffix, such as "busybox-static") uses the first argument
    to determine which applet to run, as shown above.
</p>
<p>
    BusyBox also has a feature called the "standalone shell", 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.)
</p>
<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
    menuconfig to add just the features you need.  Don't forget to recompile
    with "make" once you've finished configuring.)
</p>
<hr/>
<p/>
<h2><a name="build_system">How do I build a BusyBox-based system?</a></h2>
<p>
    BusyBox is a package that replaces a dozen standard packages, but it is
    not by itself a complete bootable system.  Building an entire Linux
    distribution from source is a bit beyond the scope of this FAQ, but it
    understandably keeps cropping up on the mailing list, so here are some
    pointers.
</p>
<p>
    Start by learning how to strip a working system down to the bare essentials
    needed to run one or two commands, so you know what it is you actually
    need.  An excellent practical place to do
    this is the <a href="http://www.tldp.org/HOWTO/Bootdisk-HOWTO/">Linux
    BootDisk Howto</a>, or for a more theoretical approach try
    <a href="http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html">From
    PowerUp to Bash Prompt</a>.
</p>
<p>
    To learn how to build a working Linux system entirely from source code,
    the place to go is the <a href="http://www.linuxfromscratch.org">Linux
    From Scratch</a> project.  They have an entire book of step-by-step
    instructions you can
    <a href="http://www.linuxfromscratch.org/lfs/view/stable/">read online</a>
    or
    <a href="http://www.linuxfromscratch.org/lfs/downloads/stable/">download</a>.
    Be sure to check out the other sections of their main page, including
    Beyond Linux From Scratch, Hardened Linux From Scratch, their Hints
    directory, and their LiveCD project.  (They also have mailing lists which
    are better sources of answers to Linux-system building questions than
    the busybox list.)
</p>
<p>
    If you want an automated yet customizable system builder which produces
    a BusyBox and uClibc based system, try
    <a href="http://buildroot.uclibc.org">buildroot</a>, which is
    another project by the maintainer of the uClibc and BusyBox projects
    (Erik Andersen).  Download the tarball, extract it, unset CC, make.
    For more instructions, see the website.
</p>


<hr />
<p>
<h2><a name="kernel">Which Linux kernel versions are supported?</a></h2>
<p>
    Full functionality requires Linux 2.4.x or better.  (Earlier versions may
    still work, but are no longer regularly tested.)  A large fraction of the
    code should run on just about anything.  While the current code is fairly
    Linux specific, it should be fairly easy to port the majority of the code
    to support, say, FreeBSD or Solaris, or Mac OS X, or even Windows (if you
    are into that sort of thing).
</p>
<hr />
<p>
<h2><a name="arch">Which architectures does BusyBox run on?</a></h2>
<p>
    BusyBox in general will build on any architecture supported by gcc.
    Kernel module loading for 2.4 Linux kernels is currently
    limited to ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC,
    S390, SH3/4/5, Sparc, v850e, and x86_64 for 2.4.x kernels.
</p>
<p>
    With 2.6.x kernels, module loading support should work on all architectures.
</p>
<hr />
<p>
<h2><a name="libc">Which C libraries are supported?</a></h2>
<p>
    On Linux, BusyBox releases are tested against uClibc (0.9.27 or later) and
    glibc (2.2 or later).  Both should provide full functionality with busybox,
    and if you find a bug we want to hear about it.
</p>
<p>
    Linux-libc5 is no longer maintained (and has no known advantages over
    uClibc), dietlibc is known to have numerous unfixed bugs, and klibc is
    missing too many features to build BusyBox.  If you require a small C
    library for Linux, the busybox developers recommend uClibc.
</p>
<p>
    Some BusyBox applets have been built and run under a combination
    of newlib and libgloss (see
    <a href="http://www.busybox.net/lists/busybox/2005-March/013759.html">this thread</a>).
    This is still experimental, but may be supported in a future release.
</p>
<hr />
<p>
<h2><a name="commercial">Can I include BusyBox as part of the software on my device?</a></h2>

    Yes.  As long as you <a href="http://busybox.net/license.html">fully comply
    with the generous terms of the GPL BusyBox license</a> you can ship BusyBox
    as part of the software on your device.

    <br>
    <a href="#support">Please consider sharing some of the money you make.</a>


<hr />
<p>
<h2><a name="bugs">I think I found a bug in BusyBox!  What should I do?</a></h2>
<p>


<p>

    If you simply need help with using or configuring BusyBox, please submit a
    detailed description of your problem to the BusyBox mailing list at <a
    href="mailto:busybox@mail.busybox.net"> busybox@mail.busybox.net</a>.
    Please do not send private email to Erik (the maintainer of BusyBox) asking
    for private help unless you are planning on paying for consulting services.
    When we answer questions on the BusyBox mailing list, it helps everyone,
    while private answers help only you...

    <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 sometimes get
    lost when posted to the mailing list.  To prevent your bug report from
    getting lost, if you find a bug in BusyBox, please use the <a
    href="http://bugs.busybox.net/">BusyBox Bug and Patch Tracking System</a>
    to submit a detailed bug report.

    <p>

    The same also applies to patches... Regardless of whether your patch is a
    bug fix or adds shiney new features, please post your patch to the <a
    href="http://bugs.busybox.net/">BusyBox Bug and Patch Tracking System</a>
    to make certain it is properly considered.


<hr />
<p>
<h2><a name="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></h2>
<p>

    Job control will be turned off since your shell can not obtain a controlling
    terminal.  This typically happens when you run your shell on /dev/console.
    The kernel will not provide a controlling terminal on the /dev/console
    device.  Your should run your shell on a normal tty such as tty1 or ttyS0
    and everything will work perfectly.  If you <em>REALLY</em> want your shell
    to run on /dev/console, then you can hack your kernel (if you are into that
    sortof thing) by changing drivers/char/tty_io.c to change the lines where
    it sets "noctty = 1;" to instead set it to "0".  I recommend you instead
    run your shell on a real console...


<hr />
<p>
<h2><a name="demanding">I demand that you to add &lt;favorite feature&gt; 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></h2>
<p>

    You have not paid us a single cent and yet you still have the product of
    many years of our work.  We are not your slaves!  We work on BusyBox
    because we find it useful and interesting.  If you go off flaming us, we
    will ignore you.


<hr />
<p>
<h2><a name="helpme">I need help with BusyBox!  What should I do?</a></h2>
<p>

    If you find that you need help with BusyBox, you can ask for help on the
    BusyBox mailing list at busybox@mail.busybox.net.  In addition to the BusyBox
    mailing list, Erik (andersee), Manuel (mjn3) and others are known to hang out
    on the uClibc IRC channel: #uclibc on irc.freenode.net.  (Daily logs of
    that IRC channel, going back to 2002, are available
    <a href="http://ibot.Rikers.org/%23uclibc/">here</a>.)

    <p>

    <b>Please do not send private email to Erik, Manuel, or the other BusyBox
    contributors asking for private help unless you are planning on paying for
    consulting services.</b>

    <p>

    When we answer questions on the BusyBox mailing list, it helps everyone
    since people with similar problems in the future will be able to get help
    by searching the mailing list archives.  Private help is reserved as a paid
    service.  If you need to use private communication, or if you are serious
    about getting timely assistance with BusyBox, you should seriously consider
    paying for consulting services.

    <p>



<hr />
<p>
<h2><a name="contracts">I need you to add &lt;favorite feature&gt;!  Are the BusyBox
        developers willing to be paid in order to fix bugs or add in &lt;favorite feature&gt;?
        Are you willing to provide support contracts?</a></h2>
<p>

    Sure!  Now you have our attention!  What you should do is contact <a
        href="mailto:andersen@codepoet.org">Erik Andersen</a> of <a
        href="http://codepoet-consulting.com/">CodePoet Consulting</a> to bid
    on your project.  If Erik is too busy to personally add your feature, there
    are many other active BusyBox contributors who will almost certainly be able
    to help you out.  Erik can contact them privately, and may even let you to
    post your request for services on the mailing list.


<hr />
<p>
<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!


<hr />
<p>
<h2><a name="support">I think you guys are great and I want to help support your work!</a></h2>
<p>

    Wow, that would be great!  If you would like to make a donation to help
    support BusyBox, and/or request features, you can click here:

    <!-- Begin PayPal Logo -->
    <center>
    <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
        <input type="hidden" name="cmd" value="_xclick">
        <input type="hidden" name="business" value="andersen@codepoet.org">
        <input type="hidden" name="item_name" value="Support BusyBox">
        <input type="hidden" name="image_url" value="http://codepoet-consulting.com/images/codepoet.png">
        <input type="hidden" name="no_shipping" value="1">
        <input type="image" src="images/donate.png" name="submit" alt="Make donation using PayPal">
    </form>
    </center>
    <!-- End PayPal Logo -->

    If you prefer to contact Erik directly to make a donation, donate hardware,
    request support, etc, you can contact
    <a href="http://codepoet-consulting.com/">CodePoet Consulting</a> here.
    CodePoet Consulting can accept both Visa and MasterCard for those that do not
    trust PayPal...

<hr />
<p>
<h2><a name="optimize">I want to make busybox even smaller, how do I go about it?</a></h2>
<p>
        To conserve bytes it's good to know where they're being used, and the
        size of the final executable isn't always a reliable indicator of
        the size of the components (since various structures are rounded up,
        so a small change may not even be visible by itself, but many small
        savings add up).
</p>
<p>
        The busybox Makefile can generate a report of how much space is actually
        being used by each function and variable.  Run "<b>make sizes</b>" (preferably
        with CONFIG_DEBUG off) to get a list of symbols and the amount of
        space allocated for each one, sorted by size.
</p>
<hr />



<br>
<br>
<br>

<!--#include file="footer.html" -->