INSTALL

   1 Building:
   2 =========
   3
   4 The BusyBox build process is similar to the Linux kernel build:
   5
   6   make menuconfig     # This creates a file called ".config"
   7   make                # This creates the "busybox" executable
   8   make install        # or make PREFIX=/path/from/root install
   9
  10 The full list of configuration and install options is available by typing:
  11
  12   make help
  13
  14 Quick Start:
  15 ============
  16
  17 The easy way to try out BusyBox for the first time, without having to install
  18 it, is to enable all features and then use "standalone shell" mode with a
  19 blank command $PATH:
  20
  21   make allyesconfig
  22   make
  23   PATH= ./busybox ash
  24
  25 Standalone shell mode causes busybox's built-in command shell to run
  26 any built-in busybox applets directly, without looking for external
  27 programs by that name.  Supplying an empty command path (as above) means
  28 the only commands busybox can find are the built-in ones.
  29
  30 (Note that the standalone shell requires the /proc directory to function.)
  31
  32 Configuring Busybox:
  33 ====================
  34
  35 Busybox is optimized for size, but enabling the full set of functionality
  36 still results in a fairly large executable (more than 1 megabyte when
  37 statically linked).  To save space, busybox can be configured with only the
  38 set of applets needed for each environment.  The minimal configuration, with
  39 all applets disabled, produces a 4k executable.  (It's useless, but very small.)
  40
  41 The manual configurators "make config" and "make menuconfig" modify the
  42 existing configuration.  Quick ways to get starting configurations include
  43 "make allyesconfig" (enables almost all options), "make allnoconfig" (disables
  44 all options), "make allbaseconfig" (enables all applets but disables all
  45 optional features), and "make defconfig" (reset to defaults).
  46
  47 Configuring BusyBox produces a file ".config", which can be saved for future
  48 use.
  49
  50 Installing Busybox:
  51 ===================
  52
  53 Busybox is a single executable that can behave like many different commands,
  54 and BusyBox uses the name it was invoked under to determine the desired
  55 behavior.  (Try "mv busybox ls" and then "./ls -l".)
  56
  57 Installing busybox consists of creating symlinks (or hardlinks) to the busybox
  58 binary for each applet enabled in busybox, and making sure these symlinks are
  59 in the shell's command $PATH.  Running "make install" creates these symlinks,
  60 or "make install-hardlinks" creates hardlinks instead (useful on systems with
  61 a limited number of inodes).  This install process uses the file
  62 "busybox.links" (created by make), which contains the list of enabled applets
  63 and the path at which to install them.
  64
  65 Installing links to busybox is not always necessary.  The special applet name
  66 "busybox" (or with any optional suffix, such as "busybox-static") uses the
  67 first argument to determine which applet to behave as, for example
  68 "./busybox cat LICENSE".  (Running the busybox applet with no arguments gives
  69 a list of all enabled applets.) The standalone shell can also call busybox
  70 applets without links to busybox under other names in the filesystem.  You can
  71 also configure a standaone install capability into the busybox base applet,
  72 and then install such links at runtime with one of "busybox --install" (for
  73 hardlinks) or "busybox --install -s" (for symlinks).
  74
  75 If you built busybox as shared object which uses libbusybox.so and have not
  76 yet installed the binary but want to run tests, then set your LD_LIBRARY_PATH
  77 accordingly before running the executable:
  78
  79   export LD_LIBRARY_PATH=`pwd`
  80   ./busybox
  81
  82 Building out-of-tree:
  83 =====================
  84
  85 By default, the BusyBox build puts its temporary files in the source tree.
  86 Building from a read-only source tree, or to building multiple
  87 configurations from the same source directory, requires the ability to
  88 put the temporary files somewhere else.
  89
  90 To build out of tree, cd to the empty directory and do this instead:
  91
  92   make -f /path/to/source/Makefile allyesconfig
  93   make
  94   make install
  95
  96 Alternately, use the O=$BUILDPATH option during the configuration step, as in:
  97
  98   make O=/some/empty/directory allyesconfig
  99   cd /some/empty/directory
 100   make
 101   make PREFIX=. install
 102
 103 (Note, O= requires an absolute path.)
 104
 105
 106 More Information:
 107 =================
 108
 109 Se also the busybox FAQ, under the questions "How can I get started using
 110 BusyBox" and "How do I build a BusyBox-based system?"  The BusyBox FAQ is
 111 available from http://www.busybox.net/FAQ.html or as the file
 112 docs/busybox.net/FAQ.html in this tarball.