eliminate mixed declaration, to support older compilers a little longer.
[people/mcb30/busybox.git] / 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 ues 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 The special applet name "busybox" (or with any optional suffix, such as
66 "busybox-static") uses the first argument to determine which applet to behave
67 as (for example, "./busybox cat LICENSE").  (Running the busybox applet with
68 no arguments gives a list of all enabled applets.)
69
70 Building out-of-tree:
71 =====================
72
73 By default, the BusyBox build puts its temporary files in the source tree.
74 Building from a read-only source tree, or to building multiple
75 configurations from the same source directory, requires the ability to
76 put the temporary files somewhere else.
77
78 To build out of tree, use the O=$BUILDPATH option during the configuration
79 step, as in:
80
81   make O=/some/empty/directory allyesconfig
82   cd /some/empty/directory
83   make
84   make PREFIX=. install
85
86 (Note, O= requires an absolute path.)
87
88 Alternately, cd to the empty directory and do this instead:
89
90   make top_srcdir=/path/to/source -f /path/to/source/Makefile allyesconfig
91   make
92   make install
93
94 More Information:
95 =================
96
97 Se also the busybox FAQ, under the questions "How can I get started using
98 BusyBox" and "How do I build a BusyBox-based system?"  The BusyBox FAQ is
99 available from http://www.busybox.net/FAQ.html or as the file
100 docs/busybox.net/FAQ.html in this tarball.