Annotation of /trunk/mkinitrd-magellan/busybox/INSTALL

Building:
=========

The BusyBox build process is similar to the Linux kernel build:

  make menuconfig     # This creates a file called ".config"
  make                # This creates the "busybox" executable
  make install        # or make CONFIG_PREFIX=/path/from/root install

The full list of configuration and install options is available by typing:

  make help

Quick Start:
============

The easy way to try out BusyBox for the first time, without having to install
it, is to enable all features and then use "standalone shell" mode with a
blank command $PATH.

To enable all features, use "make defconfig", which produces the largest
general-purpose configuration.  It's allyesconfig minus debugging options,
optional packaging choices, and a few special-purpose features requiring
extra configuration to use.  Then enable "standalone shell" feature:

  make defconfig
  make menuconfig
  # select Busybox Settings
  #   then General Configuration
  #     then exec prefers applets
  #   exit back to top level menu
  #   select Shells
  #     then Standalone shell
  #   exit back to top level menu
  # exit and save new configuration
  #   OR
  # use these commands to modify .config directly:
  sed -e 's/.*FEATURE_PREFER_APPLETS.*/CONFIG_FEATURE_PREFER_APPLETS=y/' -i .config
  sed -e 's/.*FEATURE_SH_STANDALONE.*/CONFIG_FEATURE_SH_STANDALONE=y/' -i .config
  make
  PATH= ./busybox ash

Standalone shell mode causes busybox's built-in command shell to run
any built-in busybox applets directly, without looking for external
programs by that name.  Supplying an empty command path (as above) means
the only commands busybox can find are the built-in ones.

Note that the standalone shell requires CONFIG_BUSYBOX_EXEC_PATH
to be set appropriately, depending on whether or not /proc/self/exe is
available or not. If you do not have /proc, then point that config option
to the location of your busybox binary, usually /bin/busybox.

Configuring Busybox:
====================

