docs/busybox.net/programming.html

   1 <!--#include file="header.html" -->
   2
   3 <h2>Rob's notes on programming busybox.</h2>
   4
   5 <ul>
   6   <li><a href="#goals">What are the goals of busybox?</a></li>
   7   <li><a href="#design">What is the design of busybox?</a></li>
   8   <li><a href="#source">How is the source code organized?</a></li>
   9   <ul>
  10     <li><a href="#source_applets">The applet directories.</a></li>
  11     <li><a href="#source_libbb">The busybox shared library (libbb)</a></li>
  12   </ul>
  13   <li><a href="#adding">Adding an applet to busybox</a></li>
  14   <li><a href="#standards">What standards does busybox adhere to?</a></li>
  15 </ul>
  16
  17 <h2><b><a name="goals" />What are the goals of busybox?</b></h2>
  18
  19 <p>Busybox aims to be the smallest and simplest correct implementation of the
  20 standard Linux command line tools.  First and foremost, this means the
  21 smallest executable size we can manage.  We also want to have the simplest
  22 and cleanest implementation we can manage, be <a href="#standards">standards
  23 compliant</a>, minimize run-time memory usage (heap and stack), run fast, and
  24 take over the world.</p>
  25
  26 <h2><b><a name="design" />What is the design of busybox?</b></h2>
  27
  28 <p>Busybox is like a swiss army knife: one thing with many functions.
  29 The busybox executable can act like many different programs depending on
  30 the name used to invoke it.  Normal practice is to create a bunch of symlinks
  31 pointing to the busybox binary, each of which triggers a different busybox
  32 function.  (See <a href="FAQ.html#getting_started">getting started</a> in the
  33 FAQ for more information on usage, and <a href="BusyBox.html">the
  34 busybox documentation</a> for a list of symlink names and what they do.)
  35
  36 <p>The "one binary to rule them all" approach is primarily for size reasons: a
  37 single multi-purpose executable is smaller then many small files could be.
  38 This way busybox only has one set of ELF headers, it can easily share code
  39 between different apps even when statically linked, it has better packing
  40 efficiency by avoding gaps between files or compression dictionary resets,
  41 and so on.</p>
  42
  43 <p>Work is underway on new options such as "make standalone" to build separate
  44 binaries for each applet, and a "libbb.so" to make the busybox common code
  45 available as a shared library.  Neither is ready yet at the time of this
  46 writing.</p>
  47
  48 <a name="source" />
  49
  50 <h2><a name="source_applets" /><b>The applet directories</b></h2>
  51
  52 <p>The directory "applets" contains the busybox startup code (applets.c and
  53 busybox.c), and several subdirectories containing the code for the individual
  54 applets.</p>
  55
  56 <p>Busybox execution starts with the main() function in applets/busybox.c,
  57 which sets the global variable bb_applet_name to argv[0] and calls
  58 run_applet_by_name() in applets/applets.c.  That uses the applets[] array
  59 (defined in include/busybox.h and filled out in include/applets.h) to
  60 transfer control to the appropriate APPLET_main() function (such as
  61 cat_main() or sed_main()).  The individual applet takes it from there.</p>
  62
  63 <p>This is why calling busybox under a different name triggers different
  64 functionality: main() looks up argv[0] in applets[] to get a function pointer
  65 to APPLET_main().</p>
  66
  67 <p>Busybox applets may also be invoked through the multiplexor applet
  68 "busybox" (see busybox_main() in applets/busybox.c), and through the
  69 standalone shell (grep for STANDALONE_SHELL in applets/shell/*.c).
  70 See <a href="FAQ.html#getting_started">getting started</a> in the
  71 FAQ for more information on these alternate usage mechanisms, which are
  72 just different ways to reach the relevant APPLET_main() function.</p>
  73
  74 <p>The applet subdirectories (archival, console-tools, coreutils,
  75 debianutils, e2fsprogs, editors, findutils, init, loginutils, miscutils,
  76 modutils, networking, procps, shell, sysklogd, and util-linux) correspond
  77 to the configuration sub-menus in menuconfig.  Each subdirectory contains the
  78 code to implement the applets in that sub-menu, as well as a Config.in
  79 file defining that configuration sub-menu (with dependencies and help text
  80 for each applet), and the makefile segment (Makefile.in) for that
  81 subdirectory.</p>
  82
  83 <p>The run-time --help is stored in usage_messages[], which is initialized at
  84 the start of applets/applets.c and gets its help text from usage.h.  During the
  85 build this help text is also used to generate the BusyBox documentation (in
  86 html, txt, and man page formats) in the docs directory.  See
  87 <a href="#adding">adding an applet to busybox</a> for more
  88 information.</p>
  89
  90 <h2><a name="source_libbb" /><b>libbb</b></h2>
  91
  92 <p>Most non-setup code shared between busybox applets lives in the libbb
  93 directory.  It's a mess that evolved over the years without much auditing
  94 or cleanup.  For anybody looking for a great project to break into busybox
  95 development with, documenting libbb would be both incredibly useful and good
  96 experience.</p>
  97
  98 <p>Common themes in libbb include allocation functions that test
  99 for failure and abort the program with an error message so the caller doesn't
 100 have to test the return value (xmalloc(), xstrdup(), etc), wrapped versions
 101 of open(), close(), read(), and write() that test for their own failures
 102 and/or retry automatically, linked list management functions (llist.c),
 103 command line argument parsing (getopt_ulflags.c), and a whole lot more.</p>
 104
 105 <h2><a name="adding" /><b>Adding an applet to busybox</b></h2>
 106
 107 <p>To add a new applet to busybox, first pick a name for the applet and
 108 a corresponding CONFIG_NAME.  Then do this:</p>
 109
 110 <ul>
 111 <li>Figure out where in the busybox source tree your applet best fits,
 112 and put your source code there.  Be sure to use APPLET_main() instead
 113 of main(), where APPLET is the name of your applet.</li>
 114
 115 <li>Add your applet to the relevant Config.in file (which file you add
 116 it to determines where it shows up in "make menuconfig").  This uses
 117 the same general format as the linux kernel's configuration system.</li>
 118
 119 <li>Add your applet to the relevant Makefile.in file (in the same
 120 directory as the Config.in you chose), using the existing entries as a
 121 template and the same CONFIG symbol as you used for Config.in.  (Don't
 122 forget "needlibm" or "needcrypt" if your applet needs libm or
 123 libcrypt.)</li>
 124
 125 <li>Add your applet to "include/applets.h", using one of the existing
 126 entries as a template.  (Note: this is in alphabetical order.  Applets
 127 are found via binary search, and if you add an applet out of order it
 128 won't work.)</li>
 129
 130 <li>Add your applet's runtime help text to "include/usage.h".  You need
 131 at least appname_trivial_usage (the minimal help text, always included
 132 in the busybox binary when this applet is enabled) and appname_full_usage
 133 (extra help text included in the busybox binary with
 134 CONFIG_FEATURE_VERBOSE_USAGE is enabled), or it won't compile.
 135 The other two help entry types (appname_example_usage and
 136 appname_notes_usage) are optional.  They don't take up space in the binary,
 137 but instead show up in the generated documentation (BusyBox.html,
 138 BusyBox.txt, and the man page BusyBox.1).</li>
 139
 140 <li>Run menuconfig, switch your applet on, compile, test, and fix the
 141 bugs.  Be sure to try both "allyesconfig" and "allnoconfig" (and
 142 "allbareconfig" if relevant).</li>
 143
 144 </ul>
 145
 146 <h2><a name="standards" />What standards does busybox adhere to?</a></h2>
 147
 148 <p>The standard we're paying attention to is the "Shell and Utilities"
 149 portion of the <a href=http://www.opengroup.org/onlinepubs/009695399/>Open
 150 Group Base Standards</a> (also known as the Single Unix Specification version
 151 3 or SUSv3).  Note that paying attention isn't necessarily the same thing as
 152 following it.</p>
 153
 154 <p>SUSv3 doesn't even mention things like init, mount, tar, or losetup, nor
 155 commonly used options like echo's '-e' and '-n', or sed's '-i'.  Busybox is
 156 driven by what real users actually need, not the fact the standard believes
 157 we should implement ed or sccs.  For size reasons, we're unlikely to include
 158 much internationalization support beyond UTF-8, and on top of all that, our
 159 configuration menu lets developers chop out features to produce smaller but
 160 very non-standard utilities.</p>
 161
 162 <p>Also, Busybox is aimed primarily at Linux.  Unix standards are interesting
 163 because Linux tries to adhere to them, but portability to dozens of platforms
 164 is only interesting in terms of offering a restricted feature set that works
 165 everywhere, not growing dozens of platform-specific extensions.  Busybox
 166 should be portable to all hardware platforms Linux supports, and any other
 167 similar operating systems that are easy to do and won't require much
 168 maintenance.</p>
 169
 170 <p>In practice, standards compliance tends to be a clean-up step once an
 171 applet is otherwise finished.  When polishing and testing a busybox applet,
 172 we ensure we have at least the option of full standards compliance, or else
 173 document where we (intentionally) fall short.</p>
 174
 175 <br>
 176 <br>
 177 <br>
 178
 179 <!--#include file="footer.html" -->