From 4aca87515a5083ae0e31ce3177189fd43b6d05ac Mon Sep 17 00:00:00 2001
From: Andreas Baumann
-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 /dev, /etc, and a kernel.
-
-
-BusyBox is now maintained by
-
-Erik Andersen, and its ongoing development is being sponsored by
-Lineo.
-
-BusyBox is licensed under the
-GNU GENERAL PUBLIC LICENSE.
-
-
-
- Because everybody loves screenshots, a screenshot of BusyBox
-is now available right here.
-
-
-
-
- Those wanting an easy way to test the 0.60.0 release with uClibc can
- use User-Mode Linux
- to give it a try by downloading and compiling
- buildroot.tar.gz.
- You don't have to be root or reboot your machine to run test this way.
- Preconfigured User-Mode Linux kernel source is also on oss.lineo.com.
-
- Another cool thing is the nifty
- BusyBox Tutorial contributed by K Computing. This requires
- a ShockWave plugin (or standalone viewer), so you may want to grab the
- the GPLed shockwave viewer from here
- to view the tutorial.
-
-
- Finally, In case you didn't notice anything odd about the
- version number of this release, let me point out that this release
- is not 0.53, because I bumped the version number up a
- bit. This reflects the fact that this release is intended to form
- a new stable BusyBox release series. If you need to rely on a
- stable version of BusyBox, you should plan on using the stable
- 0.60.x series. If bugs show up then I will release 0.60.1, then
- 0.60.2, etc... This is also intended to deal with the fact that
- the BusyBox build system will be getting a major overhaul for the
- next release and I don't want that to break products that people
- are shipping. To avoid that, the new build system will be
- released as part of a new BusyBox development series that will
- have some not-yet-decided-on odd version number. Once things
- stabilize and the new build system is working for everyone, then
- I will release that as a new stable release series.
-
-
- The
- changelog has all
- the details. As usual BusyBox 0.60.0 can be downloaded from
- ftp://oss.lineo.com/busybox.
- Have Fun!
-
-
-
-
- The
- changelog covers
- some of the more obvious details, but there are many many things that
- are not mentioned, but have been improved in subtle ways. As usual,
- BusyBox 0.52 can be downloaded from
- ftp://oss.lineo.com/busybox.
- Have Fun!
-
-
-
- (Note that while the number of applets in Busybox has increased, you
- can still configure Busybox to be as small as you want by selectively
- turning off whichever applets you don't need.)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- I know of the following products and/or projects that use BusyBox --
-listed in the order I happen to add them to the web page:
-
- Do you use BusyBox? I'd love to know about it and I'd be happy to link to
-you.
-
-
-
-
-
-
-
- There are a number of improvements in this release as well. For
- one thing, the wget applet is greatly improved. Dmitry Zakharov
- added FTP support, and Laurence Anderson make wget fully RFC
- compliant for HTTP 1.1. The mechanism for including utility
- functions in previous releases was clumsy and error prone. Now
- all utility functions are part of a new libbb library, which makes
- maintaining utility functions much simpler. And BusyBox now
- compiles on itanium systems (thanks to the Debian itanium porters
- for letting me use their system!).
-
- You can read the
- changelog for
- complete details. BusyBox 0.51 can be downloaded from
- ftp://oss.lineo.com/busybox.
- Have Fun!
-
-
- Because you asked for it, we have made available a Busybox boot floppy
- image. Here's how you use it:
-
- If you want to look at the contents of the initrd image, do this:
-
-
- lash (the busybox shell) is still with us, fixed up a bit so it
- now behaves itself quite nicely. It really is quite usable as
- long as you don't expect it to provide Bourne shell grammer.
- Standard things like pipes, redirects, command line editing, and
- environment variable expansion work great. But we have found that
- this shell, while very usable, does not provide an extensible
- framework for adding in full Bourne shell behavior. So the first order of
- business as we begin working on the next BusyBox release will be to merge in the new shell
- currently in progress at
- Larry Doolittle's website.
-
-
-
-
- Special thanks go out to Matt Kraai and Larry Doolittle for all their
- work on this release, and for keeping on top of things while I've been
- out of town.
-
- Special Note
-
-
- The curious can get a list of some of the more interesting changes by reading
- the changelog.
-
- Many thanks go out to the many many people that have contributed to
- this release, especially Matt Kraai, Larry Doolittle, and Kent Robotti.
-
-
- Also, some exciting infrastructure news! Busybox now has its own
- mailing list,
- publically browsable
- CVS tree,
- anonymous
- CVS access, and
- for those that are actively contributing there is even
- CVS write access.
- I think this will be a huge help to the ongoing development of BusyBox.
-
- Also, for the curious, there is no 0.44 release. Somehow 0.44 got announced
- a few weeks ago prior to its actually being released. To avoid any confusion
- we are just skipping 0.44.
-
- Many thanks go out to the many people that have contributed to this release
- of BusyBox (esp. Pavel Roskin)!
-
-
-
- Karl M. Hegbloom has created a
- fix for the problem.
- Thanks Karl!
-
-
-
- Many thanks go out to the fine people that have helped by submitting patches
- and bug reports; particularly instrumental in helping for this release were
- Karl Hegbloom, Pavel Roskin, Friedrich Vedder, Emanuele Caratti,
- Bob Tinsley, Nicolas Pitre, Avery Pennarun, Arne Bernin, John Beppu, and Jim Gleason.
- There were others so if I somehow forgot to mention you, I'm very sorry.
-
-
- You can grab BusyBox 0.43 tarballs here.
-
-
- The pre-release can be found here.
- Please let me know ASAP if you find any bugs.
-
-
- Anyway, I'm glad to note that despite the much-faster-than-we-were-expecting
- labor, both Shaunalei and our new baby boy are doing wonderfully.
-
- So now that I am done with my excuse for the slow release cycle...
- Progress on the next release of BusyBox has been slow but steady. I expect
- to have a release sometime during the first week of April. This release will
- include a number of important changes, including the addition of a shell, a
- re-write of tar (to accommodate the Linux Router Project), and syslogd can now
- accept multiple concurrent connections, fixing lots of unexpected blocking
- problems.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- B u s y B o x
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 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.
- Screenshot
-
-Mailing List Information
-BusyBox now has a mailing list!
-To subscribe, go and visit this page.
-
-
-
-
-
-
-
- Latest News
-
-
-
-
-
-
-
-
-
-
-
-
- I am very pleased to announce the immediate availability of
- BusyBox 0.60.0. I have personally tested this release with libc5, glibc,
- and uClibc on
- x86, ARM, and powerpc using linux 2.2 and 2.4, and I know a number
- of people using it on everything from ia64 to m68k with great success.
- Everything seems to be working very nicely now, so getting a nice
- stable bug-free(tm) release out seems to be in order. This releases fixes
- a memory leak in syslogd, a number of bugs in the ash and msh shells, and
- cleans up a number of things.
-
-
-
- I am very pleased to announce the immediate availability of
- BusyBox 0.52 (the "new-and-improved rock-solid release"). This
- release is the result of many hours of work and has tons
- of bugfixes, optimizations, and cleanups. This release adds
- several new applets, including several new shells (such as hush, msh,
- and ash).
-
-
- The illustrious Larry Doolittle has made a PostScript chart of the growth
- of the Busybox tarball size over time. It is available for downloading /
- viewing right here.
-
-
- For the old news, visit the old news page.
-
-
-
- Download
-
-
-
-
-
-
-
-
-
-
-
-
- Documentation
-
-
-Current documentation for BusyBox includes:
-
-
-
-
-
-
-
-
-
-
- Important Links
-
-
-
-
-
-
-
-
-
-
-
-
- The original idea for BusyBox, and all versions up to 0.26 were written
- by Bruce Perens. This is his BusyBox website.
-
-
-
- Products/Projects Using BusyBox
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Mail all comments, insults, suggestions and bribes to
- Erik Andersen
-
-
- The Busybox logo is copyright 1999,2000,2001, Erik Andersen.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- B u s y B o x
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Older BusyBox News
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- BusyBox 0.51 (the "rock-solid release") is now out there. This
- release adds only 2 new applets: env and vi. The vi applet,
- contributed by Sterling Huxley, is very functional, and is only
- 22k. This release fixes 3 critical bugs in the 0.50 release.
- There were 2 potential segfaults in lash (the busybox shell) in
- the 0.50 release which are now fixed. Another critical bug in
- 0.50 which is now fixed: syslogd from 0.50 could potentially
- deadlock the init process and thereby break your entire system.
-
-
-
-
-
- mount ./busybox.floppy.img /mnt -o loop -t msdos
- cp /mnt/initrd.gz /tmp
- umount /mnt
- gunzip /tmp/initrd.gz
- mount /tmp/initrd /mnt -o loop -t minix
-
-
-
-
-
- This release adds several new applets including ifconfig, route, pivot_root, stty,
- and tftp, and also fixes tons of bugs. Tab completion in the
- shell is now working very well, and the shell's environment variable
- expansion was fixed. Tons of other things were fixed or made
- smaller. For a fairly complete overview, see the
- changelog.
-
-
- Several new applets, lots of bug fixes, cleanups, and many smaller
- things made nicer. Several cleanups and improvements to the shell.
- For a list of the most interesting changes
- you might want to look at the changelog.
-
-
- BusyBox 0.49 was supposed to have replaced lash, the BusyBox
- shell, with a new shell that understands full Bourne shell/Posix shell grammer.
- Well, that simply didn't happen in time for this release. A new
- shell that will eventually replace lash is already under
- construction. This new shell is being developed by Larry
- Doolittle, and could use all of our help. Please see the work in
- progress on Larry's website
- and help out if you can. This shell will be included in the next
- release of BusyBox.
-
-
- This release fixes lots and lots of bugs. This has had some very
- rigorous testing, and looks very, very clean. The usual tar
- update of course: tar no longer breaks hardlinks, tar -xzf is
- optionally supported, and the LRP folks will be pleased to know
- that 'tar -X' and 'tar --exclude' are both now in. Applets are
- now looked up using a binary search making lash (the busybox
- shell) much faster. For the new debian-installer (for Debian
- woody) a .udeb can now be generated.
-
-
- This release fixes lots of bugs (including an ugly bug in 0.46
- syslogd that could fork-bomb your system). Added several new
- apps: rdate, wget, getopt, dos2unix, unix2dos, reset, unrpm,
- renice, xargs, and expr. syslogd now supports network logging.
- There are the usual tar updates. Most apps now use getopt for
- more correct option parsing.
- See the changelog
- for complete details.
-
-
-
-
- This release fixes several bugs (including a ugly bug in tar,
- and fixes for NFSv3 mount support). Added a dumpkmap to allow
- people to dump a binary keymaps for use with 'loadkmap', and a
- completely reworked 'grep' and 'sed' which should behave better.
- BusyBox shell can now also be used as a login shell.
- See the changelog
- for complete details.
-
-
-
-
- This release has been slow in coming, but is very solid at this
- point. BusyBox now supports libc5 as well as GNU libc. This
- release provides the following new apps: cut, tr, insmod, ar,
- mktemp, setkeycodes, md5sum, uuencode, uudecode, which, and
- telnet. There are bug fixes for just about every app as well (see
- the changelog for
- details).
-
- Turns out that there was still a bug in busybox syslogd.
- For example, with the following test app:
-
- #include <syslog.h>
-
- int do_log(char* msg, int delay)
- {
- openlog("testlog", LOG_PID, LOG_DAEMON);
- while(1) {
- syslog(LOG_ERR, "%s: testing one, two, three\n", msg);
- sleep(delay);
- }
- closelog();
- return(0);
- };
-
- int main(void)
- {
- if (fork()==0)
- do_log("A", 2);
- do_log("B", 3);
- }
-
- it should be logging stuff from both "A" and "B". As released in 0.43 only stuff
- from "A" would have been logged. This means that if init tries to log something
- while say ppp has the syslog open, init would block (which is bad, bad, bad).
-
- I have finally gotten everything into a state where I feel pretty
- good about things. This is definitely the most stable, solid release
- so far. A lot of bugs have been fixed, and the following new apps
- have been added: sh, basename, dirname, killall, uptime,
- freeramdisk, tr, echo, test, and usleep. Tar has been completely
- rewritten from scratch. Bss size has also been greatly reduced.
- More details are available in the
- changelog.
- Oh, and as a special bonus, I wrote some fairly comprehensive
- documentation, complete with examples and full usage information.
-
-
- Unfortunately, I have not yet finished all the things I want to
- do for BusyBox 0.43, so I am posting this pre-release for people
- to poke at. This contains my complete rewrite of tar, which now weighs in at
- 5k (7k with all options turned on) and works for reading and writing
- tarballs (which it does correctly for everything I have been able to throw
- at it). Tar also (optionally) supports the "--exclude" option (mainly because
- the Linux Router Project folks asked for it). This also has a pre-release
- of the micro shell I have been writing. This pre-release should be stable
- enough for production use -- it just isn't a release since I have some structural
- changes I still want to make.
-
- I am pleased to announce that on Tuesday March 28th at 5:48pm, weighing in at 7
- lbs. 12 oz, Micah Erik Andersen was born at LDS Hospital here in Salt Lake City.
- He was born in the emergency room less then 5 minutes after we arrived -- and
- it was such a relief that we even made it to the hospital at all. Despite the
- fact that I was driving at an amazingly unlawful speed and honking at everybody
- and thinking decidedly unkind thoughts about the people in our way, my wife
- (inconsiderate of my feelings and complete lack of medical training) was lying
- down in the back seat saying things like "I think I need to start pushing now"
- (which she then proceeded to do despite my best encouraging statements to the
- contrary).
-
-
- This is the most solid BusyBox release so far. Many, many
- bugs have been fixed. See the
-changelog for details.
-
- Of particular interest, init will now cleanly unmount
- filesystems on reboot, cp and mv have been rewritten and
- behave much better, and mount and umount no longer leak
- loop devices. Many thanks go out to Randolph Chung,
- Karl M. Hegbloom, Taketoshi Sano, and Pavel Roskin for
- their hard work on this release of BusyBox. Please pound
- on it and let me know if you find any bugs.
-
-
-
- This release includes bugfixes to cp, mv, logger, true, false,
- mkdir, syslogd, and init. New apps include wc, hostid,
- logname, tty, whoami, and yes. New features include loop device
- support in mount and umount, and better TERM handling by init.
- The changelog can be found here.
-
-
-
- This release includes bugfixes to init (now includes inittab support),
- syslogd, head, logger, du, grep, cp, mv, sed, dmesg, ls, kill, gunzip, and mknod.
- New apps include sort, uniq, lsmod, rmmod, fbset, and loadacm.
- In particular, this release fixes an important bug in tar which
- in some cases produced serious security problems.
- As always, the changelog can be found here.
-
-
- I have received permission from Bruce Perens (the original author of BusyBox)
- to set up this site as the new primary website for BusyBox. This website
- will always contain pointers to the latest and greatest, and will also
- contain the latest documentation on how to use BusyBox, what it can do,
- what arguments its apps support, etc.
-
-
- This release includes fixes to init, reboot, halt, kill, and ls, and contains
- the new apps ping, hostname, mkfifo, free, tail, du, tee, and head. A full
- changelog can be found here.
-
- This release includes fixes to tar, cat, ls, dd, rm, umount, find, df,
- and make install, and includes new apps syslogd/klogd and logger.
-
-
-
-
- Important Links
-
-
-
-
-
-
-
-
-
-
-
-
-
- The original idea for BusyBox, and all versions up to 0.26 were written
- by Bruce Perens. This is his BusyBox website.
-
-
- Mail all comments, insults, suggestions and bribes to
- Erik Andersen - The Busybox logo is copyright 1999,2000, Erik Andersen. - - |
-
- - - | - -- - | - -- - | - -- | - -- - | - -
-
-
-- - -$ ./busybox -BusyBox v0.49 (2001.01.30-17:35+0000) multi-call binary -- GPL2 - -Usage: busybox [function] [arguments]... - or: [function] [arguments]... - - BusyBox is a multi-call binary that combines many common Unix - utilities into a single executable. Most people will create a - link to busybox for each function they wish to use, and BusyBox - will act like whatever it was invoked as. - -Currently defined functions: - basename, busybox, cat, chgrp, chmod, chown, chroot, chvt, clear, - cp, cut, date, dd, df, dirname, dmesg, du, echo, false, find, - free, grep, gunzip, gzip, halt, head, id, init, kill, killall, - ln, logger, ls, lsmod, mkdir, mknod, mkswap, more, mount, mv, - poweroff, ps, pwd, reboot, reset, rm, rmdir, sed, sh, sleep, sort, - swapoff, swapon, sync, syslogd, tail, tar, touch, true, tty, umount, - uname, uniq, uptime, wc, which, whoami, xargs, yes, zcat - -$ - -- - |
If you just want to try out busybox without installing it, download the + tarball, extract it, run "make defconfig", and then run "make". +
++ This will create a busybox binary with almost all features enabled. To try + out a busybox applet, type "./busybox [appletname] [options]", for + example "./busybox ls -l" or "./busybox cat LICENSE". Type "./busybox" + to see a command list, and "busybox appletname --help" to see a brief + usage message for a given applet. +
++ BusyBox uses the name it was invoked under to determine which applet is + being invoked. (Try "mv busybox ls" and then "./ls -l".) Installing + busybox consists of creating symlinks (or hardlinks) to the busybox + binary for each applet in busybox, and making sure these links are in + the shell's command $PATH. The special applet name "busybox" (or with + any optional suffix, such as "busybox-static") uses the first argument + to determine which applet to run, as shown above. +
++ BusyBox also has a feature called the + "standalone shell", where the busybox + shell runs any built-in applets before checking the command path. This + feature is also enabled by "make allyesconfig", and to try it out run + the command line "PATH= ./busybox ash". This will blank your command path + and run busybox as your command shell, so the only commands it can find + (without an explicit path such as /bin/ls) are the built-in busybox ones. + This is another good way to see what's built into busybox. + 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. + (So if you set it to /proc/self/exe, and happen to be able to chroot into + your rootfs, you must mount /proc beforehand.) +
++ A typical indication that you set CONFIG_BUSYBOX_EXEC_PATH to proc but + forgot to mount proc is: +
+$ /bin/echo $PATH +/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11 +$ echo $PATH +/bin/sh: echo: not found ++ +
Busybox is configured similarly to the linux kernel. Create a default + configuration and then run "make menuconfig" to modify it. The end + result is a .config file that tells the busybox build process what features + to include. So instead of "./configure; make; make install" the equivalent + busybox build would be "make defconfig; make; make install". +
+ +Busybox configured with all features enabled is a little under a megabyte + dynamically linked on x86. To create a smaller busybox, configure it with + fewer features. Individual busybox applets cost anywhere from a few + hundred bytes to tens of kilobytes. Disable unneeded applets to save, + space, using menuconfig. +
+ +The most important busybox configurators are:
+ +make defconfig - Create the maximum "sane" configuration. This +enables almost all features, minus things like debugging options and features +that require changes to the rest of the system to work (such as selinux or +devfs device names). Use this if you want to start from a full-featured +busybox and remove features until it's small enough.
make allnoconfig - Disable everything. This creates a tiny version +of busybox that doesn't do anything. Start here if you know exactly what +you want and would like to select only those features.
make menuconfig - Interactively modify a .config file through a +multi-level menu interface. Use this after one of the previous two.
Some other configuration options are:
+make oldconfig - Update an old .config file for a newer version +of busybox.
make allyesconfig - Select absolutely everything. This creates +a statically linked version of busybox full of debug code, with dependencies on +selinux, using devfs names... This makes sure everything compiles. Whether +or not the result would do anything useful is an open question.
make allbareconfig - Select all applets but disable all sub-features +within each applet. More build coverage testing.
make randconfig - Create a random configuration for test purposes.
Menuconfig modifies your .config file through an interactive menu where you can enable or disable + busybox features, and get help about each feature. + +
+ To build a smaller busybox binary, run "make menuconfig" and disable the + features you don't need. (Or run "make allnoconfig" and then use + menuconfig to add just the features you need. Don't forget to recompile + with "make" once you've finished configuring.) +
+ ++ To build busybox with a cross-compiler, specify CROSS_COMPILE=<prefix>. +
++ CROSS_COMPILE specifies the prefix used for all executables used + during compilation. Only gcc and related binutils executables + are prefixed with $(CROSS_COMPILE) in the makefiles. + CROSS_COMPILE can be set on the command line: +
++ make CROSS_COMPILE=arm-linux-uclibcgnueabi- ++
+ Alternatively CROSS_COMPILE can be set in the environment. + Default value for CROSS_COMPILE is not to prefix executables. +
++ To store the cross-compiler in your .config, set the variable + CONFIG_CROSS_COMPILER_PREFIX accordingly in menuconfig or by + editing the .config file. +
+ ++ BusyBox is a package that replaces a dozen standard packages, but it is + not by itself a complete bootable system. Building an entire Linux + distribution from source is a bit beyond the scope of this FAQ, but it + understandably keeps cropping up on the mailing list, so here are some + pointers. +
++ Start by learning how to strip a working system down to the bare essentials + needed to run one or two commands, so you know what it is you actually + need. An excellent practical place to do + this is the Linux + BootDisk Howto, or for a more theoretical approach try + From + PowerUp to Bash Prompt. +
++ To learn how to build a working Linux system entirely from source code, + the place to go is the Linux + From Scratch project. They have an entire book of step-by-step + instructions you can + read online + or + download. + Be sure to check out the other sections of their main page, including + Beyond Linux From Scratch, Hardened Linux From Scratch, their Hints + directory, and their LiveCD project. (They also have mailing lists which + are better sources of answers to Linux-system building questions than + the busybox list.) +
++ If you want an automated yet customizable system builder which produces + a BusyBox and uClibc based system, try + buildroot, which is + another project by the maintainer of the uClibc (Erik Andersen). + Download the tarball, extract it, unset CC, make. + For more instructions, see the website. +
+ ++ Full functionality requires Linux 2.4.x or better. (Earlier versions may + still work, but are no longer regularly tested.) A large fraction of the + code should run on just about anything. While the current code is fairly + Linux specific, it should be fairly easy to port the majority of the code + to support, say, FreeBSD or Solaris, or Mac OS X, or even Windows (if you + are into that sort of thing). +
+ ++ BusyBox in general will build on any architecture supported by gcc. + Kernel module loading for 2.4 Linux kernels is currently + limited to ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC, + S390, SH3/4/5, Sparc, v850e, and x86_64 for 2.4.x kernels. +
++ With 2.6.x kernels, module loading support should work on all architectures. +
+ ++ On Linux, BusyBox releases are tested against uClibc (0.9.27 or later) and + glibc (2.2 or later). Both should provide full functionality with busybox, + and if you find a bug we want to hear about it. +
++ Linux-libc5 is no longer maintained (and has no known advantages over + uClibc), dietlibc is known to have numerous unfixed bugs, and klibc is + missing too many features to build BusyBox. If you require a small C + library for Linux, the busybox developers recommend uClibc. +
++ Some BusyBox applets have been built and run under a combination + of newlib and libgloss (see + this thread). + This is still experimental, but may be supported in a future release. +
+ ++ Yes. As long as you fully comply + with the generous terms of the GPL BusyBox license you can ship BusyBox + as part of the software on your device. +
+ ++ we maintain such a list on this site! +
+ ++ You have not paid us a single cent and yet you still have the product of + many years of our work. We are not your slaves! We work on BusyBox + because we find it useful and interesting. If you go off flaming us, we + will ignore you. + +
+ If you find that you need help with BusyBox, you can ask for help on the + BusyBox mailing list at busybox@busybox.net.
+ +In addition to the mailing list, Erik Andersen (andersee), Manuel Nova + (mjn3), Rob Landley (landley), Mike Frysinger (SpanKY), + Bernhard Reutner-Fischer (blindvt), and other long-time BusyBox developers + are known to hang out on the uClibc IRC channel: #uclibc on + irc.freenode.net. There is a + web archive of + daily logs of the #uclibc IRC channel going back to 2002. +
+ ++ Please do not send private email to Rob, Erik, Manuel, or the other + BusyBox contributors asking for private help unless you are planning on + paying for consulting services. +
+ ++ When we answer questions on the BusyBox mailing list, it helps everyone + since people with similar problems in the future will be able to get help + by searching the mailing list archives. Private help is reserved as a paid + service. If you need to use private communication, or if you are serious + about getting timely assistance with BusyBox, you should seriously consider + paying for consulting services. +
+ ++ Yes we are. The easy way to sponsor a new feature is to post an offer on + the mailing list to see who's interested. You can also email the project's + maintainer and ask them to recommend someone. +
+ ++ If you simply need help with using or configuring BusyBox, please submit a + detailed description of your problem to the BusyBox mailing list at busybox@busybox.net. + Please do not send email to individual developers asking + for private help unless you are planning on paying for consulting services. + When we answer questions on the BusyBox mailing list, it helps everyone, + while private answers help only you... +
+ ++ Bug reports and new feature patches sometimes get lost when posted to the + mailing list, because the developers of BusyBox are busy people and have + only so much they can keep in their brains at a time. You can post a + polite reminder after 2-3 days without offending anybody. If that doesn't + result in a solution, please use the + BusyBox Bug + and Patch Tracking System to submit a detailed explanation and we'll + get to it as soon as we can. +
+ ++ Note that bugs entered into the bug system without being mentioned on the + mailing list first may languish there for months before anyone even notices + them. We generally go through the bug system when preparing for new + development releases, to see what fell through the cracks while we were + off writing new features. (It's a fast/unreliable vs slow/reliable thing. + Saves retransits, but the latency sucks.) +
+ +Variants of this one get asked a lot.
+ +The purpose of the BusyBox mailing list is to develop and improve BusyBox, +and we're happy to respond to our users' needs. But if you're coming to the +list for free tech support we're going to ask you to upgrade to a current +version before we try to diagnose your problem.
+ +If you're building BusyBox 0.50 with uClibc 0.9.19 and gcc 1.27 there's a +fairly large chance that whatever problem you're seeing has already been fixed. +To get that fix, all you have to do is upgrade to a newer version. If you +don't at least _try_ that, you're wasting our time.
+ +The volunteers are happy to fix any bugs you point out in the current +versions because doing so helps everybody and makes the project better. We +want to make the current version work for you. But diagnosing, debugging, and +backporting fixes to old versions isn't something we do for free, because it +doesn't help anybody but you. The cost of volunteer tech support is using a +reasonably current version of the project.
+ +If you don't want to upgrade, you have the complete source code and thus +the ability to fix it yourself, or hire a consultant to do it for you. If you +got your version from a vendor who still supports the older version, they can +help you. But there are limits as to what the volunteers will feel obliged to +do for you.
+ +As a rule of thumb, volunteers will generally answer polite questions about +a given version for about three years after its release before it's so old +we don't remember the answer off the top of our head. And if you want us to +put any _effort_ into tracking it down, we want you to put in a little effort +of your own by confirming it's still a problem with the current version. It's +also hard for us to fix a problem of yours if we can't reproduce it because +we don't have any systems running an environment that old.
+ +A consultant will happily set up a special environment just to reproduce +your problem, and you can always ask on the list if any of the developers +have consulting rates.
+ ++ Init is the first program that runs, so it might be that no programs are + working on your new system because of a problem with your cross-compiler, + kernel, console settings, shared libraries, root filesystem... To rule all + that out, first build a statically linked version of the following "hello + world" program with your cross compiler toolchain: +
++#include <stdio.h> + +int main(int argc, char *argv) +{ + printf("Hello world!\n"); + sleep(999999999); +} ++ +
+ Now try to boot your device with an "init=" argument pointing to your + hello world program. Did you see the hello world message? Until you + do, don't bother messing with busybox init. +
+ ++ Once you've got it working statically linked, try getting it to work + dynamically linked. Then read the FAQ entry How + do I build a BusyBox-based system?, and the + documentation for BusyBox + init. +
+ ++ Configuring Busybox depends on a recent version of sed. Older + distributions (Red Hat 7.2, Debian 3.0) may not come with a + usable version. Luckily BusyBox can use its own sed to configure itself, + although this leads to a bit of a chicken and egg problem. + You can work around this by hand-configuring busybox to build with just + sed, then putting that sed in your path to configure the rest of busybox + with, like so: +
+ ++ tar xvjf sources/busybox-x.x.x.tar.bz2 + cd busybox-x.x.x + make allnoconfig + make include/bb_config.h + echo "CONFIG_SED=y" >> .config + echo "#undef ENABLE_SED" >> include/bb_config.h + echo "#define ENABLE_SED 1" >> include/bb_config.h + make + mv busybox sed + export PATH=`pwd`:"$PATH" ++ +
Then you can run "make defconfig" or "make menuconfig" normally.
+ ++ Job control will be turned off since your shell can not obtain a controlling + terminal. This typically happens when you run your shell on /dev/console. + The kernel will not provide a controlling terminal on the /dev/console + device. Your should run your shell on a normal tty such as tty1 or ttyS0 + and everything will work perfectly. If you REALLY want your shell + to run on /dev/console, then you can hack your kernel (if you are into that + sortof thing) by changing drivers/char/tty_io.c to change the lines where + it sets "noctty = 1;" to instead set it to "0". I recommend you instead + run your shell on a real console... +
+ +Busybox has nothing to do with the timezone. Please consult your libc +documentation. (http://google.com/search?q=uclibc+glibc+timezone).
+ +Busybox aims to be the smallest and simplest correct implementation of the +standard Linux command line tools. First and foremost, this means the +smallest executable size we can manage. We also want to have the simplest +and cleanest implementation we can manage, be standards +compliant, minimize run-time memory usage (heap and stack), run fast, and +take over the world.
+ +Busybox is like a swiss army knife: one thing with many functions. +The busybox executable can act like many different programs depending on +the name used to invoke it. Normal practice is to create a bunch of symlinks +pointing to the busybox binary, each of which triggers a different busybox +function. (See getting started in the +FAQ for more information on usage, and the +busybox documentation for a list of symlink names and what they do.) + +
The "one binary to rule them all" approach is primarily for size reasons: a +single multi-purpose executable is smaller then many small files could be. +This way busybox only has one set of ELF headers, it can easily share code +between different apps even when statically linked, it has better packing +efficiency by avoding gaps between files or compression dictionary resets, +and so on.
+ +Work is underway on new options such as "make standalone" to build separate +binaries for each applet, and a "libbb.so" to make the busybox common code +available as a shared library. Neither is ready yet at the time of this +writing.
+ + + +The directory "applets" contains the busybox startup code (applets.c and +busybox.c), and several subdirectories containing the code for the individual +applets.
+ +Busybox execution starts with the main() function in applets/busybox.c, +which sets the global variable applet_name to argv[0] and calls +run_applet_and_exit() in applets/applets.c. That uses the applets[] array +(defined in include/busybox.h and filled out in include/applets.h) to +transfer control to the appropriate APPLET_main() function (such as +cat_main() or sed_main()). The individual applet takes it from there.
+ +This is why calling busybox under a different name triggers different +functionality: main() looks up argv[0] in applets[] to get a function pointer +to APPLET_main().
+ +Busybox applets may also be invoked through the multiplexor applet +"busybox" (see busybox_main() in libbb/appletlib.c), and through the +standalone shell (grep for STANDALONE_SHELL in applets/shell/*.c). +See getting started in the +FAQ for more information on these alternate usage mechanisms, which are +just different ways to reach the relevant APPLET_main() function.
+ +The applet subdirectories (archival, console-tools, coreutils, +debianutils, e2fsprogs, editors, findutils, init, loginutils, miscutils, +modutils, networking, procps, shell, sysklogd, and util-linux) correspond +to the configuration sub-menus in menuconfig. Each subdirectory contains the +code to implement the applets in that sub-menu, as well as a Config.in +file defining that configuration sub-menu (with dependencies and help text +for each applet), and the makefile segment (Makefile.in) for that +subdirectory.
+ +The run-time --help is stored in usage_messages[], which is initialized at +the start of applets/applets.c and gets its help text from usage.h. During the +build this help text is also used to generate the BusyBox documentation (in +html, txt, and man page formats) in the docs directory. See +adding an applet to busybox for more +information.
+ +Most non-setup code shared between busybox applets lives in the libbb +directory. It's a mess that evolved over the years without much auditing +or cleanup. For anybody looking for a great project to break into busybox +development with, documenting libbb would be both incredibly useful and good +experience.
+ +Common themes in libbb include allocation functions that test +for failure and abort the program with an error message so the caller doesn't +have to test the return value (xmalloc(), xstrdup(), etc), wrapped versions +of open(), close(), read(), and write() that test for their own failures +and/or retry automatically, linked list management functions (llist.c), +command line argument parsing (getopt32.c), and a whole lot more.
+ ++ To conserve bytes it's good to know where they're being used, and the + size of the final executable isn't always a reliable indicator of + the size of the components (since various structures are rounded up, + so a small change may not even be visible by itself, but many small + savings add up). +
+ +The busybox Makefile builds two versions of busybox, one of which + (busybox_unstripped) has extra information that various analysis tools + can use. (This has nothing to do with CONFIG_DEBUG, leave that off + when trying to optimize for size.) +
+ +The "make bloatcheck" option uses Matt Mackall's bloat-o-meter + script to compare two versions of busybox (busybox_unstripped vs + busybox_old), and report which symbols changed size and by how much. + To use it, first build a base version with "make baseline". + (This creates busybox_old, which should have the original sizes for + comparison purposes.) Then build the new version with your changes + and run "make bloatcheck" to see the size differences from the old + version. +
++ The first line of output has totals: how many symbols were added or + removed, how many symbols grew or shrank, the number of bytes added + and number of bytes removed by these changes, and finally the total + number of bytes difference between the two files. The remaining + lines show each individual symbol, the old and new sizes, and the + increase or decrease in size (which results are sorted by). +
++ The "make sizes" option produces raw symbol size information for + busybox_unstripped. This is the output from the "nm --size-sort" + command (see "man nm" for more information), and is the information + bloat-o-meter parses to produce the comparison report above. For + defconfig, this is a good way to find the largest symbols in the tree + (which is a good place to start when trying to shrink the code). To + take a closer look at individual applets, configure busybox with just + one applet (run "make allnoconfig" and then switch on a single applet + with menuconfig), and then use "make sizes" to see the size of that + applet's components. +
++ The "showasm" command (in the scripts directory) produces an assembly + dump of a function, providing a closer look at what changed. Try + "scripts/showasm busybox_unstripped" to list available symbols, and + "scripts/showasm busybox_unstripped symbolname" to see the assembly + for a sepecific symbol. +
+ +To add a new applet to busybox, first pick a name for the applet and +a corresponding CONFIG_NAME. Then do this:
+ +The standard we're paying attention to is the "Shell and Utilities" +portion of the Open +Group Base Standards (also known as the Single Unix Specification version +3 or SUSv3). Note that paying attention isn't necessarily the same thing as +following it.
+ +SUSv3 doesn't even mention things like init, mount, tar, or losetup, nor +commonly used options like echo's '-e' and '-n', or sed's '-i'. Busybox is +driven by what real users actually need, not the fact the standard believes +we should implement ed or sccs. For size reasons, we're unlikely to include +much internationalization support beyond UTF-8, and on top of all that, our +configuration menu lets developers chop out features to produce smaller but +very non-standard utilities.
+ +Also, Busybox is aimed primarily at Linux. Unix standards are interesting +because Linux tries to adhere to them, but portability to dozens of platforms +is only interesting in terms of offering a restricted feature set that works +everywhere, not growing dozens of platform-specific extensions. Busybox +should be portable to all hardware platforms Linux supports, and any other +similar operating systems that are easy to do and won't require much +maintenance.
+ +In practice, standards compliance tends to be a clean-up step once an +applet is otherwise finished. When polishing and testing a busybox applet, +we ensure we have at least the option of full standards compliance, or else +document where we (intentionally) fall short.
+ +Busybox is a Linux project, but that doesn't mean we don't have to worry +about portability. First of all, there are different hardware platforms, +different C library implementations, different versions of the kernel and +build toolchain... The file "include/platform.h" exists to centralize and +encapsulate various platform-specific things in one place, so most busybox +code doesn't have to care where it's running.
+ +To start with, Linux runs on dozens of hardware platforms. We try to test +each release on x86, x86-64, arm, power pc, and mips. (Since qemu can handle +all of these, this isn't that hard.) This means we have to care about a number +of portability issues like endianness, word size, and alignment, all of which +belong in platform.h. That header handles conditional #includes and gives +us macros we can use in the rest of our code. At some point in the future +we might grow a platform.c, possibly even a platform subdirectory. As long +as the applets themselves don't have to care.
+ +On a related note, we made the "default signedness of char varies" problem +go away by feeding the compiler -funsigned-char. This gives us consistent +behavior on all platforms, and defaults to 8-bit clean text processing (which +gets us halfway to UTF-8 support). NOMMU support is less easily separated +(see the tips section later in this document), but we're working on it.
+ +Another type of portability is build environments: we unapologetically use +a number of gcc and glibc extensions (as does the Linux kernel), but these have +been picked up by packages like uClibc, TCC, and Intel's C Compiler. As for +gcc, we take advantage of newer compiler optimizations to get the smallest +possible size, but we also regression test against an older build environment +using the Red Hat 9 image at "http://busybox.net/downloads/qemu". This has a +2.4 kernel, gcc 3.2, make 3.79.1, and glibc 2.3, and is the oldest +build/deployment environment we still put any effort into maintaining. (If +anyone takes an interest in older kernels you're welcome to submit patches, +but the effort would probably be better spent +trimming +down the 2.6 kernel.) Older gcc versions than that are uninteresting since +we now use c99 features, although +tcc might be worth a +look.
+ +We also test busybox against the current release of uClibc. Older versions +of uClibc aren't very interesting (they were buggy, and uClibc wasn't really +usable as a general-purpose C library before version 0.9.26 anyway).
+ +Other unix implementations are mostly uninteresting, since Linux binaries +have become the new standard for portable Unix programs. Specifically, +the ubiquity of Linux was cited as the main reason the Intel Binary +Compatability Standard 2 died, by the standards group organized to name a +successor to ibcs2: the 86open +project. That project disbanded in 1999 with the endorsement of an +existing standard: Linux ELF binaries. Since then, the major players at the +time (such as AIX, Solaris, and +FreeBSD) +have all either grown Linux support or folded.
+ +The major exceptions are newcomer MacOS X, some embedded environments +(such as newlib+libgloss) which provide a posix environment but not a full +Linux environment, and environments like Cygwin that provide only partial Linux +emulation. Also, some embedded Linux systems run a Linux kernel but amputate +things like the /proc directory to save space.
+ +Supporting these systems is largely a question of providing a clean subset +of BusyBox's functionality -- whichever applets can easily be made to +work in that environment. Annotating the configuration system to +indicate which applets require which prerequisites (such as procfs) is +also welcome. Other efforts to support these systems (swapping #include +files to build in different environments, adding adapter code to platform.h, +adding more extensive special-case supporting infrastructure such as mount's +legacy mtab support) are handled on a case-by-case basis. Support that can be +cleanly hidden in platform.h is reasonably attractive, and failing that +support that can be cleanly separated into a separate conditionally compiled +file is at least worth a look. Special-case code in the body of an applet is +something we're trying to avoid.
+ +Various things busybox uses that aren't particularly well documented +elsewhere.
+ +Password fields in /etc/passwd and /etc/shadow are in a special format. +If the first character isn't '$', then it's an old DES style password. If +the first character is '$' then the password is actually three fields +separated by '$' characters:
++ $type$salt$encrypted_password ++ +
The "type" indicates which encryption algorithm to use: 1 for MD5 and 2 for SHA1.
+ +The "salt" is a bunch of ramdom characters (generally 8) the encryption +algorithm uses to perturb the password in a known and reproducible way (such +as by appending the random data to the unencrypted password, or combining +them with exclusive or). Salt is randomly generated when setting a password, +and then the same salt value is re-used when checking the password. (Salt is +thus stored unencrypted.)
+ +The advantage of using salt is that the same cleartext password encrypted +with a different salt value produces a different encrypted value. +If each encrypted password uses a different salt value, an attacker is forced +to do the cryptographic math all over again for each password they want to +check. Without salt, they could simply produce a big dictionary of commonly +used passwords ahead of time, and look up each password in a stolen password +file to see if it's a known value. (Even if there are billions of possible +passwords in the dictionary, checking each one is just a binary search against +a file only a few gigabytes long.) With salt they can't even tell if two +different users share the same password without guessing what that password +is and decrypting it. They also can't precompute the attack dictionary for +a specific password until they know what the salt value is.
+ +The third field is the encrypted password (plus the salt). For md5 this +is 22 bytes.
+ +The busybox function to handle all this is pw_encrypt(clear, salt) in +"libbb/pw_encrypt.c". The first argument is the clear text password to be +encrypted, and the second is a string in "$type$salt$password" format, from +which the "type" and "salt" fields will be extracted to produce an encrypted +value. (Only the first two fields are needed, the third $ is equivalent to +the end of the string.) The return value is an encrypted password in +/etc/passwd format, with all three $ separated fields. It's stored in +a static buffer, 128 bytes long.
+ +So when checking an existing password, if pw_encrypt(text, +old_encrypted_password) returns a string that compares identical to +old_encrypted_password, you've got the right password. When setting a new +password, generate a random 8 character salt string, put it in the right +format with sprintf(buffer, "$%c$%s", type, salt), and feed buffer as the +second argument to pw_encrypt(text,buffer).
+ +On systems that haven't got a Memory Management Unit, fork() is unreasonably +expensive to implement (and sometimes even impossible), so a less capable +function called vfork() is used instead. (Using vfork() on a system with an +MMU is like pounding a nail with a wrench. Not the best tool for the job, but +it works.)
+ +Busybox hides the difference between fork() and vfork() in +libbb/bb_fork_exec.c. If you ever want to fork and exec, use bb_fork_exec() +(which returns a pid and takes the same arguments as execve(), although in +this case envp can be NULL) and don't worry about it. This description is +here in case you want to know why that does what it does.
+ +Implementing fork() depends on having a Memory Management Unit. With an +MMU then you can simply set up a second set of page tables and share the +physical memory via copy-on-write. So a fork() followed quickly by exec() +only copies a few pages of the parent's memory, just the ones it changes +before freeing them.
+ +With a very primitive MMU (using a base pointer plus length instead of page +tables, which can provide virtual addresses and protect processes from each +other, but no copy on write) you can still implement fork. But it's +unreasonably expensive, because you have to copy all the parent process' +memory into the new process (which could easily be several megabytes per fork). +And you have to do this even though that memory gets freed again as soon as the +exec happens. (This is not just slow and a waste of space but causes memory +usage spikes that can easily cause the system to run out of memory.)
+ +Without even a primitive MMU, you have no virtual addresses. Every process +can reach out and touch any other process' memory, because all pointers are to +physical addresses with no protection. Even if you copy a process' memory to +new physical addresses, all of its pointers point to the old objects in the +old process. (Searching through the new copy's memory for pointers and +redirect them to the new locations is not an easy problem.)
+ +So with a primitive or missing MMU, fork() is just not a good idea.
+ +In theory, vfork() is just a fork() that writeably shares the heap and stack +rather than copying it (so what one process writes the other one sees). In +practice, vfork() has to suspend the parent process until the child does exec, +at which point the parent wakes up and resumes by returning from the call to +vfork(). All modern kernel/libc combinations implement vfork() to put the +parent to sleep until the child does its exec. There's just no other way to +make it work: the parent has to know the child has done its exec() or exit() +before it's safe to return from the function it's in, so it has to block +until that happens. In fact without suspending the parent there's no way to +even store separate copies of the return value (the pid) from the vfork() call +itself: both assignments write into the same memory location.
+ +One way to understand (and in fact implement) vfork() is this: imagine +the parent does a setjmp and then continues on (pretending to be the child) +until the exec() comes around, then the _exec_ does the actual fork, and the +parent does a longjmp back to the original vfork call and continues on from +there. (It thus becomes obvious why the child can't return, or modify +local variables it doesn't want the parent to see changed when it resumes.) + +
Note a common mistake: the need for vfork doesn't mean you can't have two +processes running at the same time. It means you can't have two processes +sharing the same memory without stomping all over each other. As soon as +the child calls exec(), the parent resumes.
+ +If the child's attempt to call exec() fails, the child should call _exit() +rather than a normal exit(). This avoids any atexit() code that might confuse +the parent. (The parent should never call _exit(), only a vforked child that +failed to exec.)
+ +(Now in theory, a nommu system could just copy the _stack_ when it forks +(which presumably is much shorter than the heap), and leave the heap shared. +Even with no MMU at all +In practice, you've just wound up in a multi-threaded situation and you can't +do a malloc() or free() on your heap without freeing the other process' memory +(and if you don't have the proper locking for being threaded, corrupting the +heap if both of you try to do it at the same time and wind up stomping on +each other while traversing the free memory lists). The thing about vfork is +that it's a big red flag warning "there be dragons here" rather than +something subtle and thus even more dangerous.)
+ +Busybox has special functions, bb_full_read() and bb_full_write(), to +check that all the data we asked for got read or written. Is this a real +world consideration? Try the following:
+ +while true; do echo hello; sleep 1; done | tee out.txt+ +
If tee is implemented with bb_full_read(), tee doesn't display output +in real time but blocks until its entire input buffer (generally a couple +kilobytes) is read, then displays it all at once. In that case, we _want_ +the short read, for user interface reasons. (Note that read() should never +return 0 unless it has hit the end of input, and an attempt to write 0 +bytes should be ignored by the OS.)
+ +As for short writes, play around with two processes piping data to each +other on the command line (cat bigfile | gzip > out.gz) and suspend and +resume a few times (ctrl-z to suspend, "fg" to resume). The writer can +experience short writes, which are especially dangerous because if you don't +notice them you'll discard data. They can also happen when a system is under +load and a fast process is piping to a slower one. (Such as an xterm waiting +on x11 when the scheduler decides X is being a CPU hog with all that +text console scrolling...)
+ +So will data always be read from the far end of a pipe at the +same chunk sizes it was written in? Nope. Don't rely on that. For one +counterexample, see rfc 896 +for Nagle's algorithm, which waits a fraction of a second or so before +sending out small amounts of data through a TCP/IP connection in case more +data comes in that can be merged into the same packet. (In case you were +wondering why action games that use TCP/IP set TCP_NODELAY to lower the latency +on their their sockets, now you know.)
+ +The downside of standard dynamic linking is that it results in self-modifying +code. Although each executable's pages are mmaped() into a process' address +space from the executable file and are thus naturally shared between processes +out of the page cache, the library loader (ld-linux.so.2 or ld-uClibc.so.0) +writes to these pages to supply addresses for relocatable symbols. This +dirties the pages, triggering copy-on-write allocation of new memory for each +processes' dirtied pages.
+ +One solution to this is Position Independent Code (PIC), a way of linking +a file so all the relocations are grouped together. This dirties fewer +pages (often just a single page) for each process' relocations. The down +side is this results in larger executables, which take up more space on disk +(and a correspondingly larger space in memory). But when many copies of the +same program are running, PIC dynamic linking trades a larger disk footprint +for a smaller memory footprint, by sharing more pages.
+ +A third solution is static linking. A statically linked program has no +relocations, and thus the entire executable is shared between all running +instances. This tends to have a significantly larger disk footprint, but +on a system with only one or two executables, shared libraries aren't much +of a win anyway.
+ +You can tell the glibc linker to display debugging information about its +relocations with the environment variable "LD_DEBUG". Try +"LD_DEBUG=help /bin/true" for a list of commands. Learning to interpret +"LD_DEBUG=statistics cat /proc/self/statm" could be interesting.
+ +For more on this topic, here's Rich Felker:
+++ +Dynamic linking (without fixed load addresses) fundamentally requires +at least one dirty page per dso that uses symbols. Making calls (but +never taking the address explicitly) to functions within the same dso +does not require a dirty page by itself, but will with ELF unless you +use -Bsymbolic or hidden symbols when linking.
+ +ELF uses significant additional stack space for the kernel to pass all +the ELF data structures to the newly created process image. These are +located above the argument list and environment. This normally adds 1 +dirty page to the process size.
+ +The ELF dynamic linker has its own data segment, adding one or more +dirty pages. I believe it also performs relocations on itself.
+ +The ELF dynamic linker makes significant dynamic allocations to manage +the global symbol table and the loaded dso's. This data is never +freed. It will be needed again if libdl is used, so unconditionally +freeing it is not possible, but normal programs do not use libdl. Of +course with glibc all programs use libdl (due to nsswitch) so the +issue was never addressed.
+ +ELF also has the issue that segments are not page-aligned on disk. +This saves up to 4k on disk, but at the expense of using an additional +dirty page in most cases, due to a large portion of the first data +page being filled with a duplicate copy of the last text page.
+ +The above is just a partial list of the tiny memory penalties of ELF +dynamic linking, which eventually add up to quite a bit. The smallest +I've been able to get a process down to is 8 dirty pages, and the +above factors seem to mostly account for it (but some were difficult +to measure).
+
The "linux" or "asm" directories of /usr/include +contain Linux kernel +headers, so that the C library can talk directly to the Linux kernel. In +a perfect world, applications shouldn't include these headers directly, but +we don't live in a perfect world.
+ +For example, Busybox's losetup code wants linux/loop.c because nothing else +#defines the structures to call the kernel's loopback device setup ioctls. +Attempts to cut and paste the information into a local busybox header file +proved incredibly painful, because portions of the loop_info structure vary by +architecture, namely the type __kernel_dev_t has different sizes on alpha, +arm, x86, and so on. Meaning we either #include <linux/posix_types.h> or +we hardwire #ifdefs to check what platform we're building on and define this +type appropriately for every single hardware architecture supported by +Linux, which is simply unworkable.
+ +This is aside from the fact that the relevant type defined in +posix_types.h was renamed to __kernel_old_dev_t during the 2.5 series, so +to cut and paste the structure into our header we have to #include +<linux/version.h> to figure out which name to use. (What we actually +do is +check if we're building on 2.6, and if so just use the new 64 bit structure +instead to avoid the rename entirely.) But we still need the version +check, since 2.4 didn't have the 64 bit structure.
+ +The BusyBox developers spent two years trying to figure +out a clean way to do all this. There isn't one. The losetup in the +util-linux package from kernel.org isn't doing it cleanly either, they just +hide the ugliness by nesting #include files. Their mount/loop.h +#includes "my_dev_t.h", which #includes <linux/posix_types.h> +and <linux/version.h> just like we do. There simply is no alternative. +
+ +Just because directly #including kernel headers is sometimes +unavoidable doesn't me we should include them when there's a better +way to do it. However, block copying information out of the kernel headers +is not a better way.
+ +The following login accounts currently exist on busybox.net. (I.E. these +people can commit patches +into subversion for the BusyBox, uClibc, and buildroot projects.)
+ ++aldot :Bernhard Reutner-Fischer +andersen :Erik Andersen - uClibc and BuildRoot maintainer. +bug1 :Glenn McGrath +davidm :David McCullough +gkajmowi :Garrett Kajmowicz - uClibc++ maintainer +jbglaw :Jan-Benedict Glaw +jocke :Joakim Tjernlund +landley :Rob Landley +lethal :Paul Mundt +mjn3 :Manuel Novoa III +osuadmin :osuadmin +pgf :Paul Fox +pkj :Peter Kjellerstedt +prpplague :David Anders +psm :Peter S. Mazinger +russ :Russ Dill +sandman :Robert Griebl +sjhill :Steven J. Hill +solar :Ned Ludd +timr :Tim Riker +tobiasa :Tobias Anderberg +vapier :Mike Frysinger +vda :Denys Vlasenko - BusyBox maintainer ++ +
The following accounts used to exist on busybox.net, but don't anymore so +I can't ask /etc/passwd for their names. Rob Wentworth +<robwen at gmail.com> asked Google and recovered the names:
+ ++aaronl :Aaron Lehmann +beppu :John Beppu +dwhedon :David Whedon +erik :Erik Andersen +gfeldman :Gennady Feldman +jimg :Jim Gleason +kraai :Matt Kraai +markw :Mark Whitley +miles :Miles Bader +proski :Pavel Roskin +rjune :Richard June +tausq :Randolph Chung +vodz :Vladimir N. Oleynik ++ + +
BusyBox combines tiny versions of many common UNIX utilities into a single +small executable. It provides replacements for most of the utilities you +usually find in GNU fileutils, shellutils, 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 +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 some device +nodes in /dev, a few configuration files in /etc, and a Linux kernel.
+ +BusyBox is maintained by +Denys Vlasenko, +and licensed under the GNU GENERAL PUBLIC LICENSE +version 2.
+ + diff --git a/release/src/router/busybox/docs/busybox.net/busybox-growth.ps b/release/src/router/busybox/docs/busybox.net/busybox-growth.ps old mode 100755 new mode 100644 index 123f3811..2379defa --- a/release/src/router/busybox/docs/busybox.net/busybox-growth.ps +++ b/release/src/router/busybox/docs/busybox.net/busybox-growth.ps @@ -213,7 +213,7 @@ gnudict begin /PentE { stroke [] 0 setdash gsave translate 0 hpt M 4 {72 rotate 0 hpt L} repeat closepath stroke grestore } def -/CircE { stroke [] 0 setdash +/CircE { stroke [] 0 setdash hpt 0 360 arc stroke } def /Opaque { gsave closepath 1 setgray fill grestore 0 setgray closepath } def /DiaW { stroke [] 0 setdash vpt add M @@ -233,7 +233,7 @@ gnudict begin /PentW { stroke [] 0 setdash gsave translate 0 hpt M 4 {72 rotate 0 hpt L} repeat Opaque stroke grestore } def -/CircW { stroke [] 0 setdash +/CircW { stroke [] 0 setdash hpt 0 360 arc Opaque stroke } def /BoxFill { gsave Rec 1 setgray fill grestore } def end diff --git a/release/src/router/busybox/docs/busybox.net/copyright.txt b/release/src/router/busybox/docs/busybox.net/copyright.txt new file mode 100644 index 00000000..39747563 --- /dev/null +++ b/release/src/router/busybox/docs/busybox.net/copyright.txt @@ -0,0 +1,30 @@ + +The code and graphics on this website (and it's mirror sites, if any) are +Copyright (c) 1999-2004 by Erik Andersen. All rights reserved. +Copyright (c) 2005-2006 Rob Landley. + +Documents on this Web site including their graphical elements, design, and +layout are protected by trade dress and other laws and MAY BE COPIED OR +IMITATED IN WHOLE OR IN PART. THIS WEBSITE IS LICENSED FREE OF CHARGE, THERE +IS NO WARRANTY FOR THE WEBSITE TO THE EXTENT PERMITTED BY APPLICABLE LAW. +SHOULD THIS WEBSITE PROVE DEFECTIVE, YOU MAY ASSUME THAT SOMEONE MIGHT GET +AROUND TO SERVICING, REPAIRING OR CORRECTING IT SOMETIME WHEN THEY HAVE NOTHING +BETTER TO DO. REGARDLESS, YOU GET TO KEEP BOTH PIECES. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY +COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THIS +WEBSITE AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR +INABILITY TO USE THIS WEBSITE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR +LOSS OF HAIR, LOSS OF LIFE, LOSS OF MEMORY, LOSS OF YOUR CARKEYS, MISPLACEMENT +OF YOUR PAYCHECK, OR COMMANDER DATA BEING RENDERED UNABLE TO ASSIST THE +STARFLEET OFFICERS ABORD THE STARSHIP ENTERPRISE TO RECALIBRATE THE MAIN +DEFLECTOR ARRAY, LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE +WEBSITE TO OPERATE WITH YOUR WEBBROWSER), EVEN IF SUCH HOLDER OR OTHER PARTY +HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +You have been warned. + +You can contact the webmaster at- - B u s y B o x - - | -
- - Anonymous CVS - - |
-
-We allow anonymous (read-only) CVS access to everyone. The first command you
-need to run for anonymous CVS access is:
--cvs -d:pserver:anonymous@busybox.net:/var/cvs login- -CVS will prompt you for a password. Just press the Enter key (there is no -password for anonymous access). This step only needs to be done once, the first -time you attempt to access CVS. - -Once the login is complete, you can then check the list of available -CVS modules by running the following command (all on one line): - -cvs -z3 -d:pserver:anonymous@busybox.net:/var/cvs co -c- - -If you wish, you can then check out a local copy of any of the -available modules. The following is an example of how to grab -a copy of busybox and tinylogin: - - cvs -z3 -d:pserver:anonymous@busybox.net:/var/cvs co -P busybox tinylogin-This will create a directory called busybox and a directory called -tinylogin in the current directory. These directories contain the -latest and greatest source code for busybox and tinylogin. - - -I usually create a ~/.cvsrc file with the following things in it, and I -recommend you should use the same: - - -z3 - update -dP - rdiff -u - diff -ubBwpN - checkout -P- - -Once you've checked out a copy of the source tree, you can update your -source tree at any time so it is in sync with the latest and greatest by -running the command: - -cvs update- -Because you've only been granted anonymous access to the tree, you won't be -able to commit any changes. Changes can be submitted for inclusion by posting -them to the appropriate mailing list. - - - - - |
-
- Mail all comments, insults, suggestions and bribes to
- Erik Andersen - The Busybox logo is copyright 1999-2002, Erik Andersen. - - |
-
- - - | - -- - | - -- - | - -- | - -- - | - -
- - B u s y B o x - - | -
- - CVS Read/Write Access - - |
-
-
-If you want to be able to commit things to CVS, first contribute some
-stuff to show you are serious. Then, very nicely ask
-Erik Andersen if he will set you up with
-an account. To access CVS, you will want to add the following to set up your environment:
--$ export CVS_RSH=/usr/bin/ssh -$ export CVSROOT='username@cvs.busybox.net:/var/cvs'- -It goes without saying you must change username to your own -username... - - -To obtain commit access, you will need to demonstrate you are -serious by submitting a few good patches first. Then, you will need to -select a user-name to use when committing stuff, and finally, you will -need to send me the username you have selected, an ssh key, and the email -address where you prefer email to be sent (I will forward any email sent -to you, but not store it). - - -Note that if you would prefer to keep your communications with me -private, you can encrypt your email using my -public key. - - - - - |
-
- Mail all comments, insults, suggestions and bribes to
- Erik Andersen - The Busybox logo is copyright 1999-2002, Erik Andersen. - - |
-
- - - | - -- - | - -- - | - -- | - -- - | - -
Subversion commit access requires an account on Morris. The server +behind busybox.net and uclibc.org. If you want to be able to commit things to +Subversion, first contribute some stuff to show you are serious, can handle +some responsibility, and that your patches don't generally need a lot of +cleanup. Then, very nicely ask one of us (Rob +Landley for BusyBox, or Erik +Andersen for uClibc) for an account.
+ +If you're approved for an account, you'll need to send an email from your +preferred contact email address with the username you'd like to use when +committing changes to SVN, and attach a public ssh key to access your account +with.
+ +If you don't currently have an ssh version 2 DSA key at least 1024 bits +long (the default), you can generate a key using the +command ssh-keygen -t dsa and hitting enter at the prompts. This +will create the files ~/.ssh/id_dsa and ~/.ssh/id_dsa.pub +You must then send the content of 'id_dsa.pub' to me so I can set up your +account. (The content of 'id_dsa' should of course be kept secret, anyone +who has that can access any account that's installed your public key in +its .ssh/authorized_keys file.)
+ +Note that if you would prefer to keep your communications with us +private, you can encrypt your email using +Rob's public key or +Erik's public +key.
+ +Once you are setup with an account, you will need to use your account to +checkout a copy of BusyBox from Subversion:
+ +svn checkout svn+ssh://username@busybox.net/svn/trunk/busybox
+or
+svn checkout svn+ssh://username@uclibc.org/svn/trunk/uclibc
+ +You must change username to your own username, or omit +it if it's the same as your local username.
+ +You can then enter the newly checked out project directory, make changes, +check your changes, diff your changes, revert your changes, and and commit your +changes using commands such as:
+ ++svn diff +svn status +svn revert +EDITOR=vi svn commit +svn log -v -r PREV:HEAD +svn help ++ +
For additional detail on how to use Subversion, please visit the +the Subversion website. +You might also want to read online or buy a copy of the Subversion Book...
+ +A morris account also gives you a personal web page +(http://busybox.net/~username comes from ~/public_html on morris), and of +course a shell prompt you can ssh into (as a regular user, root access is +reserved for Erik and Rob). But keep in mind an account on Morris is a +priviledge, not a requirement. Most contributors to busybox and uClibc +haven't got one, and accounts are handed out to make the project maintainers' +lives easier, not because "you deserve it".
+ + diff --git a/release/src/router/busybox/docs/busybox.net/download.html b/release/src/router/busybox/docs/busybox.net/download.html new file mode 100644 index 00000000..34195b6f --- /dev/null +++ b/release/src/router/busybox/docs/busybox.net/download.html @@ -0,0 +1,60 @@ + + + + ++Source for the latest release can always be +downloaded from http://www.busybox.net/downloads/. + +
+Each 1.x branch has bug fix releases after initial 1.x.0 release. +Also there are patches on top of latest bug fix release. +
+Latest releases and patch directories for each branch:
+
+1.10.1,
+patches,
+
+1.9.2,
+patches,
+
+1.8.3,
+patches,
+
+1.7.5,
+patches,
+
+1.6.2,
+patches,
+
+1.5.2,
+patches,
+
+1.4.2,
+patches,
+
+1.3.2,
+patches.
+
+
+You can also obtain Daily Snapshots of +the latest development source tree for those wishing to follow BusyBox development, +but cannot or do not wish to use Subversion (svn). + +
If you found a regression or severe bug in busybox, and you have a patch + for it, and you want to see it added to "hot fixes", please rediff your + patch against corresponding unmodified busybox source and send it to + the mailing list. +
+ +
+
+
+ Copyright © 1999-2008 Erik Andersen
+ + Mail all comments, insults, suggestions and bribes to + + Denys Vlasenko vda.linux@googlemail.com + + + |
+
+ + + | + ++ + | + +