blob: 731e58e411d872bb11ef4867626e5f4052ea7dd7 [file] [log] [blame]
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +00001Building:
2=========
3
Rob Landleyff9f2f62005-10-09 20:18:32 +00004The BusyBox build process is similar to the Linux kernel build:
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +00005
Rob Landleyff9f2f62005-10-09 20:18:32 +00006 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
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +00009
Rob Landleyff9f2f62005-10-09 20:18:32 +000010The full list of configuration and install options is available by typing:
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +000011
Rob Landleyff9f2f62005-10-09 20:18:32 +000012 make help
Matt Kraai6e91f692001-05-10 14:12:20 +000013
Rob Landleyff9f2f62005-10-09 20:18:32 +000014Quick Start:
15============
Matt Kraai6e91f692001-05-10 14:12:20 +000016
Rob Landleyff9f2f62005-10-09 20:18:32 +000017The 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
Rob Landley965030e2006-03-13 04:38:40 +000019blank command $PATH.
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +000020
Rob Landley965030e2006-03-13 04:38:40 +000021To 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.)
25
26 make defconfig
Rob Landleyff9f2f62005-10-09 20:18:32 +000027 make
28 PATH= ./busybox ash
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +000029
Rob Landleyff9f2f62005-10-09 20:18:32 +000030Standalone shell mode causes busybox's built-in command shell to run
31any built-in busybox applets directly, without looking for external
32programs by that name. Supplying an empty command path (as above) means
33the only commands busybox can find are the built-in ones.
Bernhard Reutner-Fischerb8faa7e2005-10-07 17:44:14 +000034
Rob Landley965030e2006-03-13 04:38:40 +000035(Note that the standalone shell currently requires /proc/self/exe to
36launch new applets.)
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +000037
Rob Landleyff9f2f62005-10-09 20:18:32 +000038Configuring Busybox:
39====================
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +000040
Rob Landleyff9f2f62005-10-09 20:18:32 +000041Busybox is optimized for size, but enabling the full set of functionality
Rob Landley965030e2006-03-13 04:38:40 +000042still results in a fairly large executable -- more than 1 megabyte when
43statically linked. To save space, busybox can be configured with only the
Rob Landleyff9f2f62005-10-09 20:18:32 +000044set of applets needed for each environment. The minimal configuration, with
45all applets disabled, produces a 4k executable. (It's useless, but very small.)
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +000046
Rob Landley965030e2006-03-13 04:38:40 +000047The manual configurator "make menuconfig" modifies the existing configuration.
48(For systems without ncurses, try "make config" instead.) The two most
49interesting starting configurations are "make allnoconfig" (to start with
50everything disabled and add just what you need), and "make defconfig" (to
51start with everything enabled and remove what you don't need). If menuconfig
52is run without an existing configuration, make defconfig will run first to
53create a known starting point.
54
55Other starting configurations (mostly used for testing purposes) include
Bernhard Reutner-Fischer14b1d292006-05-19 14:02:51 +000056"make allbareconfig" (enables all applets but disables all optional features),
Rob Landley965030e2006-03-13 04:38:40 +000057"make allyesconfig" (enables absolutely everything including debug features),
58and "make randconfig" (produce a random configuration).
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +000059
Rob Landleyff9f2f62005-10-09 20:18:32 +000060Configuring BusyBox produces a file ".config", which can be saved for future
Rob Landley965030e2006-03-13 04:38:40 +000061use. Run "make oldconfig" to bring a .config file from an older version of
62busybox up to date.
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +000063
Rob Landleyff9f2f62005-10-09 20:18:32 +000064Installing Busybox:
65===================
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +000066
Rob Landleyff9f2f62005-10-09 20:18:32 +000067Busybox is a single executable that can behave like many different commands,
68and BusyBox uses the name it was invoked under to determine the desired
69behavior. (Try "mv busybox ls" and then "./ls -l".)
Bernhard Reutner-Fischer5c071bc2005-10-05 07:40:46 +000070
Rob Landleyff9f2f62005-10-09 20:18:32 +000071Installing busybox consists of creating symlinks (or hardlinks) to the busybox
72binary for each applet enabled in busybox, and making sure these symlinks are
73in the shell's command $PATH. Running "make install" creates these symlinks,
74or "make install-hardlinks" creates hardlinks instead (useful on systems with
Rob Landleyd4f15e92005-12-02 18:27:39 +000075a limited number of inodes). This install process uses the file
Rob Landleyff9f2f62005-10-09 20:18:32 +000076"busybox.links" (created by make), which contains the list of enabled applets
77and the path at which to install them.
78
Rob Landleyd4f15e92005-12-02 18:27:39 +000079Installing links to busybox is not always necessary. The special applet name
80"busybox" (or with any optional suffix, such as "busybox-static") uses the
81first argument to determine which applet to behave as, for example
82"./busybox cat LICENSE". (Running the busybox applet with no arguments gives
83a list of all enabled applets.) The standalone shell can also call busybox
84applets without links to busybox under other names in the filesystem. You can
85also configure a standaone install capability into the busybox base applet,
86and then install such links at runtime with one of "busybox --install" (for
87hardlinks) or "busybox --install -s" (for symlinks).
Rob Landleyff9f2f62005-10-09 20:18:32 +000088
Rob Landley965030e2006-03-13 04:38:40 +000089If you enabled the busybox shared library feature (libbusybox.so) and want
90to run tests without installing, set your LD_LIBRARY_PATH accordingly when
91running the executable:
Bernhard Reutner-Fischer5d261262006-03-01 22:54:48 +000092
Rob Landley965030e2006-03-13 04:38:40 +000093 LD_LIBRARY_PATH=`pwd` ./busybox
Bernhard Reutner-Fischer5d261262006-03-01 22:54:48 +000094
Rob Landleyff9f2f62005-10-09 20:18:32 +000095Building out-of-tree:
96=====================
97
98By default, the BusyBox build puts its temporary files in the source tree.
Rob Landley965030e2006-03-13 04:38:40 +000099Building from a read-only source tree, or building multiple configurations from
100the same source directory, requires the ability to put the temporary files
101somewhere else.
Rob Landleyff9f2f62005-10-09 20:18:32 +0000102
Rob Landley965030e2006-03-13 04:38:40 +0000103To build out of tree, cd to an empty directory and configure busybox from there:
Bernhard Reutner-Fischer5d261262006-03-01 22:54:48 +0000104
Rob Landley965030e2006-03-13 04:38:40 +0000105 make -f /path/to/source/Makefile defconfig
Bernhard Reutner-Fischer5d261262006-03-01 22:54:48 +0000106 make
107 make install
108
Rob Landley965030e2006-03-13 04:38:40 +0000109Alternately, use the O=$BUILDPATH option (with an absolute path) during the
110configuration step, as in:
Rob Landleyff9f2f62005-10-09 20:18:32 +0000111
112 make O=/some/empty/directory allyesconfig
113 cd /some/empty/directory
114 make
115 make PREFIX=. install
116
Rob Landleyff9f2f62005-10-09 20:18:32 +0000117More Information:
118=================
119
120Se also the busybox FAQ, under the questions "How can I get started using
121BusyBox" and "How do I build a BusyBox-based system?" The BusyBox FAQ is
122available from http://www.busybox.net/FAQ.html or as the file
123docs/busybox.net/FAQ.html in this tarball.