www/faq.html

   1 <html><head><title>toybox news</title>
   2 <!--#include file="header.html" -->
   3
   4 <ul>
   5 <li><h2><a href="#capitalize">Do you capitalize toybox?</a></h2></li>
   6 <li><h2><a href="#why_toybox">Why toybox? (What was wrong with busybox?)</a></h2></li>
   7 <li><h2><a href="#support_horizon">Why a 7 year support horizon?</a></h2></li>
   8 <li><h2><a href="#code">Where do I start understanding the toybox source code?</a></h2></li>
   9 </ul>
  10
  11 <a name="capitalize" />
  12 <h2>Q: Do you capitalize toybox?</h2>
  13
  14 <p>A: Only at the start of a sentence. The command name is all lower case so
  15 it seems silly to capitalize the project name, but not capitalizing the
  16 start of sentences is awkward, so... compromise. (It is _not_ "ToyBox".)</p>
  17
  18 <a name="why_toybox" />
  19 <h2>Q: "Why is there toybox? What was wrong with busybox?"</h2>
  20
  21 <p>A: Toybox started back in 2006 when I
  22 <a href=https://lwn.net/Articles/202106/>handed off BusyBox maintainership</a>
  23 and <a href=http://landley.net/notes-2006.html#28-09-2006>started over from
  24 scratch</a> on a new codebase after a
  25 <a href=http://lists.busybox.net/pipermail/busybox/2006-September/058617.html>protracted licensing argument</a> took all the fun out of working on BusyBox.</p>
  26
  27 <p>Toybox was just a personal project until it got
  28 <a href=http://landley.net/notes-2011.html#13-11-2011>relaunched
  29 in November 2011</a> with a new goal to
  30 <a href=http://landley.net/aboriginal/about.html#selfhost>make Android
  31 self-hosting</a>. This involved me relicensing my own
  32 code, which <a href=https://lwn.net/Articles/478308/>made people who had
  33 never used or participated in the project loudly angry</a>. The switch came
  34 after a lot of thinking <a href=http://landley.net/talks/ohio-2013.txt>about
  35 licenses</a> and <a href=http://landley.net/notes-2011.html#21-03-2011>the
  36 transition to smartphones</a>, which led to a
  37 <a href=http://landley.net/talks/celf-2013.txt>2013</a>
  38 <a href=https://www.youtube.com/watch?v=SGmtP5Lg_t0>talk</a> laying
  39 out a strategy to make Android self-hosting using toybox. This helped
  40 <a href=https://code.google.com/p/android/issues/detail?id=76861>bring
  41 it to Android's attention</a>, and they
  42 <a href=https://lwn.net/Articles/629362/>merged it</a> into Android M.</p>
  43
  44 <p>The answer to the second question is "licensing". BusyBox predates Android
  45 by almost a decade but Android still doesn't ship with it because GPLv3 came
  46 out around the same time Android did and caused many people to throw
  47 out the GPLv2 baby with the GPLv3 bathwater.
  48 Android <a href=https://source.android.com/source/licenses.html>explicitly
  49 discourages</a> use of GPL and LGPL licenses in its products, and has gradually
  50 reimplemented historical GPL components such as its bluetooth stack under the
  51 Apache license. Similarly, Apple froze xcode at the last GPLv2 releases
  52 (GCC 4.2.1 with binutils 2.17) for over 5 years while it sponsored the
  53 development of new projects (clang/llvm/lld) to replace them,
  54 implemented its SMB server from scratch to replace samba,
  55 <a href=http://meta.ath0.com/2012/02/05/apples-great-gpl-purge/>and so
  56 on</a>. Toybox itself exists because somebody with in a legacy position
  57 just wouldn't shut up about GPLv3, otherwise I would probably
  58 still happily be maintaining BusyBox. (For more on how I wound
  59 up working on busybox in the first place,
  60 <a href=http://landley.net/aboriginal/history.html>see here</a>.)</p>
  61
  62 <h2><a name="support_horizon">Q: Why a 7 year support horizon?</a></h2>
  63
  64 <p>A: Our <a href=http://lists.busybox.net/pipermail/busybox/2006-September/058440.html>longstanding rule of thumb</a> is to try to run and build on
  65 hardware and distributions released up to 7 years ago, and feel ok dropping
  66 support for stuff older than that. (This is a little longer than Ubuntu's
  67 Long Term Support, but not by much.)</p>
  68
  69 <p>If a kernel or libc feature is less than 7 years old, I try to have a
  70 build-time configure test for it and let the functionality cleanly drop out.
  71 I also keep old Ubuntu images around in VMs and perform the occasional
  72 defconfig build there to see what breaks. (I'm not perfect about this,
  73 but I accept bug reports.)</p>
  74
  75 <p>My original theory was "4 to 5 18-month cycles of moore's law should cover
  76 the vast majority of the installed base of PC hardware", loosely based on some
  77 research I did <a href=http://www.catb.org/esr/halloween/halloween9.html#id2867629>back in 2003</a>
  78 and <a href=http://catb.org/esr/writings/world-domination/world-domination-201.html#id248066>updated in 2006</a>
  79 which said that low end systems were 2 iterations of moore's
  80 law below the high end systems, and that another 2-3 iterations should cover
  81 the useful lifetime of most systems no longer being sold but still in use and
  82 potentially being upgraded to new software releases.</p>
  83
  84 <p>It turns out <a href=http://landley.net/notes-2011.html#26-06-2011>I missed
  85 industry changes</a> in the 1990's that stretched the gap
  86 from low end to high end from 2 cycles to 4 cycles, and _that_ analysis
  87 ignored the switch from PC to smartphone cutting off the R&D air supply of the
  88 laptop market.  Meanwhile the Moore's Law s-curve started bending
  89 down in 2000 and these days is pretty flat because the drive for faster clock
  90 speeds <a href=http://www.anandtech.com/show/613>stumbled</a>
  91 then <a href=http://www.pcworld.com/article/118603/article.html>died</a>, and
  92 the subsequent drive to go wide maxed out around 4x SMP with ~2 megabyte
  93 caches for most applications. These days the switch from exponential to
  94 linear growth in hardware capabilities is
  95 <a href=https://www.cnet.com/news/end-of-moores-law-its-not-just-about-physics/>common</a>
  96 <a href=http://www.acm.org/articles/people-of-acm/2016/david-patterson>knowledge</a>.</p>
  97
  98 <p>But the 7 year rule of thumb stuck around anyway: if a kernel or libc
  99 feature is less than 7 years old, I try to have a build-time configure test
 100 for it and let the functionality cleanly drop out. I also keep old Ubuntu
 101 images around in VMs and perform the occasional defconfig build there to
 102 see what breaks.</p>
 103
 104 <h2><a name="code" />Where do I start understanding the source code?</h2>
 105
 106 <p>Toybox is written in C. There are longer writeups of the
 107 <a href=design.html>design ideas</a> and a <a href=code.html>code walkthrough</a>,
 108 and the <a href=about.html>about page</a> summarizes what we're trying to
 109 accomplish, but here's a quick start:</p>
 110
 111 <p>Toybox uses the standard three stage configure/make/install
 112 <a href=code.html#building>build</a>, in this case "<b>make defconfig;
 113 make; make install</b>". Type "<b>make help</b>" to
 114 see available make targets.</p>
 115
 116 <p><b>The configure stage is copied from the Linux kernel</b> (in the "kconfig"
 117 directory), and saves your selections in the file ".config" at the top
 118 level. The "defconfig" target selects the
 119 maximum sane configuration (enabling all the commands and features that
 120 aren't unfinished, only intended as examples, debug code, etc) and is
 121 probably what you want. You can use "make menuconfig" to manually select
 122 specific commands to include, through an interactive menu (cursor up and
 123 down, enter to descend into a sub-menu, space to select an entry, ? to see
 124 an entry's help text, esc to exit). The menuconfig help text is the
 125 same as the command's --help output.</p>
 126
 127 <p><b>The "make" stage creates a toybox binary</b> (which is stripped, look in
 128 generated/unstripped for the debug versions), and "install" adds a bunch of
 129 symlinks to toybox under the various command names. Toybox determines which
 130 command to run based on the filename, or you can use the "toybox" name in which case the first
 131 argument is the command to run (ala "toybox ls -l"). <b>You can also build
 132 individual commands as standalone executables</b>, ala "make sed cat ls".</p>
 133
 134 <p><b>The main() function is in main.c at the top level</b>,
 135 along with setup plumbing and selecting which command to run this time.
 136 The function toybox_main() implements the "toybox" multiplexer command.</p>
 137
 138 <p><b>The individual command implementations are under "toys"</b>, and are grouped
 139 into categories (mostly based on which standard they come from, posix, lsb,
 140 android...) The "pending" directory contains unfinished commands, and the
 141 "examples" directory contains examples. Commands in those two directories
 142 are _not_ selected by defconfig. (These days pending directory is mostly
 143 third party submissions that have not yet undergone proper code review.)</p>
 144
 145 <p><b>Common infrastructure shared between commands is under "lib"</b>. Most
 146 commands call lib/args.c to parse their command line arguments before calling
 147 the command's own main() function, which uses the option string in
 148 the command's NEWTOY() macro. This is similar to the libc function getopt(),
 149 but more powerful, and is documented at the top of lib/args.c.</p>
 150
 151 <p>Most of the actual <b>build/install infrastructure is shell scripts under
 152 "scripts"</b>. <b>These populate the "generated" directory</b> with headers
 153 created from other files, which are <a href=code.html#generated>described</a>
 154 in the code walkthrough. All the
 155 build's temporary files live under generated, including the .o files built
 156 from the .c files (in generated/obj). The "make clean" target deletes that
 157 directory. ("make distclean" also deletes your .config and deletes the
 158 kconfig binaries that process .config.)</p>
 159
 160 <p>Each command's file contains all the information for that command, so
 161 <b>adding a command to toybox means adding a single file under "toys"</b>.
 162 Usually you <a href=code.html#adding>start a new command</a> by copying an
 163 existing command file to a new filename
 164 (toys/examples/hello.c, toys/examples/skeleton.c, toys/posix/cat.c,
 165 and toys/posix/true.c have all been used for this purpose) and then replacing
 166 all instances of its old name with the new name (which should match the
 167 new filename), and modifying the help text, argument string, and what the
 168 code does. You might have to "make distclean" before you new command
 169 shows up in defconfig or menuconfig.</p>
 170
 171 <p><b>The toybox test suite lives in the "tests" directory</b>. From the top
 172 level you can "make tests" to test everything, or "make test_sed" test a
 173 single command's standalone version (which should behave identically)
 174 but that's why we test.</p>
 175
 176 <!--#include file="footer.html" -->