1<html><head><title>What is toybox?</title> 2<!--#include file="header.html" --> 3 4<h2><a name="what" />What is toybox?</h2> 5 6<p>Toybox combines many common Linux command line utilities together into 7a single <a href=license.html>BSD-licensed</a> executable. It's simple, small, fast, and reasonably 8standards-compliant (<a href=http://opengroup.org/onlinepubs/9699919799>POSIX-2008</a> and <a href=http://refspecs.linuxfoundation.org/LSB_4.1.0>LSB 4.1</a>).</p> 9 10<p>Toybox's main goal is to make Android 11<a href=http://landley.net/aboriginal/about.html#selfhost>self-hosting</a> 12by improving Android's command line utilities so it can 13build an installable Android Open Source Project image 14entirely from source under a stock Android system. After a talk at the 2013 15Embedded Linux Conference explaining this plan 16(<a href=http://landley.net/talks/celf-2013.txt>outline</a>, 17<a href=https://www.youtube.com/watch?v=SGmtP5Lg_t0>video</a>), Google 18<a href=https://lwn.net/Articles/629362/>merged toybox into AOSP</a> and 19began shipping toybox in Android Mashmallow.</p> 20 21<p>Toybox aims to provide one quarter of a theoretical "minimal native 22development environment", which is the simplest Linux system capable of 23rebuilding itself from source code and then building 24<a href=http://linuxfromscratch.org/lfs>Linux From Scratch</a> 25and the <a href=https://source.android.com>Android Open Source Project</a> 26under the result. In theory, this should only require four packages: 271) a set of posix-ish command line utilities, 282) a compiler<a name="1_back"></a><sup><font size=-3><a href=#1>[1]</a></font></sup>, 293) a C library, and 4) a kernel. This provides a reproducible and auditable 30base system, which with the addition of a few convienciences (vi, top, 31shell command line history...) can provide a usable interactive experience 32rather than just a headless build server.</p> 33 34<b><h2><a name="why" />Why is toybox?</h2></b> 35 36<p>The <a href=http://landley.net/talks/celf-2013.txt>2013 toybox talk</a> 37at ELC was devoted to this question, and has the following sections:</p> 38 39<ul> 40<li>0m29s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=0m29s>The smartphone is replacing the PC</a></li> 41 <ul> 42 <li>4m22s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=4m22s>Software needed to become self-hosting</a></li> 43 <li>6m20s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=6m20s>Do we care if android or iphone wins?</a></li> 44 </ul> 45<li>9m45s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=9m45s>Android not vanilla: oppose or accept?</a></li> 46 <ul> 47 <li>11m30s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=11m30s>Open source can't do User Interfaces</a></li> 48 </ul> 49<li>15m09s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=15m09s>Android is not copyleft: oppose or accept?</a></li> 50<li>18m23s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=18m23s>Security issues</a></li> 51<li>21m15s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=21m15s>Solutions to the software problems</a></li> 52 <ul> 53 <li>22m55s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=22m55s>What toybox needs to be/do</a></li> 54 <li>28m17s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=28m17s>What is toybox?</a></li> 55 <ul> 56 <li>28m58s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=28m58s>Why toybox started...</a></li> 57 <li>37m50s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=37m50s>What does toybox actually implement?</a></li> 58 </ul> 59 </ul> 60</ul> 61 62<p>A more recent talk from 2019 compares 63<a href=https://www.youtube.com/watch?v=MkJkyMuBm3g#t=1m18s>BusyBox vs toybox</a> 64and explains the design decisions behind both. 65(A 2015 toybox talk was part of the channel 66<a href=https://marc.info/?l=linux-embedded&m=158159902514847&w=2>accidentally deleted</a> off youtube by the Linux Foundation, 67but the <a href=https://landley.net/talks/celf-2015.txt>outline</a> is 68still available.)</p> 69 70<b><h2><a name="context" />What context was toybox created in?</h2></b> 71 72<p>The toybox maintainer's previous minimal self-hosting system project, 73<a href=http://landley.net/aboriginal/about.html>Aboriginal Linux</a>, 74got a native development environment down to only seven packages in 75its 1.0 release (busybox, uClibc, gcc, binutils, make, bash, and linux) 76and then built Linux From Scratch under the result. That project 77<a href=http://landley.net/aboriginal/history.html>was the reason</a> 78toybox's maintainer became busybox maintainer, having done so 79much work to extend busybox to replace all the gnu tools in a Linux From 80Scratch build that the previous maintainer handed over the project (to 81spend more time on buildroot).</p> 82 83<p>Despite the maintainer's history with busybox, toybox is a fresh 84from-scratch implementation under an 85<a href=https://source.android.com/source/licenses.html>android-compatible</a> 86<a href=license.html>license</a>. Busybox predates Android, but has never 87shipped with Android due to the license. As long as we're starting over anyway, 88we can do a better job.</p> 89 90<p>Toybox's current minimal native development environment builder is a new 91<a href=https://github.com/landley/toybox/blob/master/scripts/mkroot.sh>tiny 92implementation</a> integrated into the toybox source. 93The "make root" target will create a simple toybox chroot 94(by default in the root/host directory), and adding a LINUX= argument to 95the make command line pointing to Linux kernel source code creates a tiny 96bootable system with a wrapper script to run it under the emulator 97<a href=https://qemu.org>qemu</a>.</p> 98 99<p>The list of commands remaining before we can build Linux From Scratch under 100the result (with an appropriate 101<a href=https://github.com/landley/toybox/blob/master/scripts/mcm-buildall.sh>compiler</a>) 102is tracked <a href=roadmap.html#dev_env>in 103the roadmap</a>, and doing so is one of the main goals for toybox's 1.0 104release.</p> 105 106<p>Building LFS requres fewer commands than building AOSP, which has a lot more 107<a href=http://source.android.com/source/initializing.html>build 108prerequisites</a>. In theory some of those can be built from source 109as external packages (we're clearly not including our own java implementation), 110but some early prerequisites may need to be added to bootstrap AOSP far enough 111to build them (such as a read-only version of "git": 112how does repo download the AOSP source otherwise?) 113<a name="2_back"></a><sup><font size=-3><a href=#2>[2]</a></font></sup></p> 114 115<b><h2><a name="status" />What commands are planned/implemented in toybox?</h2></b> 116 117<p>The current list of commands implemented by toybox is on the 118<a href=status.html>status page</a>, which is updated each release. 119There is also a <a href=roadmap.html>roadmap</a> listing all planned commands 120for the 1.0 release and the reasons for including them.</p> 121 122<p>In general, configuring toybox with "make defconfig" enables all the commands 123compete enough to be useful. Configuring "allyesconfig" enables partially 124implemented commands as well, along with debugging features.</p> 125 126<b><h3>Relevant Standards</h3></b> 127 128<p>Most commands are implemented according to POSIX-2008 (I.E. 129<a href=http://opengroup.org/onlinepubs/9699919799/idx/utilities.html>The 130Single Unix Specification version 4</a>) where applicable. This does not mean 131that toybox is implementing every SUSv4 utility: some such as SCCS and ed are 132obsolete, while others such as c99 are outside the scope of the project. 133Toybox also isn't implementing full internationalization support: it should be 1348-bit clean and handle UTF-8, but otherwise we leave this to X11 and higher 135layers. And some things (like $CDPATH support in "cd") await a good 136explanation of why to bother with them. (POSIX provides an important 137frame of reference, but is not an infallable set of commandments to be blindly 138obeyed. We do try to document our deviations from it in the comment section 139at the start of each command under toys/posix.)</p> 140 141<p>The other major sources of commands are the Linux man pages, the 142Linux Standard Base, and testing the behavior of existing command 143implementations (although not generally looking at their 144source code), including the commands in Android's toolbox. SUSv4 does not 145include many basic commands such as "mount", "init", and "mke2fs", which are 146kind of nice to have.</p> 147 148<p>For more on this see the <a href=roadmap.html>roadmap</a> and 149<a href=design.html>design goals</a>.</p> 150 151<b><h2><a name="downloads" />Download</h2></b> 152 153<p>This project is maintained as a <a href=https://github.com/landley/toybox>git 154archive</a>, and also offers <a href=http://landley.net/toybox/downloads>source 155tarballs</a> and <a href=http://landley.net/toybox/bin>static binaries</a> 156of the release versions.</p> 157 158<p>The maintainer's <a href=http://landley.net/notes.html>development log</a> and the project's 159<a href=http://lists.landley.net/listinfo.cgi/toybox-landley.net>mailing 160list</a> are also good ways to track what's going on with the project.</p> 161 162<b><h2><a name="toycans" />What's the toybox logo image?</h2></b> 163 164<p>It's <a href=toycans-big.jpg>carefully stacked soda cans</a>. Specifically, 165it's a bunch of the original "Coke Zero" and "Pepsi One" cans, circa 2006, 166stacked to spell out the binary values of the ascii string "Toybox", with 167null terminator at the bottom. (The big picture's on it's side because 168the camera was held sideways to get a better shot.)</p> 169 170<p>No, it's not photoshopped, I actually had these cans until a coworker 171who Totally Did Not Get It <sup><font size=-3><a href=http://www.timesys.com>tm</a></font></sup> threw them out one day after I'd gone home, 172thinking they were recycling. (I still have two of each kind, but 173Pepsi One seems discontinued and Coke Zero switched its can color 174from black to grey, presumably in celebration. It was fun while it lasted...)</p> 175 176<b><h2>Footnotes</h2></b> 177 178<p><a name="1" /><a href="#1_back">[1]</a> Ok, most toolchains (gcc, llvm, pcc, libfirm...) 179are multiple packages, but the maintainer of toybox used to maintain a 180<a href=http://landley.net/tinycc>fork of tinycc</a> (an integrated 181compiler/assembler/linker which once upon a 182time did <a href=http://bellard.org/tcc/tccboot.html>build a bootable linux 183kernel</a> before its original developer abandoned the project), 184and has <a href=http://landley.net/hg/qcc/file/tip/todo/todo.txt>vague plans</a> of <a href=http://landley.net/qcc>trying 185again someday</a>. The compiler toolchain is _conceptually_ one package, 186implementable as a single multicall binary acting like make, cc, as, ld, cpp, 187strip, readelf, nm, objdump, and so on as necessary. It's just the existing 188packages that do this <strike>kinda suck</strike> don't. (In theory "make" 189belongs in qcc, in practice llvm hasn't got its own make so toybox probably 190needs to add it after 1.0 to eliminate another gpl build prerequite from 191AOSP.)</p> 192 193<p><a name="2" /><a href="#2_back">[2]</a> 194The dividing line is 195"Is there an acceptably licensed version Android can ship, or do we have 196to write one?" Since android is not "GNU/Linux" in any way, we need to 197clean out all traces of gnu software from its build to get a clean 198self-hosting system.</p> 199 200<!--#include file="footer.html" --> 201