Busybox is optimized for size, but enabling the full set of functionality
still results in a fairly large executable -- more than 1 megabyte when
statically linked.  To save space, busybox can be configured with only the
set of applets needed for each environment.  The minimal configuration, with
all applets disabled, produces a 4k executable.  (It's useless, but very small.)

The manual configurator "make menuconfig" modifies the existing configuration.
(For systems without ncurses, try "make config" instead.) The two most
interesting starting configurations are "make allnoconfig" (to start with
everything disabled and add just what you need), and "make defconfig" (to
start with everything enabled and remove what you don't need).  If menuconfig
is run without an existing configuration, make defconfig will run first to
create a known starting point.

Other starting configurations (mostly used for testing purposes) include
"make allbareconfig" (enables all applets but disables all optional features),
"make allyesconfig" (enables absolutely everything including debug features),
and "make randconfig" (produce a random configuration).

Configuring BusyBox produces a file ".config", which can be saved for future
use.  Run "make oldconfig" to bring a .config file from an older version of
busybox up to date.

Installing Busybox:
===================

Busybox is a single executable that can behave like many different commands,
and BusyBox uses the name it was invoked under to determine the desired
behavior.  (Try "mv busybox ls" and then "./ls -l".)

Installing busybox consists of creating symlinks (or hardlinks) to the busybox
binary for each applet enabled in busybox, and making sure these symlinks are
in the shell's command $PATH.  Running "make install" creates these symlinks,
or "make install-hardlinks" creates hardlinks instead (useful on systems with
a limited number of inodes).  This install process uses the file
"busybox.links" (created by make), which contains the list of enabled applets
and the path at which to install them.

Installing links to busybox is not always necessary.  The special applet name
"busybox" (or with any optional suffix, such as "busybox-static") uses the
first argument to determine which applet to behave as, for example
"./busybox cat LICENSE".  (Running the busybox applet with no arguments gives
a list of all enabled applets.) The standalone shell can also call busybox
applets without links to busybox under other names in the filesystem.  You can
also configure a standaone install capability into the busybox base applet,
and then install such links at runtime with one of "busybox --install" (for
hardlinks) or "busybox --install -s" (for symlinks).

If you enabled the busybox shared library feature (libbusybox.so) and want
to run tests without installing, set your LD_LIBRARY_PATH accordingly when
running the executable:

  LD_LIBRARY_PATH=`pwd` ./busybox

Building out-of-tree:
=====================

By default, the BusyBox build puts its temporary files in the source tree.
Building from a read-only source tree, or building multiple configurations from
the same source directory, requires the ability to put the temporary files
somewhere else.

To build out of tree, cd to an empty directory and configure busybox from there:

  make KBUILD_SRC=/path/to/source -f /path/to/source/Makefile defconfig
  make
  make install

Alternately, use the O=$BUILDPATH option (with an absolute path) during the
configuration step, as in:

  make O=/some/empty/directory allyesconfig
  cd /some/empty/directory
  make
  make CONFIG_PREFIX=. install

More Information:
=================

Se also the busybox FAQ, under the questions "How can I get started using
BusyBox" and "How do I build a BusyBox-based system?"  The BusyBox FAQ is
available from http://www.busybox.net/FAQ.html
1	niro	532	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	niro	816	make install # or make CONFIG_PREFIX=/path/from/root install
9	niro	532
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	niro	984	general-purpose configuration. It's allyesconfig minus debugging options,
23	niro	532	optional packaging choices, and a few special-purpose features requiring
24	niro	984	extra configuration to use. Then enable "standalone shell" feature:
25	niro	532
26			make defconfig
27	niro	984	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	niro	532	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).
74
75			Configuring BusyBox produces a file ".config", which can be saved for future
76			use. Run "make oldconfig" to bring a .config file from an older version of
77			busybox up to date.
78
79			Installing Busybox:
80			===================
81
82			Busybox is a single executable that can behave like many different commands,
83			and BusyBox uses the name it was invoked under to determine the desired
84			behavior. (Try "mv busybox ls" and then "./ls -l".)
85
86			Installing busybox consists of creating symlinks (or hardlinks) to the busybox
87			binary for each applet enabled in busybox, and making sure these symlinks are
88			in the shell's command $PATH. Running "make install" creates these symlinks,
89			or "make install-hardlinks" creates hardlinks instead (useful on systems with
90			a limited number of inodes). This install process uses the file
91			"busybox.links" (created by make), which contains the list of enabled applets
92			and the path at which to install them.
93
94			Installing links to busybox is not always necessary. The special applet name
95			"busybox" (or with any optional suffix, such as "busybox-static") uses the
96			first argument to determine which applet to behave as, for example
97			"./busybox cat LICENSE". (Running the busybox applet with no arguments gives
98			a list of all enabled applets.) The standalone shell can also call busybox
99			applets without links to busybox under other names in the filesystem. You can
100			also configure a standaone install capability into the busybox base applet,
101			and then install such links at runtime with one of "busybox --install" (for
102			hardlinks) or "busybox --install -s" (for symlinks).
103
104			If you enabled the busybox shared library feature (libbusybox.so) and want
105			to run tests without installing, set your LD_LIBRARY_PATH accordingly when
106			running the executable:
107
108			LD_LIBRARY_PATH=`pwd` ./busybox
109
110			Building out-of-tree:
111			=====================
112
113			By default, the BusyBox build puts its temporary files in the source tree.
114			Building from a read-only source tree, or building multiple configurations from
115			the same source directory, requires the ability to put the temporary files
116			somewhere else.
117
118			To build out of tree, cd to an empty directory and configure busybox from there:
119
120	niro	984	make KBUILD_SRC=/path/to/source -f /path/to/source/Makefile defconfig
121	niro	532	make
122			make install
123
124			Alternately, use the O=$BUILDPATH option (with an absolute path) during the
125			configuration step, as in:
126
127			make O=/some/empty/directory allyesconfig
128			cd /some/empty/directory
129			make
130	niro	816	make CONFIG_PREFIX=. install
131	niro	532
132			More Information:
133			=================
134
135			Se also the busybox FAQ, under the questions "How can I get started using
136			BusyBox" and "How do I build a BusyBox-based system?" The BusyBox FAQ is
137	niro	984	available from http://www.busybox.net/FAQ.html