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