summaryrefslogtreecommitdiff
path: root/docs/busybox_header.pod
diff options
context:
space:
mode:
authorEric Andersen2004-03-27 09:40:15 +0000
committerEric Andersen2004-03-27 09:40:15 +0000
commitfbcf06d2960f8f0959aac71d0fad8d9ab446b439 (patch)
treed3518bfe5e398abef0ac3fd0af9254cbbfd56808 /docs/busybox_header.pod
parent97310d025390e96f34140cff13034fcd2b5da18f (diff)
downloadbusybox-fbcf06d2960f8f0959aac71d0fad8d9ab446b439.zip
busybox-fbcf06d2960f8f0959aac71d0fad8d9ab446b439.tar.gz
Update docs
Diffstat (limited to 'docs/busybox_header.pod')
-rw-r--r--docs/busybox_header.pod87
1 files changed, 67 insertions, 20 deletions
diff --git a/docs/busybox_header.pod b/docs/busybox_header.pod
index 132aa3b..395e2c8 100644
--- a/docs/busybox_header.pod
+++ b/docs/busybox_header.pod
@@ -14,42 +14,67 @@ BusyBox - The Swiss Army Knife of Embedded Linux
BusyBox combines tiny versions of many common UNIX utilities into a single
small executable. It provides minimalist replacements for most of the utilities
-you usually find in fileutils, shellutils, findutils, textutils, grep, gzip,
-tar, etc. BusyBox provides a fairly complete POSIX environment for any small
-or embedded system. The utilities in BusyBox generally have fewer options than
-their full-featured GNU cousins; however, the options that are included provide
-the expected functionality and behave very much like their GNU counterparts.
+you usually find in GNU coreutils, util-linux, etc. The utilities in BusyBox
+generally have fewer options than their full-featured GNU cousins; however, the
+options that are included provide the expected functionality and behave very
+much like their GNU counterparts. BusyBox provides a fairly complete POSIX
+environment for any small or embedded system.
BusyBox has been written with size-optimization and limited resources in mind.
It is also extremely modular so you can easily include or exclude commands (or
-features) at compile time. This makes it easy to customize your embedded
-systems. To create a working system, just add a kernel, a shell (such as ash),
-and an editor (such as elvis-tiny or ae).
+features) at compile time. This makes it easy to customize your embedded
+systems. To create a working system, just add /dev, /etc, and a Linux kernel.
+
+BusyBox is extremely configurable. This allows you to include only the
+components you need, thereby reducing binary size. Run 'make config' or 'make
+menuconfig' for select the functionality that you wish to enable. The run
+'make' to compile BusyBox using your configuration.
+
+After the compile has finished, you should use 'make install' to install
+BusyBox. This will install the '/bin/busybox' binary, and will also create
+symlinks pointing to the '/bin/busybox' binary for each utility that you
+compile into BusyBox. By default, 'make install' will place these symlinks
+into the './_install' directory, unless you have defined 'PREFIX', thereby
+specifying some alternative location (i.e., 'make PREFIX=/tmp/foo install').
+If you wish to install using hardlinks, rather than the default of using
+symlinks, you can use 'make PREFIX=/tmp/foo install-hardlinks' instead.
=head1 USAGE
-When you create a link to BusyBox for the function you wish to use, when BusyBox
-is called using that link it will behave as if the command itself has been invoked.
+BusyBox is a multi-call binary. A multi-call binary is an executable program
+that performs the same job as more than one utility program. That means there
+is just a single BusyBox binary, but that single binary acts like a large
+number of utilities. This allows BusyBox to be smaller since all the built-in
+utility programs (we call them applets) can share code for many common operations.
+
+You can also invoke BusyBox by issuing the command as an argument on the
+command line. For example, entering
+
+ /bin/busybox ls
+
+will also cause BusyBox to behave as 'ls'.
+
+Of course, adding '/bin/busybox' into every command would be painful. So most
+people will invoke BusyBox using links to the BusyBox binary.
For example, entering
- ln -s ./BusyBox ls
+ ln -s /bin/busybox ls
./ls
will cause BusyBox to behave as 'ls' (if the 'ls' command has been compiled
-into BusyBox).
-
-You can also invoke BusyBox by issuing the command as an argument on the
-command line. For example, entering
+into BusyBox). Generally speaking, you should never need to make all these
+links yourself, as the BusyBox build system will do this for you when you run
+the 'make install' command.
- ./BusyBox ls
-
-will also cause BusyBox to behave as 'ls'.
+If you invoke BusyBox with no arguments, it will provide you with a list of the
+applets that have been compiled into your BusyBox binary.
=head1 COMMON OPTIONS
-Most BusyBox commands support the B<-h> option to provide a
-terse runtime description of their behavior.
+Most BusyBox commands support the B<--help> argument to provide a terse runtime
+description of their behavior. If the CONFIG_FEATURE_VERBOSE_USAGE option has
+been enabled, more detailed usage information will also be available.
=head1 COMMANDS
@@ -80,4 +105,26 @@ Currently defined functions include:
=over 4
+=head1 LIBC NSS
+
+GNU Libc (glibc) uses the Name Service Switch (NSS) to configure the behavior
+of the C library for the local environment, and to configure how it reads
+system data, such as passwords and group information. This is implemented
+using an /etc/nsswitch.conf configuration file, and using one or more of the
+/lib/libnss_* libraries. BusyBox tries to avoid using any libc calls that make
+use of NSS. Some applets, such as login and su, will use libc functions that
+usually require NSS.
+
+If you enable CONFIG_USE_BB_PWD_GRP, BusyBox will use internal functions to
+directly access the /etc/passwd, /etc/group, and /etc/shadow files without
+using NSS. This may allow you to run your system without the need for
+installing any of the NSS configuration files and libraries.
+
+When used with glibc, the BusyBox 'networking' applets will similarly require
+that you install at least some of the glibc NSS stuff (in particular,
+/etc/nsswitch.conf, /lib/libnss_dns*, /lib/libnss_files*, and /lib/libresolv*).
+
+Shameless Plug: As an alternative one could use a C library such as uClibc. In
+addition to making your system significantly smaller, uClibc does not need or
+use any NSS support files or libraries.