Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 1 | <!--#include file="header.html" --> |
| 2 | |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 3 | <h3>Frequently Asked Questions</h3> |
| 4 | |
| 5 | This is a collection of some of the more frequently asked questions |
| 6 | about BusyBox. Some of the questions even have answers. If you |
| 7 | have additions to this FAQ document, we would love to add them, |
| 8 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 9 | <h2>General questions</h2> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 10 | <ol> |
Rob Landley | ac4c92d | 2006-05-11 17:21:13 +0000 | [diff] [blame] | 11 | <li><a href="#getting_started">How can I get started using BusyBox?</a></li> |
| 12 | <li><a href="#configure">How do I configure busybox?</a></li> |
| 13 | <li><a href="#build_system">How do I build a BusyBox-based system?</a></li> |
| 14 | <li><a href="#kernel">Which Linux kernel versions are supported?</a></li> |
| 15 | <li><a href="#arch">Which architectures does BusyBox run on?</a></li> |
| 16 | <li><a href="#libc">Which C libraries are supported?</a></li> |
| 17 | <li><a href="#commercial">Can I include BusyBox as part of the software on my device?</a></li> |
| 18 | <li><a href="#external">Where can I find other small utilities since busybox does not include the features I want?</a></li></li> |
| 19 | <li><a href="#demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a></li> |
| 20 | <li><a href="#helpme">I need help with BusyBox! What should I do?</a></li> |
| 21 | <li><a href="#contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a></li> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 22 | </ol> |
Rob Landley | de7f9b7 | 2005-07-31 04:27:19 +0000 | [diff] [blame] | 23 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 24 | <h2>Troubleshooting</h2> |
| 25 | <ol> |
| 26 | <li><a href="#bugs">I think I found a bug in BusyBox! What should I do?!</a></li> |
Rob Landley | 95718b3 | 2006-08-16 22:13:56 +0000 | [diff] [blame] | 27 | <li><a href="#backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</a></li> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 28 | <li><a href="#init">Busybox init isn't working!</a></li> |
| 29 | <li><a href="#sed">I can't configure busybox on my system.</a></li> |
| 30 | <li><a href="#job_control">Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?</a></li> |
| 31 | </ol> |
| 32 | |
| 33 | <h2>Programming questions</h2> |
| 34 | <ol> |
| 35 | <li><a href="#goals">What are the goals of busybox?</a></li> |
| 36 | <li><a href="#design">What is the design of busybox?</a></li> |
| 37 | <li><a href="#source">How is the source code organized?</a></li> |
| 38 | <ul> |
| 39 | <li><a href="#source_applets">The applet directories.</a></li> |
| 40 | <li><a href="#source_libbb">The busybox shared library (libbb)</a></li> |
| 41 | </ul> |
| 42 | <li><a href="#optimize">I want to make busybox even smaller, how do I go about it?</a></li> |
| 43 | <li><a href="#adding">Adding an applet to busybox</a></li> |
| 44 | <li><a href="#standards">What standards does busybox adhere to?</a></li> |
| 45 | <li><a href="#portability">Portability.</a></li> |
| 46 | <li><a href="#tips">Tips and tricks.</a></li> |
| 47 | <ul> |
| 48 | <li><a href="#tips_encrypted_passwords">Encrypted Passwords</a></li> |
| 49 | <li><a href="#tips_vfork">Fork and vfork</a></li> |
| 50 | <li><a href="#tips_short_read">Short reads and writes</a></li> |
| 51 | <li><a href="#tips_memory">Memory used by relocatable code, PIC, and static linking.</a></li> |
| 52 | <li><a href="#tips_kernel_headers">Including Linux kernel headers.</a></li> |
| 53 | </ul> |
| 54 | <li><a href="#who">Who are the BusyBox developers?</a></li> |
| 55 | </ul> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 56 | |
| 57 | |
| 58 | </ol> |
| 59 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 60 | <h1>General questions</h1> |
| 61 | |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 62 | <hr /> |
| 63 | <p> |
| 64 | <h2><a name="getting_started">How can I get started using BusyBox?</a></h2> |
| 65 | <p> If you just want to try out busybox without installing it, download the |
Rob Landley | ac4c92d | 2006-05-11 17:21:13 +0000 | [diff] [blame] | 66 | tarball, extract it, run "make defconfig", and then run "make". |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 67 | </p> |
| 68 | <p> |
Rob Landley | ac4c92d | 2006-05-11 17:21:13 +0000 | [diff] [blame] | 69 | This will create a busybox binary with almost all features enabled. To try |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 70 | out a busybox applet, type "./busybox [appletname] [options]", for |
| 71 | example "./busybox ls -l" or "./busybox cat LICENSE". Type "./busybox" |
| 72 | to see a command list, and "busybox appletname --help" to see a brief |
| 73 | usage message for a given applet. |
| 74 | </p> |
| 75 | <p> |
| 76 | BusyBox uses the name it was invoked under to determine which applet is |
| 77 | being invoked. (Try "mv busybox ls" and then "./ls -l".) Installing |
| 78 | busybox consists of creating symlinks (or hardlinks) to the busybox |
Rob Landley | 3d283dd | 2005-11-03 22:11:00 +0000 | [diff] [blame] | 79 | binary for each applet in busybox, and making sure these links are in |
| 80 | the shell's command $PATH. The special applet name "busybox" (or with |
| 81 | any optional suffix, such as "busybox-static") uses the first argument |
| 82 | to determine which applet to run, as shown above. |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 83 | </p> |
| 84 | <p> |
| 85 | BusyBox also has a feature called the "standalone shell", where the busybox |
| 86 | shell runs any built-in applets before checking the command path. This |
| 87 | feature is also enabled by "make allyesconfig", and to try it out run |
| 88 | the command line "PATH= ./busybox ash". This will blank your command path |
| 89 | and run busybox as your command shell, so the only commands it can find |
| 90 | (without an explicit path such as /bin/ls) are the built-in busybox ones. |
Bernhard Reutner-Fischer | d591a36 | 2006-08-20 17:35:13 +0000 | [diff] [blame^] | 91 | This is another good way to see what's built into busybox. |
| 92 | Note that the standalone shell requires CONFIG_BUSYBOX_EXEC_PATH |
| 93 | to be set appropriately, depending on whether or not /proc/self/exe is |
| 94 | available or not. If you do not have /proc, then point that config option |
| 95 | to the location of your busybox binary, usually /bin/busybox. |
| 96 | (So if you set it to /proc/self/exe, and happen to be able to chroot into |
| 97 | your rootfs, you must mount /proc beforehand.) |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 98 | </p> |
Rob Landley | ac4c92d | 2006-05-11 17:21:13 +0000 | [diff] [blame] | 99 | |
| 100 | <hr /> |
| 101 | <p> |
| 102 | <h2><a name="configure">How do I configure busybox?</a></h2> |
| 103 | <p> Busybox is configured similarly to the linux kernel. Create a default |
| 104 | configuration and then run "make menuconfig" to modify it. The end |
| 105 | result is a .config file that tells the busybox build process what features |
| 106 | to include. So instead of "./configure; make; make install" the equivalent |
| 107 | busybox build would be "make defconfig; make; make install". |
| 108 | </p> |
| 109 | |
| 110 | <p> Busybox configured with all features enabled is a little under a megabyte |
| 111 | dynamically linked on x86. To create a smaller busybox, configure it with |
| 112 | fewer features. Individual busybox applets cost anywhere from a few |
| 113 | hundred bytes to tens of kilobytes. Disable unneeded applets to save, |
| 114 | space, using menuconfig. |
| 115 | </p> |
| 116 | |
| 117 | <p>The most important busybox configurators are:</p> |
| 118 | |
| 119 | <ul> |
| 120 | <li><p>make <b>defconfig</b> - Create the maximum "sane" configuration. This |
| 121 | enables almost all features, minus things like debugging options and features |
| 122 | that require changes to the rest of the system to work (such as selinux or |
| 123 | devfs device names). Use this if you want to start from a full-featured |
| 124 | busybox and remove features until it's small enough.</p></li> |
| 125 | <li><p>make <b>allnoconfig</b> - Disable everything. This creates a tiny version |
| 126 | of busybox that doesn't do anything. Start here if you know exactly what |
| 127 | you want and would like to select only those features.</p></li> |
| 128 | <li><p>make <b>menuconfig</b> - Interactively modify a .config file through a |
| 129 | multi-level menu interface. Use this after one of the previous two.</p></li> |
| 130 | </ul> |
| 131 | |
| 132 | <p>Some other configuration options are:</p> |
| 133 | <ul> |
| 134 | <li><p>make <b>oldconfig</b> - Update an old .config file for a newer version |
| 135 | of busybox.</p></li> |
| 136 | <li><p>make <b>allyesconfig</b> - Select absolutely everything. This creates |
| 137 | a statically linked version of busybox full of debug code, with dependencies on |
| 138 | selinux, using devfs names... This makes sure everything compiles. Whether |
| 139 | or not the result would do anything useful is an open question.</p></li> |
| 140 | <li><p>make <b>allbareconfig</b> - Select all applets but disable all sub-features |
| 141 | within each applet. More build coverage testing.</p></li> |
| 142 | <li><p>make <b>randconfig</b> - Create a random configuration for test purposes.</p></li> |
| 143 | </ul> |
| 144 | |
| 145 | <p> Menuconfig modifies your .config file through an interactive menu where you can enable or disable |
| 146 | busybox features, and get help about each feature. |
| 147 | |
| 148 | |
| 149 | |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 150 | <p> |
| 151 | To build a smaller busybox binary, run "make menuconfig" and disable the |
| 152 | features you don't need. (Or run "make allnoconfig" and then use |
| 153 | menuconfig to add just the features you need. Don't forget to recompile |
| 154 | with "make" once you've finished configuring.) |
| 155 | </p> |
| 156 | <hr/> |
| 157 | <p/> |
| 158 | <h2><a name="build_system">How do I build a BusyBox-based system?</a></h2> |
| 159 | <p> |
| 160 | BusyBox is a package that replaces a dozen standard packages, but it is |
| 161 | not by itself a complete bootable system. Building an entire Linux |
| 162 | distribution from source is a bit beyond the scope of this FAQ, but it |
| 163 | understandably keeps cropping up on the mailing list, so here are some |
| 164 | pointers. |
| 165 | </p> |
| 166 | <p> |
| 167 | Start by learning how to strip a working system down to the bare essentials |
| 168 | needed to run one or two commands, so you know what it is you actually |
| 169 | need. An excellent practical place to do |
| 170 | this is the <a href="http://www.tldp.org/HOWTO/Bootdisk-HOWTO/">Linux |
| 171 | BootDisk Howto</a>, or for a more theoretical approach try |
| 172 | <a href="http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html">From |
| 173 | PowerUp to Bash Prompt</a>. |
| 174 | </p> |
| 175 | <p> |
| 176 | To learn how to build a working Linux system entirely from source code, |
| 177 | the place to go is the <a href="http://www.linuxfromscratch.org">Linux |
| 178 | From Scratch</a> project. They have an entire book of step-by-step |
| 179 | instructions you can |
| 180 | <a href="http://www.linuxfromscratch.org/lfs/view/stable/">read online</a> |
| 181 | or |
| 182 | <a href="http://www.linuxfromscratch.org/lfs/downloads/stable/">download</a>. |
| 183 | Be sure to check out the other sections of their main page, including |
| 184 | Beyond Linux From Scratch, Hardened Linux From Scratch, their Hints |
| 185 | directory, and their LiveCD project. (They also have mailing lists which |
| 186 | are better sources of answers to Linux-system building questions than |
| 187 | the busybox list.) |
| 188 | </p> |
| 189 | <p> |
| 190 | If you want an automated yet customizable system builder which produces |
| 191 | a BusyBox and uClibc based system, try |
| 192 | <a href="http://buildroot.uclibc.org">buildroot</a>, which is |
Rob Landley | a253e73 | 2006-02-14 08:29:48 +0000 | [diff] [blame] | 193 | another project by the maintainer of the uClibc (Erik Andersen). |
| 194 | Download the tarball, extract it, unset CC, make. |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 195 | For more instructions, see the website. |
| 196 | </p> |
| 197 | |
Rob Landley | d48633f | 2006-03-09 18:03:21 +0000 | [diff] [blame] | 198 | <hr /> |
| 199 | <p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 200 | <h2><a name="kernel">Which Linux kernel versions are supported?</a></h2> |
| 201 | <p> |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 202 | Full functionality requires Linux 2.4.x or better. (Earlier versions may |
| 203 | still work, but are no longer regularly tested.) A large fraction of the |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 204 | code should run on just about anything. While the current code is fairly |
| 205 | Linux specific, it should be fairly easy to port the majority of the code |
| 206 | to support, say, FreeBSD or Solaris, or Mac OS X, or even Windows (if you |
| 207 | are into that sort of thing). |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 208 | </p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 209 | <hr /> |
| 210 | <p> |
| 211 | <h2><a name="arch">Which architectures does BusyBox run on?</a></h2> |
| 212 | <p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 213 | BusyBox in general will build on any architecture supported by gcc. |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 214 | Kernel module loading for 2.4 Linux kernels is currently |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 215 | limited to ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC, |
| 216 | S390, SH3/4/5, Sparc, v850e, and x86_64 for 2.4.x kernels. |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 217 | </p> |
| 218 | <p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 219 | With 2.6.x kernels, module loading support should work on all architectures. |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 220 | </p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 221 | <hr /> |
| 222 | <p> |
| 223 | <h2><a name="libc">Which C libraries are supported?</a></h2> |
| 224 | <p> |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 225 | On Linux, BusyBox releases are tested against uClibc (0.9.27 or later) and |
| 226 | glibc (2.2 or later). Both should provide full functionality with busybox, |
| 227 | and if you find a bug we want to hear about it. |
| 228 | </p> |
Mike Frysinger | d505e3e | 2005-10-29 08:03:54 +0000 | [diff] [blame] | 229 | <p> |
Rob Landley | 380ad12 | 2005-09-23 16:52:09 +0000 | [diff] [blame] | 230 | Linux-libc5 is no longer maintained (and has no known advantages over |
| 231 | uClibc), dietlibc is known to have numerous unfixed bugs, and klibc is |
| 232 | missing too many features to build BusyBox. If you require a small C |
| 233 | library for Linux, the busybox developers recommend uClibc. |
| 234 | </p> |
| 235 | <p> |
| 236 | Some BusyBox applets have been built and run under a combination |
| 237 | of newlib and libgloss (see |
| 238 | <a href="http://www.busybox.net/lists/busybox/2005-March/013759.html">this thread</a>). |
| 239 | This is still experimental, but may be supported in a future release. |
| 240 | </p> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 241 | |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 242 | <hr /> |
| 243 | <p> |
Mike Frysinger | 86097b3 | 2005-09-15 01:37:36 +0000 | [diff] [blame] | 244 | <h2><a name="commercial">Can I include BusyBox as part of the software on my device?</a></h2> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 245 | <p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 246 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 247 | <p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 248 | Yes. As long as you <a href="http://busybox.net/license.html">fully comply |
| 249 | with the generous terms of the GPL BusyBox license</a> you can ship BusyBox |
| 250 | as part of the software on your device. |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 251 | </p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 252 | |
| 253 | <hr /> |
| 254 | <p> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 255 | <h2><a name="external">where can i find other small utilities since busybox |
| 256 | does not include the features i want?</a></h2> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 257 | <p> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 258 | we maintain such a <a href="tinyutils.html">list</a> on this site! |
| 259 | </p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 260 | |
| 261 | <hr /> |
| 262 | <p> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 263 | <h2><a name="demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a></h2> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 264 | <p> |
| 265 | |
| 266 | You have not paid us a single cent and yet you still have the product of |
| 267 | many years of our work. We are not your slaves! We work on BusyBox |
| 268 | because we find it useful and interesting. If you go off flaming us, we |
| 269 | will ignore you. |
| 270 | |
| 271 | |
| 272 | <hr /> |
| 273 | <p> |
| 274 | <h2><a name="helpme">I need help with BusyBox! What should I do?</a></h2> |
| 275 | <p> |
| 276 | |
| 277 | If you find that you need help with BusyBox, you can ask for help on the |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 278 | BusyBox mailing list at busybox@busybox.net.</p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 279 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 280 | <p> In addition to the mailing list, Erik Andersen (andersee), Manuel Nova |
| 281 | (mjn3), Rob Landley (landley), Mike Frysinger (SpanKY), Bernhard Fischer |
| 282 | (blindvt), and other long-time BusyBox developers are known to hang out |
| 283 | on the uClibc IRC channel: #uclibc on irc.freenode.net. There is a |
| 284 | <a href="http://ibot.Rikers.org/%23uclibc/">web archive of |
| 285 | daily logs of the #uclibc IRC channel</a> going back to 2002. |
| 286 | </p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 287 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 288 | <p> |
Rob Landley | a253e73 | 2006-02-14 08:29:48 +0000 | [diff] [blame] | 289 | <b>Please do not send private email to Rob, Erik, Manuel, or the other |
| 290 | BusyBox contributors asking for private help unless you are planning on |
| 291 | paying for consulting services.</b> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 292 | </p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 293 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 294 | <p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 295 | When we answer questions on the BusyBox mailing list, it helps everyone |
| 296 | since people with similar problems in the future will be able to get help |
| 297 | by searching the mailing list archives. Private help is reserved as a paid |
| 298 | service. If you need to use private communication, or if you are serious |
| 299 | about getting timely assistance with BusyBox, you should seriously consider |
| 300 | paying for consulting services. |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 301 | </p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 302 | |
| 303 | <hr /> |
| 304 | <p> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 305 | <h2><a name="contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a></h2> |
| 306 | </p> |
| 307 | |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 308 | <p> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 309 | Yes we are. The easy way to sponsor a new feature is to post an offer on |
| 310 | the mailing list to see who's interested. You can also email the project's |
| 311 | maintainer and ask them to recommend someone. |
| 312 | </p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 313 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 314 | <p> If you prefer to deal with an organization rather than an individual, Rob |
| 315 | Landley (the current BusyBox maintainer) works for |
| 316 | <a http://www.timesys.com>TimeSys</a>, and Eric Andersen (the previous |
| 317 | busybox maintainer and current uClibc maintainer) owns |
| 318 | <a href="http://codepoet-consulting.com/">CodePoet Consulting</a>. Both |
| 319 | companies offer support contracts and handle new development, and there |
| 320 | are plenty of other companies that do the same. |
| 321 | </p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 322 | |
| 323 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 324 | |
| 325 | |
| 326 | <h1>Troubleshooting</h1> |
| 327 | |
| 328 | <hr /> |
| 329 | <p></p> |
| 330 | <h2><a name="bugs">I think I found a bug in BusyBox! What should I do?</a></h2> |
| 331 | <p></p> |
| 332 | |
| 333 | <p> |
| 334 | If you simply need help with using or configuring BusyBox, please submit a |
| 335 | detailed description of your problem to the BusyBox mailing list at <a |
| 336 | href="mailto:busybox@busybox.net"> busybox@busybox.net</a>. |
| 337 | Please do not send email to individual developers asking |
| 338 | for private help unless you are planning on paying for consulting services. |
| 339 | When we answer questions on the BusyBox mailing list, it helps everyone, |
| 340 | while private answers help only you... |
| 341 | </p> |
| 342 | |
| 343 | <p> |
Rob Landley | 95718b3 | 2006-08-16 22:13:56 +0000 | [diff] [blame] | 344 | Bug reports and new feature patches sometimes get lost when posted to the |
| 345 | mailing list, because the developers of BusyBox are busy people and have |
| 346 | only so much they can keep in their brains at a time. You can post a |
| 347 | polite reminder after 2-3 days without offending anybody. If that doesn't |
| 348 | result in a solution, please use the |
| 349 | <a href="http://bugs.busybox.net/">BusyBox Bug |
| 350 | and Patch Tracking System</a> to submit a detailed explanation and we'll |
| 351 | get to it as soon as we can. |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 352 | </p> |
| 353 | |
Rob Landley | 95718b3 | 2006-08-16 22:13:56 +0000 | [diff] [blame] | 354 | <p> |
| 355 | Note that bugs entered into the bug system without being mentioned on the |
| 356 | mailing list first may languish there for months before anyone even notices |
| 357 | them. We generally go through the bug system when preparing for new |
| 358 | development releases, to see what fell through the cracks while we were |
| 359 | off writing new features. (It's a fast/unreliable vs slow/reliable thing. |
| 360 | Saves retransits, but the latency sucks.) |
| 361 | </p> |
| 362 | |
| 363 | <hr /> |
| 364 | <p></p> |
| 365 | <h2><a name="backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</h2> |
| 366 | |
| 367 | <p>Variants of this one get asked a lot.</p> |
| 368 | |
| 369 | <p>The purpose of the BusyBox mailing list is to develop and improve BusyBox, |
| 370 | and we're happy to respond to our users' needs. But if you're coming to the |
| 371 | list for free tech support we're going to ask you to upgrade to a current |
| 372 | version before we try to diagnose your problem.</p> |
| 373 | |
| 374 | <p>If you're building BusyBox 0.50 with uClibc 0.9.19 and gcc 0.9.26 there's a |
| 375 | fairly large chance that whatever problem you're seeing has already been fixed. |
| 376 | To get that fix, all you have to do is upgrade to a newer version. If you |
| 377 | don't at least _try_ that, you're wasting our time.</p> |
| 378 | |
| 379 | <p>The volunteers are happy to fix any bugs you point out in the current |
| 380 | versions because doing so helps everybody and makes the project better. We |
| 381 | want to make the current version work for you. But diagnosing, debugging, and |
| 382 | backporting fixes to old versions isn't something we do for free, because it |
| 383 | doesn't help anybody but you. The cost of volunteer tech support is using a |
| 384 | reasonably current version of the project.</p> |
| 385 | |
| 386 | <p>If you don't want to upgrade, you have the complete source code and thus |
| 387 | the ability to fix it yourself, or hire a consultant to do it for you. If you |
| 388 | got your version from a vendor who still supports the older version, they can |
| 389 | help you. But there are limits as to what the volunteers will feel obliged to |
| 390 | do for you.</p> |
| 391 | |
| 392 | <p>As a rule of thumb, volunteers will generally answer polite questions about |
| 393 | a given version for about three years after its release before it's so old |
| 394 | we don't remember the answer off the top of our head. And if you want us to |
| 395 | put any _effort_ into tracking it down, we want you to put in a little effort |
| 396 | of your own by confirming it's still a problem with the current version. It's |
| 397 | also hard for us to fix a problem of yours if we can't reproduce it because |
| 398 | we don't have any systems running an environment that old.</p> |
| 399 | |
| 400 | <p>A consultant will happily set up a special environment just to reproduce |
| 401 | your problem, and you can always ask on the list if any of the developers |
| 402 | have consulting rates.</p> |
| 403 | |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 404 | <hr /> |
| 405 | <p> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 406 | <h2><a name="init">Busybox init isn't working!</a></h2> |
Mike Frysinger | 77dbe73 | 2005-04-17 04:32:22 +0000 | [diff] [blame] | 407 | <p> |
Rob Landley | c5e4ab7 | 2006-06-29 04:59:11 +0000 | [diff] [blame] | 408 | Init is the first program that runs, so it might be that no programs are |
| 409 | working on your new system because of a problem with your cross-compiler, |
| 410 | kernel, console settings, shared libraries, root filesystem... To rule all |
| 411 | that out, first build a statically linked version of the following "hello |
| 412 | world" program with your cross compiler toolchain: |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 413 | </p> |
| 414 | <pre> |
| 415 | #include <stdio.h> |
Mike Frysinger | 77dbe73 | 2005-04-17 04:32:22 +0000 | [diff] [blame] | 416 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 417 | int main(int argc, char *argv) |
| 418 | { |
| 419 | printf("Hello world!\n"); |
| 420 | sleep(999999999); |
| 421 | } |
| 422 | </pre> |
| 423 | |
| 424 | <p> |
| 425 | Now try to boot your device with an "init=" argument pointing to your |
| 426 | hello world program. Did you see the hello world message? Until you |
| 427 | do, don't bother messing with busybox init. |
| 428 | </p> |
| 429 | |
| 430 | <p> |
| 431 | Once you've got it working statically linked, try getting it to work |
| 432 | dynamically linked. Then read the FAQ entry <a href="#build_system">How |
Rob Landley | c5e4ab7 | 2006-06-29 04:59:11 +0000 | [diff] [blame] | 433 | do I build a BusyBox-based system?</a>, and the |
| 434 | <a href="/downloads/BusyBox.html#item_init">documentation for BusyBox |
| 435 | init</a>. |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 436 | </p> |
Mike Frysinger | 77dbe73 | 2005-04-17 04:32:22 +0000 | [diff] [blame] | 437 | |
| 438 | <hr /> |
| 439 | <p> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 440 | <h2><a name="sed">I can't configure busybox on my system.</a></h2> |
| 441 | <p> |
| 442 | Configuring Busybox depends on a recent version of sed. Older |
| 443 | distributions (Red Hat 7.2, Debian 3.0) may not come with a |
| 444 | usable version. Luckily BusyBox can use its own sed to configure itself, |
| 445 | although this leads to a bit of a chicken and egg problem. |
| 446 | You can work around this by hand-configuring busybox to build with just |
| 447 | sed, then putting that sed in your path to configure the rest of busybox |
| 448 | with, like so: |
| 449 | </p> |
| 450 | |
| 451 | <pre> |
| 452 | tar xvjf sources/busybox-x.x.x.tar.bz2 |
| 453 | cd busybox-x.x.x |
| 454 | make allnoconfig |
| 455 | make include/bb_config.h |
| 456 | echo "CONFIG_SED=y" >> .config |
| 457 | echo "#undef ENABLE_SED" >> include/bb_config.h |
| 458 | echo "#define ENABLE_SED 1" >> include/bb_config.h |
| 459 | make |
| 460 | mv busybox sed |
| 461 | export PATH=`pwd`:"$PATH" |
| 462 | </pre> |
| 463 | |
| 464 | <p>Then you can run "make defconfig" or "make menuconfig" normally.</p> |
| 465 | |
| 466 | <hr /> |
| 467 | <p> |
| 468 | <h2><a name="job_control">Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?</a></h2> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 469 | <p> |
| 470 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 471 | Job control will be turned off since your shell can not obtain a controlling |
| 472 | terminal. This typically happens when you run your shell on /dev/console. |
| 473 | The kernel will not provide a controlling terminal on the /dev/console |
| 474 | device. Your should run your shell on a normal tty such as tty1 or ttyS0 |
| 475 | and everything will work perfectly. If you <em>REALLY</em> want your shell |
| 476 | to run on /dev/console, then you can hack your kernel (if you are into that |
| 477 | sortof thing) by changing drivers/char/tty_io.c to change the lines where |
| 478 | it sets "noctty = 1;" to instead set it to "0". I recommend you instead |
| 479 | run your shell on a real console... |
| 480 | </p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 481 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 482 | <h1>Development</h1> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 483 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 484 | <h2><b><a name="goals">What are the goals of busybox?</a></b></h2> |
| 485 | |
| 486 | <p>Busybox aims to be the smallest and simplest correct implementation of the |
| 487 | standard Linux command line tools. First and foremost, this means the |
| 488 | smallest executable size we can manage. We also want to have the simplest |
| 489 | and cleanest implementation we can manage, be <a href="#standards">standards |
| 490 | compliant</a>, minimize run-time memory usage (heap and stack), run fast, and |
| 491 | take over the world.</p> |
| 492 | |
| 493 | <h2><b><a name="design">What is the design of busybox?</a></b></h2> |
| 494 | |
| 495 | <p>Busybox is like a swiss army knife: one thing with many functions. |
| 496 | The busybox executable can act like many different programs depending on |
| 497 | the name used to invoke it. Normal practice is to create a bunch of symlinks |
| 498 | pointing to the busybox binary, each of which triggers a different busybox |
| 499 | function. (See <a href="FAQ.html#getting_started">getting started</a> in the |
| 500 | FAQ for more information on usage, and <a href="BusyBox.html">the |
| 501 | busybox documentation</a> for a list of symlink names and what they do.) |
| 502 | |
| 503 | <p>The "one binary to rule them all" approach is primarily for size reasons: a |
| 504 | single multi-purpose executable is smaller then many small files could be. |
| 505 | This way busybox only has one set of ELF headers, it can easily share code |
| 506 | between different apps even when statically linked, it has better packing |
| 507 | efficiency by avoding gaps between files or compression dictionary resets, |
| 508 | and so on.</p> |
| 509 | |
| 510 | <p>Work is underway on new options such as "make standalone" to build separate |
| 511 | binaries for each applet, and a "libbb.so" to make the busybox common code |
| 512 | available as a shared library. Neither is ready yet at the time of this |
| 513 | writing.</p> |
| 514 | |
| 515 | <a name="source"></a> |
| 516 | |
| 517 | <h2><a name="source_applets"><b>The applet directories</b></a></h2> |
| 518 | |
| 519 | <p>The directory "applets" contains the busybox startup code (applets.c and |
| 520 | busybox.c), and several subdirectories containing the code for the individual |
| 521 | applets.</p> |
| 522 | |
| 523 | <p>Busybox execution starts with the main() function in applets/busybox.c, |
| 524 | which sets the global variable bb_applet_name to argv[0] and calls |
| 525 | run_applet_by_name() in applets/applets.c. That uses the applets[] array |
| 526 | (defined in include/busybox.h and filled out in include/applets.h) to |
| 527 | transfer control to the appropriate APPLET_main() function (such as |
| 528 | cat_main() or sed_main()). The individual applet takes it from there.</p> |
| 529 | |
| 530 | <p>This is why calling busybox under a different name triggers different |
| 531 | functionality: main() looks up argv[0] in applets[] to get a function pointer |
| 532 | to APPLET_main().</p> |
| 533 | |
| 534 | <p>Busybox applets may also be invoked through the multiplexor applet |
| 535 | "busybox" (see busybox_main() in applets/busybox.c), and through the |
| 536 | standalone shell (grep for STANDALONE_SHELL in applets/shell/*.c). |
| 537 | See <a href="FAQ.html#getting_started">getting started</a> in the |
| 538 | FAQ for more information on these alternate usage mechanisms, which are |
| 539 | just different ways to reach the relevant APPLET_main() function.</p> |
| 540 | |
| 541 | <p>The applet subdirectories (archival, console-tools, coreutils, |
| 542 | debianutils, e2fsprogs, editors, findutils, init, loginutils, miscutils, |
| 543 | modutils, networking, procps, shell, sysklogd, and util-linux) correspond |
| 544 | to the configuration sub-menus in menuconfig. Each subdirectory contains the |
| 545 | code to implement the applets in that sub-menu, as well as a Config.in |
| 546 | file defining that configuration sub-menu (with dependencies and help text |
| 547 | for each applet), and the makefile segment (Makefile.in) for that |
| 548 | subdirectory.</p> |
| 549 | |
| 550 | <p>The run-time --help is stored in usage_messages[], which is initialized at |
| 551 | the start of applets/applets.c and gets its help text from usage.h. During the |
| 552 | build this help text is also used to generate the BusyBox documentation (in |
| 553 | html, txt, and man page formats) in the docs directory. See |
| 554 | <a href="#adding">adding an applet to busybox</a> for more |
| 555 | information.</p> |
| 556 | |
| 557 | <h2><a name="source_libbb"><b>libbb</b></a></h2> |
| 558 | |
| 559 | <p>Most non-setup code shared between busybox applets lives in the libbb |
| 560 | directory. It's a mess that evolved over the years without much auditing |
| 561 | or cleanup. For anybody looking for a great project to break into busybox |
| 562 | development with, documenting libbb would be both incredibly useful and good |
| 563 | experience.</p> |
| 564 | |
| 565 | <p>Common themes in libbb include allocation functions that test |
| 566 | for failure and abort the program with an error message so the caller doesn't |
| 567 | have to test the return value (xmalloc(), xstrdup(), etc), wrapped versions |
| 568 | of open(), close(), read(), and write() that test for their own failures |
| 569 | and/or retry automatically, linked list management functions (llist.c), |
| 570 | command line argument parsing (getopt_ulflags.c), and a whole lot more.</p> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 571 | |
| 572 | <hr /> |
Rob Landley | c7a3e1b | 2005-07-31 04:25:00 +0000 | [diff] [blame] | 573 | <p> |
| 574 | <h2><a name="optimize">I want to make busybox even smaller, how do I go about it?</a></h2> |
| 575 | <p> |
| 576 | To conserve bytes it's good to know where they're being used, and the |
| 577 | size of the final executable isn't always a reliable indicator of |
| 578 | the size of the components (since various structures are rounded up, |
| 579 | so a small change may not even be visible by itself, but many small |
| 580 | savings add up). |
| 581 | </p> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 582 | |
| 583 | <p> The busybox Makefile builds two versions of busybox, one of which |
| 584 | (busybox_unstripped) has extra information that various analysis tools |
| 585 | can use. (This has nothing to do with CONFIG_DEBUG, leave that off |
| 586 | when trying to optimize for size.) |
| 587 | </p> |
| 588 | |
| 589 | <p> The <b>"make bloatcheck"</b> option uses Matt Mackall's bloat-o-meter |
| 590 | script to compare two versions of busybox (busybox_unstripped vs |
| 591 | busybox_old), and report which symbols changed size and by how much. |
Rob Landley | d244bc1 | 2006-05-27 21:30:34 +0000 | [diff] [blame] | 592 | To use it, first build a base version with <b>"make baseline"</b>. |
| 593 | (This creates busybox_old, which should have the original sizes for |
| 594 | comparison purposes.) Then build the new version with your changes |
| 595 | and run "make bloatcheck" to see the size differences from the old |
| 596 | version. |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 597 | </p> |
Rob Landley | c7a3e1b | 2005-07-31 04:25:00 +0000 | [diff] [blame] | 598 | <p> |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 599 | The first line of output has totals: how many symbols were added or |
| 600 | removed, how many symbols grew or shrank, the number of bytes added |
| 601 | and number of bytes removed by these changes, and finally the total |
| 602 | number of bytes difference between the two files. The remaining |
| 603 | lines show each individual symbol, the old and new sizes, and the |
| 604 | increase or decrease in size (which results are sorted by). |
| 605 | </p> |
| 606 | <p> |
| 607 | The <b>"make sizes"</b> option produces raw symbol size information for |
| 608 | busybox_unstripped. This is the output from the "nm --size-sort" |
| 609 | command (see "man nm" for more information), and is the information |
| 610 | bloat-o-meter parses to produce the comparison report above. For |
| 611 | defconfig, this is a good way to find the largest symbols in the tree |
| 612 | (which is a good place to start when trying to shrink the code). To |
| 613 | take a closer look at individual applets, configure busybox with just |
| 614 | one applet (run "make allnoconfig" and then switch on a single applet |
| 615 | with menuconfig), and then use "make sizes" to see the size of that |
| 616 | applet's components. |
| 617 | </p> |
| 618 | <p> |
| 619 | The "showasm" command (in the scripts directory) produces an assembly |
| 620 | dump of a function, providing a closer look at what changed. Try |
| 621 | "scripts/showasm busybox_unstripped" to list available symbols, and |
| 622 | "scripts/showasm busybox_unstripped symbolname" to see the assembly |
| 623 | for a sepecific symbol. |
Rob Landley | c7a3e1b | 2005-07-31 04:25:00 +0000 | [diff] [blame] | 624 | </p> |
| 625 | <hr /> |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 626 | |
Rob Landley | c7a3e1b | 2005-07-31 04:25:00 +0000 | [diff] [blame] | 627 | |
| 628 | |
Rob Landley | b73d2bf | 2006-05-11 15:00:32 +0000 | [diff] [blame] | 629 | <h2><a name="adding"><b>Adding an applet to busybox</b></a></h2> |
| 630 | |
| 631 | <p>To add a new applet to busybox, first pick a name for the applet and |
| 632 | a corresponding CONFIG_NAME. Then do this:</p> |
| 633 | |
| 634 | <ul> |
| 635 | <li>Figure out where in the busybox source tree your applet best fits, |
| 636 | and put your source code there. Be sure to use APPLET_main() instead |
| 637 | of main(), where APPLET is the name of your applet.</li> |
| 638 | |
| 639 | <li>Add your applet to the relevant Config.in file (which file you add |
| 640 | it to determines where it shows up in "make menuconfig"). This uses |
| 641 | the same general format as the linux kernel's configuration system.</li> |
| 642 | |
| 643 | <li>Add your applet to the relevant Makefile.in file (in the same |
| 644 | directory as the Config.in you chose), using the existing entries as a |
| 645 | template and the same CONFIG symbol as you used for Config.in. (Don't |
| 646 | forget "needlibm" or "needcrypt" if your applet needs libm or |
| 647 | libcrypt.)</li> |
| 648 | |
| 649 | <li>Add your applet to "include/applets.h", using one of the existing |
| 650 | entries as a template. (Note: this is in alphabetical order. Applets |
| 651 | are found via binary search, and if you add an applet out of order it |
| 652 | won't work.)</li> |
| 653 | |
| 654 | <li>Add your applet's runtime help text to "include/usage.h". You need |
| 655 | at least appname_trivial_usage (the minimal help text, always included |
| 656 | in the busybox binary when this applet is enabled) and appname_full_usage |
| 657 | (extra help text included in the busybox binary with |
| 658 | CONFIG_FEATURE_VERBOSE_USAGE is enabled), or it won't compile. |
| 659 | The other two help entry types (appname_example_usage and |
| 660 | appname_notes_usage) are optional. They don't take up space in the binary, |
| 661 | but instead show up in the generated documentation (BusyBox.html, |
| 662 | BusyBox.txt, and the man page BusyBox.1).</li> |
| 663 | |
| 664 | <li>Run menuconfig, switch your applet on, compile, test, and fix the |
| 665 | bugs. Be sure to try both "allyesconfig" and "allnoconfig" (and |
| 666 | "allbareconfig" if relevant).</li> |
| 667 | |
| 668 | </ul> |
| 669 | |
| 670 | <h2><a name="standards">What standards does busybox adhere to?</a></h2> |
| 671 | |
| 672 | <p>The standard we're paying attention to is the "Shell and Utilities" |
| 673 | portion of the <a href="http://www.opengroup.org/onlinepubs/009695399/">Open |
| 674 | Group Base Standards</a> (also known as the Single Unix Specification version |
| 675 | 3 or SUSv3). Note that paying attention isn't necessarily the same thing as |
| 676 | following it.</p> |
| 677 | |
| 678 | <p>SUSv3 doesn't even mention things like init, mount, tar, or losetup, nor |
| 679 | commonly used options like echo's '-e' and '-n', or sed's '-i'. Busybox is |
| 680 | driven by what real users actually need, not the fact the standard believes |
| 681 | we should implement ed or sccs. For size reasons, we're unlikely to include |
| 682 | much internationalization support beyond UTF-8, and on top of all that, our |
| 683 | configuration menu lets developers chop out features to produce smaller but |
| 684 | very non-standard utilities.</p> |
| 685 | |
| 686 | <p>Also, Busybox is aimed primarily at Linux. Unix standards are interesting |
| 687 | because Linux tries to adhere to them, but portability to dozens of platforms |
| 688 | is only interesting in terms of offering a restricted feature set that works |
| 689 | everywhere, not growing dozens of platform-specific extensions. Busybox |
| 690 | should be portable to all hardware platforms Linux supports, and any other |
| 691 | similar operating systems that are easy to do and won't require much |
| 692 | maintenance.</p> |
| 693 | |
| 694 | <p>In practice, standards compliance tends to be a clean-up step once an |
| 695 | applet is otherwise finished. When polishing and testing a busybox applet, |
| 696 | we ensure we have at least the option of full standards compliance, or else |
| 697 | document where we (intentionally) fall short.</p> |
| 698 | |
| 699 | <h2><a name="portability">Portability.</a></h2> |
| 700 | |
| 701 | <p>Busybox is a Linux project, but that doesn't mean we don't have to worry |
| 702 | about portability. First of all, there are different hardware platforms, |
| 703 | different C library implementations, different versions of the kernel and |
| 704 | build toolchain... The file "include/platform.h" exists to centralize and |
| 705 | encapsulate various platform-specific things in one place, so most busybox |
| 706 | code doesn't have to care where it's running.</p> |
| 707 | |
| 708 | <p>To start with, Linux runs on dozens of hardware platforms. We try to test |
| 709 | each release on x86, x86-64, arm, power pc, and mips. (Since qemu can handle |
| 710 | all of these, this isn't that hard.) This means we have to care about a number |
| 711 | of portability issues like endianness, word size, and alignment, all of which |
| 712 | belong in platform.h. That header handles conditional #includes and gives |
| 713 | us macros we can use in the rest of our code. At some point in the future |
| 714 | we might grow a platform.c, possibly even a platform subdirectory. As long |
| 715 | as the applets themselves don't have to care.</p> |
| 716 | |
| 717 | <p>On a related note, we made the "default signedness of char varies" problem |
| 718 | go away by feeding the compiler -funsigned-char. This gives us consistent |
| 719 | behavior on all platforms, and defaults to 8-bit clean text processing (which |
| 720 | gets us halfway to UTF-8 support). NOMMU support is less easily separated |
| 721 | (see the tips section later in this document), but we're working on it.</p> |
| 722 | |
| 723 | <p>Another type of portability is build environments: we unapologetically use |
| 724 | a number of gcc and glibc extensions (as does the Linux kernel), but these have |
| 725 | been picked up by packages like uClibc, TCC, and Intel's C Compiler. As for |
| 726 | gcc, we take advantage of newer compiler optimizations to get the smallest |
| 727 | possible size, but we also regression test against an older build environment |
| 728 | using the Red Hat 9 image at "http://busybox.net/downloads/qemu". This has a |
| 729 | 2.4 kernel, gcc 3.2, make 3.79.1, and glibc 2.3, and is the oldest |
| 730 | build/deployment environment we still put any effort into maintaining. (If |
| 731 | anyone takes an interest in older kernels you're welcome to submit patches, |
| 732 | but the effort would probably be better spent |
| 733 | <a href="http://www.selenic.com/linux-tiny/">trimming |
| 734 | down the 2.6 kernel</a>.) Older gcc versions than that are uninteresting since |
| 735 | we now use c99 features, although |
| 736 | <a href="http://fabrice.bellard.free.fr/tcc/">tcc</a> might be worth a |
| 737 | look.</p> |
| 738 | |
| 739 | <p>We also test busybox against the current release of uClibc. Older versions |
| 740 | of uClibc aren't very interesting (they were buggy, and uClibc wasn't really |
| 741 | usable as a general-purpose C library before version 0.9.26 anyway).</p> |
| 742 | |
| 743 | <p>Other unix implementations are mostly uninteresting, since Linux binaries |
| 744 | have become the new standard for portable Unix programs. Specifically, |
| 745 | the ubiquity of Linux was cited as the main reason the Intel Binary |
| 746 | Compatability Standard 2 died, by the standards group organized to name a |
| 747 | successor to ibcs2: <a href="http://www.telly.org/86open/">the 86open |
| 748 | project</a>. That project disbanded in 1999 with the endorsement of an |
| 749 | existing standard: Linux ELF binaries. Since then, the major players at the |
| 750 | time (such as <a |
| 751 | href=http://www-03.ibm.com/servers/aix/products/aixos/linux/index.html>AIX</a>, <a |
| 752 | href=http://www.sun.com/software/solaris/ds/linux_interop.jsp#3>Solaris</a>, and |
| 753 | <a href=http://www.onlamp.com/pub/a/bsd/2000/03/17/linuxapps.html>FreeBSD</a>) |
| 754 | have all either grown Linux support or folded.</p> |
| 755 | |
| 756 | <p>The major exceptions are newcomer MacOS X, some embedded environments |
| 757 | (such as newlib+libgloss) which provide a posix environment but not a full |
| 758 | Linux environment, and environments like Cygwin that provide only partial Linux |
| 759 | emulation. Also, some embedded Linux systems run a Linux kernel but amputate |
| 760 | things like the /proc directory to save space.</p> |
| 761 | |
| 762 | <p>Supporting these systems is largely a question of providing a clean subset |
| 763 | of BusyBox's functionality -- whichever applets can easily be made to |
| 764 | work in that environment. Annotating the configuration system to |
| 765 | indicate which applets require which prerequisites (such as procfs) is |
| 766 | also welcome. Other efforts to support these systems (swapping #include |
| 767 | files to build in different environments, adding adapter code to platform.h, |
| 768 | adding more extensive special-case supporting infrastructure such as mount's |
| 769 | legacy mtab support) are handled on a case-by-case basis. Support that can be |
| 770 | cleanly hidden in platform.h is reasonably attractive, and failing that |
| 771 | support that can be cleanly separated into a separate conditionally compiled |
| 772 | file is at least worth a look. Special-case code in the body of an applet is |
| 773 | something we're trying to avoid.</p> |
| 774 | |
| 775 | <h2><a name="tips" />Programming tips and tricks.</a></h2> |
| 776 | |
| 777 | <p>Various things busybox uses that aren't particularly well documented |
| 778 | elsewhere.</p> |
| 779 | |
| 780 | <h2><a name="tips_encrypted_passwords">Encrypted Passwords</a></h2> |
| 781 | |
| 782 | <p>Password fields in /etc/passwd and /etc/shadow are in a special format. |
| 783 | If the first character isn't '$', then it's an old DES style password. If |
| 784 | the first character is '$' then the password is actually three fields |
| 785 | separated by '$' characters:</p> |
| 786 | <pre> |
| 787 | <b>$type$salt$encrypted_password</b> |
| 788 | </pre> |
| 789 | |
| 790 | <p>The "type" indicates which encryption algorithm to use: 1 for MD5 and 2 for SHA1.</p> |
| 791 | |
| 792 | <p>The "salt" is a bunch of ramdom characters (generally 8) the encryption |
| 793 | algorithm uses to perturb the password in a known and reproducible way (such |
| 794 | as by appending the random data to the unencrypted password, or combining |
| 795 | them with exclusive or). Salt is randomly generated when setting a password, |
| 796 | and then the same salt value is re-used when checking the password. (Salt is |
| 797 | thus stored unencrypted.)</p> |
| 798 | |
| 799 | <p>The advantage of using salt is that the same cleartext password encrypted |
| 800 | with a different salt value produces a different encrypted value. |
| 801 | If each encrypted password uses a different salt value, an attacker is forced |
| 802 | to do the cryptographic math all over again for each password they want to |
| 803 | check. Without salt, they could simply produce a big dictionary of commonly |
| 804 | used passwords ahead of time, and look up each password in a stolen password |
| 805 | file to see if it's a known value. (Even if there are billions of possible |
| 806 | passwords in the dictionary, checking each one is just a binary search against |
| 807 | a file only a few gigabytes long.) With salt they can't even tell if two |
| 808 | different users share the same password without guessing what that password |
| 809 | is and decrypting it. They also can't precompute the attack dictionary for |
| 810 | a specific password until they know what the salt value is.</p> |
| 811 | |
| 812 | <p>The third field is the encrypted password (plus the salt). For md5 this |
| 813 | is 22 bytes.</p> |
| 814 | |
| 815 | <p>The busybox function to handle all this is pw_encrypt(clear, salt) in |
| 816 | "libbb/pw_encrypt.c". The first argument is the clear text password to be |
| 817 | encrypted, and the second is a string in "$type$salt$password" format, from |
| 818 | which the "type" and "salt" fields will be extracted to produce an encrypted |
| 819 | value. (Only the first two fields are needed, the third $ is equivalent to |
| 820 | the end of the string.) The return value is an encrypted password in |
| 821 | /etc/passwd format, with all three $ separated fields. It's stored in |
| 822 | a static buffer, 128 bytes long.</p> |
| 823 | |
| 824 | <p>So when checking an existing password, if pw_encrypt(text, |
| 825 | old_encrypted_password) returns a string that compares identical to |
| 826 | old_encrypted_password, you've got the right password. When setting a new |
| 827 | password, generate a random 8 character salt string, put it in the right |
| 828 | format with sprintf(buffer, "$%c$%s", type, salt), and feed buffer as the |
| 829 | second argument to pw_encrypt(text,buffer).</p> |
| 830 | |
| 831 | <h2><a name="tips_vfork">Fork and vfork</a></h2> |
| 832 | |
| 833 | <p>On systems that haven't got a Memory Management Unit, fork() is unreasonably |
| 834 | expensive to implement (and sometimes even impossible), so a less capable |
| 835 | function called vfork() is used instead. (Using vfork() on a system with an |
| 836 | MMU is like pounding a nail with a wrench. Not the best tool for the job, but |
| 837 | it works.)</p> |
| 838 | |
| 839 | <p>Busybox hides the difference between fork() and vfork() in |
| 840 | libbb/bb_fork_exec.c. If you ever want to fork and exec, use bb_fork_exec() |
| 841 | (which returns a pid and takes the same arguments as execve(), although in |
| 842 | this case envp can be NULL) and don't worry about it. This description is |
| 843 | here in case you want to know why that does what it does.</p> |
| 844 | |
| 845 | <p>Implementing fork() depends on having a Memory Management Unit. With an |
| 846 | MMU then you can simply set up a second set of page tables and share the |
| 847 | physical memory via copy-on-write. So a fork() followed quickly by exec() |
| 848 | only copies a few pages of the parent's memory, just the ones it changes |
| 849 | before freeing them.</p> |
| 850 | |
| 851 | <p>With a very primitive MMU (using a base pointer plus length instead of page |
| 852 | tables, which can provide virtual addresses and protect processes from each |
| 853 | other, but no copy on write) you can still implement fork. But it's |
| 854 | unreasonably expensive, because you have to copy all the parent process' |
| 855 | memory into the new process (which could easily be several megabytes per fork). |
| 856 | And you have to do this even though that memory gets freed again as soon as the |
| 857 | exec happens. (This is not just slow and a waste of space but causes memory |
| 858 | usage spikes that can easily cause the system to run out of memory.)</p> |
| 859 | |
| 860 | <p>Without even a primitive MMU, you have no virtual addresses. Every process |
| 861 | can reach out and touch any other process' memory, because all pointers are to |
| 862 | physical addresses with no protection. Even if you copy a process' memory to |
| 863 | new physical addresses, all of its pointers point to the old objects in the |
| 864 | old process. (Searching through the new copy's memory for pointers and |
| 865 | redirect them to the new locations is not an easy problem.)</p> |
| 866 | |
| 867 | <p>So with a primitive or missing MMU, fork() is just not a good idea.</p> |
| 868 | |
| 869 | <p>In theory, vfork() is just a fork() that writeably shares the heap and stack |
| 870 | rather than copying it (so what one process writes the other one sees). In |
| 871 | practice, vfork() has to suspend the parent process until the child does exec, |
| 872 | at which point the parent wakes up and resumes by returning from the call to |
| 873 | vfork(). All modern kernel/libc combinations implement vfork() to put the |
| 874 | parent to sleep until the child does its exec. There's just no other way to |
| 875 | make it work: the parent has to know the child has done its exec() or exit() |
| 876 | before it's safe to return from the function it's in, so it has to block |
| 877 | until that happens. In fact without suspending the parent there's no way to |
| 878 | even store separate copies of the return value (the pid) from the vfork() call |
| 879 | itself: both assignments write into the same memory location.</p> |
| 880 | |
| 881 | <p>One way to understand (and in fact implement) vfork() is this: imagine |
| 882 | the parent does a setjmp and then continues on (pretending to be the child) |
| 883 | until the exec() comes around, then the _exec_ does the actual fork, and the |
| 884 | parent does a longjmp back to the original vfork call and continues on from |
| 885 | there. (It thus becomes obvious why the child can't return, or modify |
| 886 | local variables it doesn't want the parent to see changed when it resumes.) |
| 887 | |
| 888 | <p>Note a common mistake: the need for vfork doesn't mean you can't have two |
| 889 | processes running at the same time. It means you can't have two processes |
| 890 | sharing the same memory without stomping all over each other. As soon as |
| 891 | the child calls exec(), the parent resumes.</p> |
| 892 | |
| 893 | <p>If the child's attempt to call exec() fails, the child should call _exit() |
| 894 | rather than a normal exit(). This avoids any atexit() code that might confuse |
| 895 | the parent. (The parent should never call _exit(), only a vforked child that |
| 896 | failed to exec.)</p> |
| 897 | |
| 898 | <p>(Now in theory, a nommu system could just copy the _stack_ when it forks |
| 899 | (which presumably is much shorter than the heap), and leave the heap shared. |
| 900 | Even with no MMU at all |
| 901 | In practice, you've just wound up in a multi-threaded situation and you can't |
| 902 | do a malloc() or free() on your heap without freeing the other process' memory |
| 903 | (and if you don't have the proper locking for being threaded, corrupting the |
| 904 | heap if both of you try to do it at the same time and wind up stomping on |
| 905 | each other while traversing the free memory lists). The thing about vfork is |
| 906 | that it's a big red flag warning "there be dragons here" rather than |
| 907 | something subtle and thus even more dangerous.)</p> |
| 908 | |
| 909 | <h2><a name="tips_sort_read">Short reads and writes</a></h2> |
| 910 | |
| 911 | <p>Busybox has special functions, bb_full_read() and bb_full_write(), to |
| 912 | check that all the data we asked for got read or written. Is this a real |
| 913 | world consideration? Try the following:</p> |
| 914 | |
| 915 | <pre>while true; do echo hello; sleep 1; done | tee out.txt</pre> |
| 916 | |
| 917 | <p>If tee is implemented with bb_full_read(), tee doesn't display output |
| 918 | in real time but blocks until its entire input buffer (generally a couple |
| 919 | kilobytes) is read, then displays it all at once. In that case, we _want_ |
| 920 | the short read, for user interface reasons. (Note that read() should never |
| 921 | return 0 unless it has hit the end of input, and an attempt to write 0 |
| 922 | bytes should be ignored by the OS.)</p> |
| 923 | |
| 924 | <p>As for short writes, play around with two processes piping data to each |
| 925 | other on the command line (cat bigfile | gzip > out.gz) and suspend and |
| 926 | resume a few times (ctrl-z to suspend, "fg" to resume). The writer can |
| 927 | experience short writes, which are especially dangerous because if you don't |
| 928 | notice them you'll discard data. They can also happen when a system is under |
| 929 | load and a fast process is piping to a slower one. (Such as an xterm waiting |
| 930 | on x11 when the scheduler decides X is being a CPU hog with all that |
| 931 | text console scrolling...)</p> |
| 932 | |
| 933 | <p>So will data always be read from the far end of a pipe at the |
| 934 | same chunk sizes it was written in? Nope. Don't rely on that. For one |
| 935 | counterexample, see <a href="http://www.faqs.org/rfcs/rfc896.html">rfc 896 |
| 936 | for Nagle's algorithm</a>, which waits a fraction of a second or so before |
| 937 | sending out small amounts of data through a TCP/IP connection in case more |
| 938 | data comes in that can be merged into the same packet. (In case you were |
| 939 | wondering why action games that use TCP/IP set TCP_NODELAY to lower the latency |
| 940 | on their their sockets, now you know.)</p> |
| 941 | |
| 942 | <h2><a name="tips_memory">Memory used by relocatable code, PIC, and static linking.</a></h2> |
| 943 | |
| 944 | <p>The downside of standard dynamic linking is that it results in self-modifying |
| 945 | code. Although each executable's pages are mmaped() into a process' address |
| 946 | space from the executable file and are thus naturally shared between processes |
| 947 | out of the page cache, the library loader (ld-linux.so.2 or ld-uClibc.so.0) |
| 948 | writes to these pages to supply addresses for relocatable symbols. This |
| 949 | dirties the pages, triggering copy-on-write allocation of new memory for each |
| 950 | processes' dirtied pages.</p> |
| 951 | |
| 952 | <p>One solution to this is Position Independent Code (PIC), a way of linking |
| 953 | a file so all the relocations are grouped together. This dirties fewer |
| 954 | pages (often just a single page) for each process' relocations. The down |
| 955 | side is this results in larger executables, which take up more space on disk |
| 956 | (and a correspondingly larger space in memory). But when many copies of the |
| 957 | same program are running, PIC dynamic linking trades a larger disk footprint |
| 958 | for a smaller memory footprint, by sharing more pages.</p> |
| 959 | |
| 960 | <p>A third solution is static linking. A statically linked program has no |
| 961 | relocations, and thus the entire executable is shared between all running |
| 962 | instances. This tends to have a significantly larger disk footprint, but |
| 963 | on a system with only one or two executables, shared libraries aren't much |
| 964 | of a win anyway.</p> |
| 965 | |
| 966 | <p>You can tell the glibc linker to display debugging information about its |
| 967 | relocations with the environment variable "LD_DEBUG". Try |
| 968 | "LD_DEBUG=help /bin/true" for a list of commands. Learning to interpret |
| 969 | "LD_DEBUG=statistics cat /proc/self/statm" could be interesting.</p> |
| 970 | |
| 971 | <p>For more on this topic, here's Rich Felker:</p> |
| 972 | <blockquote> |
| 973 | <p>Dynamic linking (without fixed load addresses) fundamentally requires |
| 974 | at least one dirty page per dso that uses symbols. Making calls (but |
| 975 | never taking the address explicitly) to functions within the same dso |
| 976 | does not require a dirty page by itself, but will with ELF unless you |
| 977 | use -Bsymbolic or hidden symbols when linking.</p> |
| 978 | |
| 979 | <p>ELF uses significant additional stack space for the kernel to pass all |
| 980 | the ELF data structures to the newly created process image. These are |
| 981 | located above the argument list and environment. This normally adds 1 |
| 982 | dirty page to the process size.</p> |
| 983 | |
| 984 | <p>The ELF dynamic linker has its own data segment, adding one or more |
| 985 | dirty pages. I believe it also performs relocations on itself.</p> |
| 986 | |
| 987 | <p>The ELF dynamic linker makes significant dynamic allocations to manage |
| 988 | the global symbol table and the loaded dso's. This data is never |
| 989 | freed. It will be needed again if libdl is used, so unconditionally |
| 990 | freeing it is not possible, but normal programs do not use libdl. Of |
| 991 | course with glibc all programs use libdl (due to nsswitch) so the |
| 992 | issue was never addressed.</p> |
| 993 | |
| 994 | <p>ELF also has the issue that segments are not page-aligned on disk. |
| 995 | This saves up to 4k on disk, but at the expense of using an additional |
| 996 | dirty page in most cases, due to a large portion of the first data |
| 997 | page being filled with a duplicate copy of the last text page.</p> |
| 998 | |
| 999 | <p>The above is just a partial list of the tiny memory penalties of ELF |
| 1000 | dynamic linking, which eventually add up to quite a bit. The smallest |
| 1001 | I've been able to get a process down to is 8 dirty pages, and the |
| 1002 | above factors seem to mostly account for it (but some were difficult |
| 1003 | to measure).</p> |
| 1004 | </blockquote> |
| 1005 | |
| 1006 | <h2><a name="tips_kernel_headers"></a>Including kernel headers</h2> |
| 1007 | |
| 1008 | <p>The "linux" or "asm" directories of /usr/include contain Linux kernel |
| 1009 | headers, so that the C library can talk directly to the Linux kernel. In |
| 1010 | a perfect world, applications shouldn't include these headers directly, but |
| 1011 | we don't live in a perfect world.</p> |
| 1012 | |
| 1013 | <p>For example, Busybox's losetup code wants linux/loop.c because nothing else |
| 1014 | #defines the structures to call the kernel's loopback device setup ioctls. |
| 1015 | Attempts to cut and paste the information into a local busybox header file |
| 1016 | proved incredibly painful, because portions of the loop_info structure vary by |
| 1017 | architecture, namely the type __kernel_dev_t has different sizes on alpha, |
| 1018 | arm, x86, and so on. Meaning we either #include <linux/posix_types.h> or |
| 1019 | we hardwire #ifdefs to check what platform we're building on and define this |
| 1020 | type appropriately for every single hardware architecture supported by |
| 1021 | Linux, which is simply unworkable.</p> |
| 1022 | |
| 1023 | <p>This is aside from the fact that the relevant type defined in |
| 1024 | posix_types.h was renamed to __kernel_old_dev_t during the 2.5 series, so |
| 1025 | to cut and paste the structure into our header we have to #include |
| 1026 | <linux/version.h> to figure out which name to use. (What we actually do is |
| 1027 | check if we're building on 2.6, and if so just use the new 64 bit structure |
| 1028 | instead to avoid the rename entirely.) But we still need the version |
| 1029 | check, since 2.4 didn't have the 64 bit structure.</p> |
| 1030 | |
| 1031 | <p>The BusyBox developers spent <u>two years</u> trying to figure |
| 1032 | out a clean way to do all this. There isn't one. The losetup in the |
| 1033 | util-linux package from kernel.org isn't doing it cleanly either, they just |
| 1034 | hide the ugliness by nesting #include files. Their mount/loop.h |
| 1035 | #includes "my_dev_t.h", which #includes <linux/posix_types.h> and |
| 1036 | <linux/version.h> just like we do. There simply is no alternative.</p> |
| 1037 | |
| 1038 | <p>Just because directly #including kernel headers is sometimes |
| 1039 | unavoidable doesn't me we should include them when there's a better |
| 1040 | way to do it. However, block copying information out of the kernel headers |
| 1041 | is not a better way.</p> |
| 1042 | |
| 1043 | <h2><a name="who">Who are the BusyBox developers?</a></h2> |
| 1044 | |
| 1045 | <p>The following login accounts currently exist on busybox.net. (I.E. these |
| 1046 | people can commit <a href="http://busybox.net/downloads/patches">patches</a> |
| 1047 | into subversion for the BusyBox, uClibc, and buildroot projects.)</p> |
| 1048 | |
| 1049 | <pre> |
| 1050 | aldot :Bernhard Fischer |
| 1051 | andersen :Erik Andersen <- uClibc and BuildRoot maintainer. |
| 1052 | bug1 :Glenn McGrath |
| 1053 | davidm :David McCullough |
| 1054 | gkajmowi :Garrett Kajmowicz <- uClibc++ maintainer |
| 1055 | jbglaw :Jan-Benedict Glaw |
| 1056 | jocke :Joakim Tjernlund |
| 1057 | landley :Rob Landley <- BusyBox maintainer |
| 1058 | lethal :Paul Mundt |
| 1059 | mjn3 :Manuel Novoa III |
| 1060 | osuadmin :osuadmin |
| 1061 | pgf :Paul Fox |
| 1062 | pkj :Peter Kjellerstedt |
| 1063 | prpplague :David Anders |
| 1064 | psm :Peter S. Mazinger |
| 1065 | russ :Russ Dill |
| 1066 | sandman :Robert Griebl |
| 1067 | sjhill :Steven J. Hill |
| 1068 | solar :Ned Ludd |
| 1069 | timr :Tim Riker |
| 1070 | tobiasa :Tobias Anderberg |
| 1071 | vapier :Mike Frysinger |
| 1072 | </pre> |
| 1073 | |
| 1074 | <p>The following accounts used to exist on busybox.net, but don't anymore so |
| 1075 | I can't ask /etc/passwd for their names. (If anybody would like to make |
| 1076 | a stab at it...)</p> |
| 1077 | |
| 1078 | <pre> |
| 1079 | aaronl |
| 1080 | beppu |
| 1081 | dwhedon |
| 1082 | erik : Also Erik Andersen? |
| 1083 | gfeldman |
| 1084 | jimg |
| 1085 | kraai |
| 1086 | markw |
| 1087 | miles |
| 1088 | proski |
| 1089 | rjune |
| 1090 | tausq |
| 1091 | vodz :Vladimir N. Oleynik |
| 1092 | </pre> |
| 1093 | |
| 1094 | |
Eric Andersen | 6c4a6b1 | 2004-10-08 10:50:08 +0000 | [diff] [blame] | 1095 | <br> |
| 1096 | <br> |
| 1097 | <br> |
| 1098 | |
| 1099 | <!--#include file="footer.html" --> |