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