We need a "Getting Started" document for the website.

[Rob Landley]

Here's a quick stab at it.  Also some quick notes:

1) The --help entries for zcat, bzcat, and xz are so brief they're
useless.  Decompress WHAT?  (gzip, bzip, and lzma, respectively, but it
doesn't SAY that).

-------------------------------------------------------------------

--- Obtaining and testing BusyBox

First, download a prebuilt binary version from:

  http://busybox.net/downloads/binaries/latest/

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.

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:

  ./busybox ls -l
  ./busybox ps
  ./busybox seq 1 5

To get a list of the commands supported by this instance of busybox, run
it without any arguments, or use the "--list" or :

  ./busybox

To see what an individual command does, use the --help option to that
command:

  ./busybox zcip --help

--- Installing BusyBox

If the busybox executable is renamed to one of the commands it supports,
it will act as that command automatically:

  ln -s busybox pwd
  ./pwd

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 to /usr/sbin and such to
help create a busybox-based root filesystem.)

  mkdir bbdir
  for i in $(busybox --list)
  do
    ln -s busybox bbdir/$i
  done

To launch busybox's built in command shell with the $PATH giving access
to just busybox's built-in commands:

  PATH=$(pwd)/bbdir bbdir/sh

--- Building BusyBox from source

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.

To build a defconfig busybox from source, download the source code from:

  http://busybox.net/downloads

Then configure and build it:

  make defconfig
  make

This should result in a new "busybox" binary.

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

--- Cross compiling busybox

Obtain and install a cross compiler for your target.  (A few prebuilt
ones are available from
"http://landley.net/aboriginal/downloads/binaries".  See also the
buildroot and crosstool-ng projects.)  Add the cross compiler to your $PATH.

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.

So to build busybox with that cross compiler, go:

  make CROSS_COMPILE=armv4tl-

(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.)

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:

  LDFLAGS="--static" make -j 4 CROSS_COMPILE="armv4tl-"

--- Where do I go from here?

Read the BusyBox FAQ (http://busybox.net/FAQ.html) and catch up on the
mailing list archives (http://lists.busybox.net/pipermail/busybox/).