From fbcf06d2960f8f0959aac71d0fad8d9ab446b439 Mon Sep 17 00:00:00 2001 From: Eric Andersen Date: Sat, 27 Mar 2004 09:40:15 +0000 Subject: Update docs --- docs/busybox_footer.pod | 20 +----------- docs/busybox_header.pod | 87 +++++++++++++++++++++++++++++++++++++------------ 2 files changed, 68 insertions(+), 39 deletions(-) (limited to 'docs') diff --git a/docs/busybox_footer.pod b/docs/busybox_footer.pod index d243a92d9..4f1058573 100644 --- a/docs/busybox_footer.pod +++ b/docs/busybox_footer.pod @@ -1,23 +1,5 @@ =back -=head1 LIBC NSS - -GNU Libc 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. BusyBox has made it Policy that it -will never use NSS, and will never use and libc calls that make use of NSS. -This allows you to run an embedded system without the need for installing an -/etc/nsswitch.conf file and without and /lib/libnss_* libraries installed. - -If you are using a system that is using a remote LDAP server for authentication -via GNU libc NSS, and you want to use BusyBox, then you will need to adjust the -BusyBox source. Chances are though, that if you have enough space to install -of that stuff on your system, then you probably want the full GNU utilities. - -=head1 SEE ALSO - -textutils(1), shellutils(1), etc... - =head1 MAINTAINER Erik Andersen @@ -173,4 +155,4 @@ Glenn Engel =cut -# $Id: busybox_footer.pod,v 1.13 2004/03/13 08:32:14 andersen Exp $ +# $Id: busybox_footer.pod,v 1.14 2004/03/27 09:40:15 andersen Exp $ diff --git a/docs/busybox_header.pod b/docs/busybox_header.pod index 132aa3b65..395e2c81a 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. -- cgit v1.2.3