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