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 15it seems silly to capitalize the project name, but not capitalizing the 16start 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> 23and <a href=http://landley.net/notes-2006.html#28-09-2006>started over from 24scratch</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 29in November 2011</a> with a new goal to 30<a href=http://landley.net/aboriginal/about.html#selfhost>make Android 31self-hosting</a>. This involved me relicensing my own 32code, which <a href=https://lwn.net/Articles/478308/>made people who had 33never used or participated in the project loudly angry</a>. The switch came 34after a lot of thinking <a href=http://landley.net/talks/ohio-2013.txt>about 35licenses</a> and <a href=http://landley.net/notes-2011.html#21-03-2011>the 36transition 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 39out 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 41it 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 45by almost a decade but Android still doesn't ship with it because GPLv3 came 46out around the same time Android did and caused many people to throw 47out the GPLv2 baby with the GPLv3 bathwater. 48Android <a href=https://source.android.com/source/licenses.html>explicitly 49discourages</a> use of GPL and LGPL licenses in its products, and has gradually 50reimplemented historical GPL components such as its bluetooth stack under the 51Apache 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 53development of new projects (clang/llvm/lld) to replace them, 54implemented its SMB server from scratch to replace samba, 55<a href=http://meta.ath0.com/2012/02/05/apples-great-gpl-purge/>and so 56on</a>. Toybox itself exists because somebody with in a legacy position 57just wouldn't shut up about GPLv3, otherwise I would probably 58still happily be maintaining BusyBox. (For more on how I wound 59up 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 65hardware and distributions released up to 7 years ago, and feel ok dropping 66support for stuff older than that. (This is a little longer than Ubuntu's 67Long 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 70build-time configure test for it and let the functionality cleanly drop out. 71I also keep old Ubuntu images around in VMs and perform the occasional 72defconfig build there to see what breaks. (I'm not perfect about this, 73but I accept bug reports.)</p> 74 75<p>My original theory was "4 to 5 18-month cycles of moore's law should cover 76the vast majority of the installed base of PC hardware", loosely based on some 77research I did <a href=http://www.catb.org/esr/halloween/halloween9.html#id2867629>back in 2003</a> 78and <a href=http://catb.org/esr/writings/world-domination/world-domination-201.html#id248066>updated in 2006</a> 79which said that low end systems were 2 iterations of moore's 80law below the high end systems, and that another 2-3 iterations should cover 81the useful lifetime of most systems no longer being sold but still in use and 82potentially 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 85industry changes</a> in the 1990's that stretched the gap 86from low end to high end from 2 cycles to 4 cycles, and _that_ analysis 87ignored the switch from PC to smartphone cutting off the R&D air supply of the 88laptop market. Meanwhile the Moore's Law s-curve started bending 89down in 2000 and these days is pretty flat because the drive for faster clock 90speeds <a href=http://www.anandtech.com/show/613>stumbled</a> 91then <a href=http://www.pcworld.com/article/118603/article.html>died</a>, and 92the subsequent drive to go wide maxed out around 4x SMP with ~2 megabyte 93caches for most applications. These days the switch from exponential to 94linear 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 99feature is less than 7 years old, I try to have a build-time configure test 100for it and let the functionality cleanly drop out. I also keep old Ubuntu 101images around in VMs and perform the occasional defconfig build there to 102see 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>, 108and the <a href=about.html>about page</a> summarizes what we're trying to 109accomplish, 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; 113make; make install</b>". Type "<b>make help</b>" to 114see available make targets.</p> 115 116<p><b>The configure stage is copied from the Linux kernel</b> (in the "kconfig" 117directory), and saves your selections in the file ".config" at the top 118level. The "defconfig" target selects the 119maximum sane configuration (enabling all the commands and features that 120aren't unfinished, only intended as examples, debug code, etc) and is 121probably what you want. You can use "make menuconfig" to manually select 122specific commands to include, through an interactive menu (cursor up and 123down, enter to descend into a sub-menu, space to select an entry, ? to see 124an entry's help text, esc to exit). The menuconfig help text is the 125same as the command's --help output.</p> 126 127<p><b>The "make" stage creates a toybox binary</b> (which is stripped, look in 128generated/unstripped for the debug versions), and "install" adds a bunch of 129symlinks to toybox under the various command names. Toybox determines which 130command to run based on the filename, or you can use the "toybox" name in which case the first 131argument is the command to run (ala "toybox ls -l"). <b>You can also build 132individual 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>, 135along with setup plumbing and selecting which command to run this time. 136The function toybox_main() implements the "toybox" multiplexer command.</p> 137 138<p><b>The individual command implementations are under "toys"</b>, and are grouped 139into categories (mostly based on which standard they come from, posix, lsb, 140android...) The "pending" directory contains unfinished commands, and the 141"examples" directory contains examples. Commands in those two directories 142are _not_ selected by defconfig. (These days pending directory is mostly 143third 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 146commands call lib/args.c to parse their command line arguments before calling 147the command's own main() function, which uses the option string in 148the command's NEWTOY() macro. This is similar to the libc function getopt(), 149but 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 153created from other files, which are <a href=code.html#generated>described</a> 154in the code walkthrough. All the 155build's temporary files live under generated, including the .o files built 156from the .c files (in generated/obj). The "make clean" target deletes that 157directory. ("make distclean" also deletes your .config and deletes the 158kconfig 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>. 162Usually you <a href=code.html#adding>start a new command</a> by copying an 163existing command file to a new filename 164(toys/examples/hello.c, toys/examples/skeleton.c, toys/posix/cat.c, 165and toys/posix/true.c have all been used for this purpose) and then replacing 166all instances of its old name with the new name (which should match the 167new filename), and modifying the help text, argument string, and what the 168code does. You might have to "make distclean" before you new command 169shows up in defconfig or menuconfig.</p> 170 171<p><b>The toybox test suite lives in the "tests" directory</b>. From the top 172level you can "make tests" to test everything, or "make test_sed" test a 173single command's standalone version (which should behave identically) 174but that's why we test.</p> 175 176<!--#include file="footer.html" --> 177