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 To enable all features, use "make defconfig", which produces the largest
  22 general-purpose configuration.  (It's allyesconfig minus debugging options,
  23 optional packaging choices, and a few special-purpose features requiring
  24 extra configuration to use.)
  25
  26   make defconfig
  27   make
  28   PATH= ./busybox ash
  29
  30 Standalone shell mode causes busybox's built-in command shell to run
  31 any built-in busybox applets directly, without looking for external
  32 programs by that name.  Supplying an empty command path (as above) means
  33 the only commands busybox can find are the built-in ones.
  34
  35 (Note that the standalone shell currently requires /proc/self/exe to
  36 launch new applets.)
  37
  38 Configuring Busybox:
  39 ====================
  40
  41 Busybox is optimized for size, but enabling the full set of functionality
  42 still results in a fairly large executable -- more than 1 megabyte when
  43 statically linked.  To save space, busybox can be configured with only the
  44 set of applets needed for each environment.  The minimal configuration, with
  45 all applets disabled, produces a 4k executable.  (It's useless, but very small.)
  46
  47 The manual configurator "make menuconfig" modifies the existing configuration.
  48 (For systems without ncurses, try "make config" instead.) The two most
  49 interesting starting configurations are "make allnoconfig" (to start with
  50 everything disabled and add just what you need), and "make defconfig" (to
  51 start with everything enabled and remove what you don't need).  If menuconfig
  52 is run without an existing configuration, make defconfig will run first to
  53 create a known starting point.
  54
  55 Other starting configurations (mostly used for testing purposes) include
  56 "make allbareconfig" (enables all applets but disables all optional features),
  57 "make allyesconfig" (enables absolutely everything including debug features),
  58 and "make randconfig" (produce a random configuration).
  59
  60 Configuring BusyBox produces a file ".config", which can be saved for future
  61 use.  Run "make oldconfig" to bring a .config file from an older version of
  62 busybox up to date.
  63
  64 Installing Busybox:
  65 ===================
  66
  67 Busybox is a single executable that can behave like many different commands,
  68 and BusyBox uses the name it was invoked under to determine the desired
  69 behavior.  (Try "mv busybox ls" and then "./ls -l".)
  70
  71 Installing busybox consists of creating symlinks (or hardlinks) to the busybox
  72 binary for each applet enabled in busybox, and making sure these symlinks are
  73 in the shell's command $PATH.  Running "make install" creates these symlinks,
  74 or "make install-hardlinks" creates hardlinks instead (useful on systems with
  75 a limited number of inodes).  This install process uses the file
  76 "busybox.links" (created by make), which contains the list of enabled applets
  77 and the path at which to install them.
  78
  79 Installing links to busybox is not always necessary.  The special applet name
  80 "busybox" (or with any optional suffix, such as "busybox-static") uses the
  81 first argument to determine which applet to behave as, for example
  82 "./busybox cat LICENSE".  (Running the busybox applet with no arguments gives
  83 a list of all enabled applets.) The standalone shell can also call busybox
  84 applets without links to busybox under other names in the filesystem.  You can
  85 also configure a standaone install capability into the busybox base applet,
  86 and then install such links at runtime with one of "busybox --install" (for
  87 hardlinks) or "busybox --install -s" (for symlinks).
  88
  89 If you enabled the busybox shared library feature (libbusybox.so) and want
  90 to run tests without installing, set your LD_LIBRARY_PATH accordingly when
  91 running the executable:
  92
  93   LD_LIBRARY_PATH=`pwd` ./busybox
  94
  95 Building out-of-tree:
  96 =====================
  97
  98 By default, the BusyBox build puts its temporary files in the source tree.
  99 Building from a read-only source tree, or building multiple configurations from
 100 the same source directory, requires the ability to put the temporary files
 101 somewhere else.
 102
 103 To build out of tree, cd to an empty directory and configure busybox from there:
 104
 105   make -f /path/to/source/Makefile defconfig
 106   make
 107   make install
 108
 109 Alternately, use the O=$BUILDPATH option (with an absolute path) during the
 110 configuration step, as in:
 111
 112   make O=/some/empty/directory allyesconfig
 113   cd /some/empty/directory
 114   make
 115   make PREFIX=. install
 116
 117 More Information:
 118 =================
 119
 120 Se also the busybox FAQ, under the questions "How can I get started using
 121 BusyBox" and "How do I build a BusyBox-based system?"  The BusyBox FAQ is
 122 available from http://www.busybox.net/FAQ.html or as the file
 123 docs/busybox.net/FAQ.html in this tarball.