Expand "How can I get started using Busybox" based on Rob's email

Signed-off-by: Denys Vlasenko <vda.linux@googlemail.com>

1 files changed, 137 insertions, 29 deletions

diff --git a/FAQ.html b/FAQ.html
index dc02735..22361f8 100644
--- a/FAQ.html
+++ b/FAQ.html
@@ -1,6 +1,6 @@
 <!--#include file="header.html" -->
 
-<h3>Frequently Asked Questions</h3>
+<h1>Frequently Asked Questions</h1>
 
 This is a collection of some of the more frequently asked questions
 about Busybox.  Some of the questions even have answers. If you
@@ -108,36 +108,144 @@ have additions to this FAQ document, we would love to add them,
 <hr />
 <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 defconfig", and then run "make".
+<h3>Obtaining and testing Busybox</h3>
+
+<p> First, download a prebuilt binary version from
+    <a href="http://busybox.net/downloads/binaries/latest/">http://busybox.net/downloads/binaries/latest/</a>
+    and save it under the name "busybox".  The "busybox-i686" version should
+    run on both 32-bit and 64-bit x86 PCs, and the armv4tl version is the
+    most generic arm version (for smartphones), so those are probably good
+    starting points.
 </p>
-<p>
-    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
-    usage message for a given applet.
+<p> This is a statically linked version of the busybox "multiplexer", a
+    single command that can perform multiple actions, the way a swiss army
+    knife has multiple blades.  To try it out, give busybox the command line
+    you'd like it to execute:
 </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.
+<pre>
+ ./busybox ls -l
+ ./busybox ps
+ ./busybox seq 1 5
+</pre>
+<p> To get a list of the commands supported by this instance of busybox, run
+    it without any arguments, or use the "--list" or :
+</p>
+<pre>
+ ./busybox
+</pre>
+<p> To see what an individual command does, use the --help option to that
+    command:
+</p>
+<pre>
+ ./busybox zcip --help
+</pre>
+
+<h3>Installing Busybox</h3>
+
+<p> If the busybox executable is renamed to one of the commands it supports,
+    it will act as that command automatically:
+</p>
+<pre>
+ ln -s busybox pwd
+ ./pwd
+</pre>
+<p> This allows you to create a bunch of symlinks or hardlinks to the
+    busybox executable, add them to your $PATH, and let a single busybox
+    provide a standard set of command line tools.  The --list option to
+    busybox gives the list of supported commands in an easily scriptable
+    form.  (The --list-full option gives full paths, such as usr/sbin/test,
+    to help create a busybox-based root filesystem.)
+</p>
+<pre>
+ mkdir bbdir
+ for i in $(busybox --list)
+ do
+   ln -s busybox bbdir/$i
+ done
+</pre>
+<p> To launch busybox's built in command shell with the $PATH giving access
+    to just busybox's built-in commands:
+</p>
+<pre>
+ PATH=$(pwd)/bbdir bbdir/sh
+</pre>
+
+<h3>Building Busybox from source</h3>
+
+<p> The prebuilt binaries are based on the default configuration of busybox,
+    which enables all functionality except special purpose things like
+    selinux or debugging support which would reduce the portability of the
+    resulting binary.
+</p>
+<p> To build a defconfig busybox from source, download the source code from
+    <a href="http://busybox.net/downloads">http://busybox.net/downloads</a>
+</p>
+
+<p> Then configure and build it:
+</p>
+<pre>
+ make defconfig
+ make
+</pre>
+<p> This should result in a new "busybox" binary.
+</p>
+<p> Busybox uses the same "menuconfig" infrastructure as the Linux kernel.
+    you can start with "make defconfig" to enable almost everything, or
+    "make allnoconfig" to disable everything, and then alter the selection
+    with "make menuconfig" (which uses tab, cursor up and down, space, and
+    escape keys to navigate, and the forward slash key to search for symbol
+    name).
+</p>
+
+<h3>Cross compiling busybox</h3>
+
+<p> Obtain and install a cross compiler for your target.  (A few prebuilt
+    ones are available from
+    <a href="http://landley.net/aboriginal/downloads/binaries">http://landley.net/aboriginal/downloads/binaries</a>.
+    See also the buildroot and crosstool-ng projects.)
+    Add the cross compiler to your $PATH.
+</p>
+<p> Cross compilers use prefixed tool names to avoid blocking the host's
+    existing compiler, thus the tools your cross compiler provides are
+    probably named things like "armv4tl-cc", "armv4tl-ld", and
+    "armv4tl-strip".  In this case, "armv4tl-" would be the prefix.
+</p>
+<p> So to build busybox with that cross compiler, go:
+</p>
+<pre>
+ make CROSS_COMPILE=armv4tl-
+</pre>
+<p> (Note the trailing dash, if that's part of the prefix.  This is a make
+    variable override preventing busybox from using its default value, which
+    is why it has to come on the make command line instead of as an
+    environment variable.)
 </p>
