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