diff options
| author | Rob Landley <rob@landley.net> | 2006-01-22 01:44:29 +0000 |
|---|---|---|
| committer | Rob Landley <rob@landley.net> | 2006-01-22 01:44:29 +0000 |
| commit | aaffef4d338f6f3d554eb0428e572ebbd5e00476 (patch) | |
| tree | 2b9261eea1e506036056b35da004b4f4b9bffee2 /docs | |
| parent | f9d40d6815aedda4b950ee642c6b0ca139481e91 (diff) | |
| download | busybox-w32-aaffef4d338f6f3d554eb0428e572ebbd5e00476.tar.gz busybox-w32-aaffef4d338f6f3d554eb0428e572ebbd5e00476.tar.bz2 busybox-w32-aaffef4d338f6f3d554eb0428e572ebbd5e00476.zip | |
Start of developer documentation for busybox.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/busybox.net/programming.html | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/docs/busybox.net/programming.html b/docs/busybox.net/programming.html new file mode 100644 index 000000000..e44f291b3 --- /dev/null +++ b/docs/busybox.net/programming.html | |||
| @@ -0,0 +1,179 @@ | |||
| 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" --> | ||