+<p> To build a static version, set the environment variable
+    "LDFLAGS=--static".  And of course you can do a parallel SMP build with
+    make's -j options.  So to build a static cross compiled version of
+    busybox using a parallel build:
+</p>
+<pre>
+ LDFLAGS="--static" make -j 4 CROSS_COMPILE="armv4tl-"
+</pre>
+
+<h3>Standalone shell</h3>
+
 <p>
     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
+    feature is not enabled by "make defconfig".  To try it out, set
+    CONFIG_FEATURE_PREFER_APPLETS and CONFIG_FEATURE_SH_STANDALONE to 'y'
+    in .config (using text editor, or by running "make menuconfig" and
+    setting these options interactively), rebuild Busybox, then run
+    the command line "PATH= ./busybox ash".
+    This will blank your command search 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 requires CONFIG_BUSYBOX_EXEC_PATH
-    to be set appropriately, depending on whether or not /proc/self/exe is
+    Note that the standalone shell also requires CONFIG_BUSYBOX_EXEC_PATH
+    to be set appropriately, and the default value, /proc/self/exe, would work
+    only if /proc filesystem is mounted.
     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
@@ -276,14 +384,14 @@ test -f cross-compiler-armv5l.tar.bz2 \
 rm -rf cross-compiler-armv5l
 tar xf cross-compiler-armv5l.tar.bz2
 
-test -f Busybox-1.17.2.tar.bz2 \
+test -f busybox-1.17.2.tar.bz2 \
 || wget http://busybox.net/downloads/busybox-1.17.2.tar.bz2
-rm -rf Busybox-1.17.2
-tar xf Busybox-1.17.2.tar.bz2
+rm -rf busybox-1.17.2
+tar xf busybox-1.17.2.tar.bz2
 
 CROSS_COMPILE="$PWD/cross-compiler-armv5l/bin/armv5l-"
 
-cd Busybox-1.17.2
+cd busybox-1.17.2
 make CROSS_COMPILE="$CROSS_COMPILE" defconfig
 make CROSS_COMPILE="$CROSS_COMPILE"
 </pre>
@@ -470,7 +578,7 @@ text somewhere on the company's web site:
   and<br>
   http://company.site.com/firmware/source/.config<br>
   to the same directory and apply the patch with this command:<br>
-    patch -p1 &lt;Busybox-1.6.2.patch<br>
+    patch -p1 &lt;busybox-1.6.2.patch<br>
   Now you can build Busybox with these commands:<br>
     export ARCH=arm<br>
     make CROSS_COMPILE=arm-linux-uclibc-<br>
@@ -657,14 +765,14 @@ int main(int argc, char *argv)
 
 <pre>
   tar xvjf sources/busybox-x.x.x.tar.bz2
-  cd Busybox-x.x.x
+  cd busybox-x.x.x
   make allnoconfig
   make include/bb_config.h
   echo "CONFIG_SED=y" >> .config
   echo "#undef ENABLE_SED" >> include/bb_config.h
   echo "#define ENABLE_SED 1" >> include/bb_config.h
   make
-  mv Busybox sed
+  mv busybox sed
   export PATH=`pwd`:"$PATH"
 </pre>