Magellan Linux

  • Back to homepage
    • /[magellan-source]/trunk/mkinitrd-magellan/busybox/README

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

    Parent Directory Parent Directory | Revision Log Revision Log

    Revision 532 - (hide annotations) (download)
    Sat Sep 1 22:45:15 2007 UTC (16 years, 8 months ago) by niro
    File size: 8821 byte(s) 
    -import if magellan mkinitrd; it is a fork of redhats mkinitrd-5.0.8 with all magellan patches and features; deprecates magellan-src/mkinitrd
    1 niro 532 Please see the LICENSE file for details on copying and usage.
    2     Please refer to the INSTALL file for instructions on how to build.
    3    
    4     What is busybox:
    5    
    6     BusyBox combines tiny versions of many common UNIX utilities into a single
    7     small executable. It provides minimalist replacements for most of the
    8     utilities you usually find in bzip2, coreutils, dhcp, diffutils, e2fsprogs,
    9     file, findutils, gawk, grep, inetutils, less, modutils, net-tools, procps,
    10     sed, shadow, sysklogd, sysvinit, tar, util-linux, and vim. The utilities
    11     in BusyBox often have fewer options than their full-featured cousins;
    12     however, the options that are included provide the expected functionality
    13     and behave very much like their larger counterparts.
    14    
    15     BusyBox has been written with size-optimization and limited resources in
    16     mind, both to produce small binaries and to reduce run-time memory usage.
    17     Busybox is also extremely modular so you can easily include or exclude
    18     commands (or features) at compile time. This makes it easy to customize
    19     embedded systems; to create a working system, just add /dev, /etc, and a
    20     Linux kernel. Busybox (usually together with uClibc) has also been used as
    21     a component of "thin client" desktop systems, live-CD distributions, rescue
    22     disks, installers, and so on.
    23    
    24     BusyBox provides a fairly complete POSIX environment for any small system,
    25     both embedded environments and more full featured systems concerned about
    26     space. Busybox is slowly working towards implementing the full Single Unix
    27     Specification V3 (http://www.opengroup.org/onlinepubs/009695399/), but isn't
    28     there yet (and for size reasons will probably support at most UTF-8 for
    29     internationalization). We are also interested in passing the Linux Test
    30     Project (http://ltp.sourceforge.net).
    31    
    32     ----------------
    33    
    34     Using busybox:
    35    
    36     BusyBox is extremely configurable. This allows you to include only the
    37     components and options you need, thereby reducing binary size. Run 'make
    38     config' or 'make menuconfig' to select the functionality that you wish to
    39     enable. (See 'make help' for more commands.)
    40    
    41     The behavior of busybox is determined by the name it's called under: as
    42     "cp" it behaves like cp, as "sed" it behaves like sed, and so on. Called
    43     as "busybox" it takes the second argument as the name of the applet to
    44     run (I.E. "./busybox ls -l /proc").
    45    
    46     The "standalone shell" mode is an easy way to try out busybox; this is a
    47     command shell that calls the builtin applets without needing them to be
    48     installed in the path. (Note that this requires /proc to be mounted, if
    49     testing from a boot floppy or in a chroot environment.)
    50    
    51     The build automatically generates a file "busybox.links", which is used by
    52     'make install' to create symlinks to the BusyBox binary for all compiled in
    53     commands. This uses the PREFIX environment variable to specify where to
    54     install, and installs hardlinks or symlinks depending on the configuration
    55     preferences. (You can also manually run the install script at
    56     "applets/install.sh").
    57    
    58     ----------------
    59    
    60     Downloading the current source code:
    61    
    62     Source for the latest released version, as well as daily snapshots, can always
    63     be downloaded from
    64    
    65     http://busybox.net/downloads/
    66    
    67     You can browse the up to the minute source code and change history online.
    68    
    69     http://www.busybox.net/cgi-bin/viewcvs.cgi/trunk/busybox/
    70    
    71     Anonymous SVN access is available. For instructions, check out:
    72    
    73     http://busybox.net/subversion.html
    74    
    75     For those that are actively contributing and would like to check files in,
    76     see:
    77    
    78     http://busybox.net/developer.html
    79    
    80     The developers also have a bug and patch tracking system
    81     (http://bugs.busybox.net) although posting a bug/patch to the mailing list
    82     is generally a faster way of getting it fixed, and the complete archive of
    83     what happened is the subversion changelog.
    84    
    85     ----------------
    86    
    87     getting help:
    88    
    89     when you find you need help, you can check out the busybox mailing list
    90     archives at http://busybox.net/lists/busybox/ or even join
    91     the mailing list if you are interested.
    92    
    93     ----------------
    94    
    95     bugs:
    96    
    97     if you find bugs, please submit a detailed bug report to the busybox mailing
    98     list at busybox@busybox.net. a well-written bug report should include a
    99     transcript of a shell session that demonstrates the bad behavior and enables
    100     anyone else to duplicate the bug on their own machine. the following is such
    101     an example:
    102    
    103     to: busybox@busybox.net
    104     from: diligent@testing.linux.org
    105     subject: /bin/date doesn't work
    106    
    107     package: busybox
    108     version: 1.00
    109    
    110     when i execute busybox 'date' it produces unexpected results.
    111     with gnu date i get the following output:
    112    
    113     $ date
    114     fri oct 8 14:19:41 mdt 2004
    115    
    116     but when i use busybox date i get this instead:
    117    
    118     $ date
    119     illegal instruction
    120    
    121     i am using debian unstable, kernel version 2.4.25-vrs2 on a netwinder,
    122     and the latest uclibc from cvs. thanks for the wonderful program!
    123    
    124     -diligent
    125    
    126     note the careful description and use of examples showing not only what
    127     busybox does, but also a counter example showing what an equivalent app
    128     does (or pointing to the text of a relevant standard). Bug reports lacking
    129     such detail may never be fixed... Thanks for understanding.
    130    
    131     ----------------
    132    
    133     Portability:
    134    
    135     Busybox is developed and tested on Linux 2.4 and 2.6 kernels, compiled
    136     with gcc (the unit-at-a-time optimizations in version 3.4 and later are
    137     worth upgrading to get, but older versions should work), and linked against
    138     uClibc (0.9.27 or greater) or glibc (2.2 or greater). In such an
    139     environment, the full set of busybox features should work, and if
    140     anything doesn't we want to know about it so we can fix it.
    141    
    142     There are many other environments out there, in which busybox may build
    143     and run just fine. We just don't test them. Since busybox consists of a
    144     large number of more or less independent applets, portability is a question
    145     of which features work where. Some busybox applets (such as cat and rm) are
    146     highly portable and likely to work just about anywhere, while others (such as
    147     insmod and losetup) require recent Linux kernels with recent C libraries.
    148    
    149     Earlier versions of Linux and glibc may or may not work, for any given
    150     configuration. Linux 2.2 or earlier should mostly work (there's still
    151     some support code in things like mount.c) but this is no longer regularly
    152     tested, and inherently won't support certain features (such as long files
    153     and --bind mounts). The same is true for glibc 2.0 and 2.1: expect a higher
    154     testing and debugging burden using such old infrastructure. (The busybox
    155     developers are not very interested in supporting these older versions, but
    156     will probably accept small self-contained patches to fix simple problems.)
    157    
    158     Some environments are not recommended. Early versions of uClibc were buggy
    159     and missing many features: upgrade. Linking against libc5 or dietlibc is
    160     not supported and not interesting to the busybox developers. (The first is
    161     obsolete and has no known size or feature advantages over uClibc, the second
    162     has known bugs that its developers have actively refused to fix.) Ancient
    163     Linux kernels (2.0.x and earlier) are similarly uninteresting.
    164    
    165     In theory it's possible to use Busybox under other operating systems (such as
    166     MacOS X, Solaris, Cygwin, or the BSD Fork Du Jour). This generally involves
    167     a different kernel and a different C library at the same time. While it
    168     should be possible to port the majority of the code to work in one of
    169     these environments, don't be suprised if it doesn't work out of the box. If
    170     you're into that sort of thing, start small (selecting just a few applets)
    171     and work your way up.
    172    
    173     Shaun Jackman has recently (2005) ported busybox to a combination of newlib
    174     and libgloss, and some of his patches have been integrated. This platform
    175     may join glibc/uclibc and Linux as a supported combination with the 1.1
    176     release, but is not supported in 1.0.
    177    
    178     Supported hardware:
    179    
    180     BusyBox in general will build on any architecture supported by gcc. We
    181     support both 32 and 64 bit platforms, and both big and little endian
    182     systems.
    183    
    184     Under 2.4 Linux kernels, kernel module loading was implemented in a
    185     platform-specific manner. Busybox's insmod utility has been reported to
    186     work under ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC, S390,
    187     SH3/4/5, Sparc, v850e, and x86_64. Anything else probably won't work.
    188    
    189     The module loading mechanism for the 2.6 kernel is much more generic, and
    190     we believe 2.6.x kernel module loading support should work on all
    191     architectures supported by the kernel.
    192    
    193     ----------------
    194    
    195     Please feed suggestions, bug reports, insults, and bribes back to the busybox
    196     maintainer:
    197     Denis Vlasenko
    198     <vda.linux@googlemail.com>