lash: style cleanup

[oweals/busybox.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 9f09110ce5ffacc5ee4ed97336e3fd8b5dfaf6f1..a7902ab8dc4ffc20b51d65835d820589bea8df43 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -5,7 +5,7 @@ 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 menuconfig     # This creates a file called ".config"
   make                # This creates the "busybox" executable

-  make install        # or make PREFIX=/path/from/root install
+  make install        # or make CONFIG_PREFIX=/path/from/root install

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


@@ -16,9 +16,14 @@ 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
 
 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:
+blank command $PATH.

 
 

-  make allyesconfig
+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.)
+
+  make defconfig

   make
   PATH= ./busybox ash
 
   make
   PATH= ./busybox ash
 


@@ -27,25 +32,36 @@ 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.
 
 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 the /proc directory to function.)
+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
 
 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
+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.)
 
 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 configurators "make config" and "make menuconfig" modify the
-existing configuration.  Quick ways to get starting configurations include
-"make allyesconfig" (enables almost all options), "make allnoconfig" (disables
-all options), "make allbaseconfig" (enables all applets but disables all
-optional features), and "make defconfig" (reset to defaults).
+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
 
 Configuring BusyBox produces a file ".config", which can be saved for future

-use.
+use.  Run "make oldconfig" to bring a .config file from an older version of
+busybox up to date.

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


@@ -58,38 +74,47 @@ 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
 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 ues the file
+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.
 
 "busybox.links" (created by make), which contains the list of enabled applets
 and the path at which to install them.
 

-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.)
+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 out-of-tree:
 =====================
 
 By default, the BusyBox build puts its temporary files in the source tree.

-Building from a read-only source tree, or to building multiple
-configurations from the same source directory, requires the ability to
-put the temporary files somewhere else.
+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, use the O=$BUILDPATH option during the configuration
-step, as in:
+To build out of tree, cd to an empty directory and configure busybox from there:

 
 

-  make O=/some/empty/directory allyesconfig
-  cd /some/empty/directory
+  make -f /path/to/source/Makefile defconfig

   make
   make

-  make PREFIX=. install
-
-(Note, O= requires an absolute path.)
+  make install

 
 

-Alternately, cd to the empty directory and do this instead:
+Alternately, use the O=$BUILDPATH option (with an absolute path) during the
+configuration step, as in:

 
 

-  make top_srcdir=/path/to/source -f /path/to/source/Makefile allyesconfig
+  make O=/some/empty/directory allyesconfig
+  cd /some/empty/directory

   make
   make

-  make install
+  make CONFIG_PREFIX=. install

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