summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDenys Vlasenko <vda.linux@googlemail.com>2011-03-08 10:04:50 (GMT)
committer Denys Vlasenko <vda.linux@googlemail.com>2011-03-08 10:04:50 (GMT)
commitf21b8252036901b7ef2188c3d341141181f8f12d (patch)
treeddbf48245ef5b71be29cd21079528a057afba0b7
parentcc7de179d4c2160022e170a2aa7f0282d18c28fa (diff)
downloadbusybox-website-f21b8252036901b7ef2188c3d341141181f8f12d.tar.gz
busybox-website-f21b8252036901b7ef2188c3d341141181f8f12d.tar.bz2
Expand "How can I get started using Busybox" based on Rob's email
Signed-off-by: Denys Vlasenko <vda.linux@googlemail.com>
-rw-r--r--FAQ.html166
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>