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-2015.txt>2015 toybox talk</a> 37starts with links to three previous talks on the history and motivation of 38the project: "Why Toybox", "Why Public Domain", and "Why did I do 39Aboriginal Linux (which led me here)?". If you're really bored, 40there's even a half-finished 41<a href=http://landley.net/aboriginal/history.html>a history page</a>.</p> 42 43<p>The toybox maintainer's earlier minimal self-hosting system project, 44<a href=http://landley.net/aboriginal/about.html>Aboriginal Linux</a>, 45got its minimal native development environment down to seven packages in 46its 1.0 release (busybox, uClibc, gcc, binutils, make, bash, and linux) 47and built Linux From Scratch under the result. That project 48<a href=http://landley.net/aboriginal/history.html>was the reason</a> 49toybox's maintainer became busybox maintainer, having done so 50much work to extend busybox to replace all the gnu tools in a Linux From 51Scratch build that the previous maintainer handed over the project (to 52spend more time on buildroot).</p> 53 54<p>Despite the maintainer's history with busybox, toybox is a fresh 55from-scratch implementation under an 56<a href=https://source.android.com/source/licenses.html>android-compatible</a> 57<a href=license.html>license</a>. Busybox predates Android, but has never 58shipped with Android due to the license. As long as we're starting over anyway, 59we can do a better job.</p> 60 61<p>These days, toybox is replacing busybox 62in Aboriginal Linux one command at a time, and each toybox release is 63regression tested by building Aboriginal Linux with it, then building 64Linux From Scratch under the result with the new toybox commands. 65The list of commands remaining is tracked <a href=roadmap.html#dev_env>in 66the roadmap</a>, and the replacing busybox in Aboriginal Linux is 67one of the main goals for toybox' 1.0 release.</p> 68 69<p>Building LFS requres fewer commands than building AOSP, which has a lot more 70<a href=http://source.android.com/source/initializing.html>build 71prerequisites</a>. In theory some of those can be built from source 72as external packages (we're clearly not including our own java implementation), 73but some early prerequisites may need to be added to bootstrap AOSP far enough 74to build them (such as a read-only version of "git": 75how does repo download the AOSP source otherwise?) 76<a name="2_back"></a><sup><font size=-3><a href=#2>[2]</a></font></sup></p> 77 78<b><h2><a name="status" />What commands are planned/implemented in toybox?</h2></b> 79 80<p>The current list of commands implemented by toybox is on the 81<a href=status.html>status page</a>, which is updated each release. 82There is also a <a href=roadmap.html>roadmap</a> listing all planned commands 83for the 1.0 release and the reasons for including them.</p> 84 85<p>In general, configuring toybox with "make defconfig" enables all the commands 86compete enough to be useful. Configuring "allyesconfig" enables partially 87implemented commands as well, along with debugging features.</p> 88 89<b><h3>Relevant Standards</h3></b> 90 91<p>Most commands are implemented according to POSIX-2008 (I.E. 92<a href=http://opengroup.org/onlinepubs/9699919799/idx/utilities.html>The 93Single Unix Specification version 4</a>) where applicable. This does not mean 94that toybox is implementing every SUSv4 utility: some such as SCCS and ed are 95obsolete, while others such as c99 are outside the scope of the project. 96Toybox also isn't implementing full internationalization support: it should be 978-bit clean and handle UTF-8, but otherwise we leave this to X11 and higher 98layers. And some things (like $CDPATH support in "cd") await a good 99explanation of why to bother with them. (POSIX provides an important 100frame of reference, but is not an infallable set of commandments to be blindly 101obeyed. We do try to document our deviations from it in the comment section 102at the start of each command under toys/posix.)</p> 103 104<p>The other major sources of commands are the Linux man pages, the 105Linux Standard Base, and testing the behavior of existing command 106implementations (although not generally looking at their 107source code), including the commands in Android's toolbox. SUSv4 does not 108include many basic commands such as "mount", "init", and "mke2fs", which are 109kind of nice to have.</p> 110 111<p>For more on this see the <a href=roadmap.html>roadmap</a> and 112<a href=design.html>design goals</a>.</p> 113 114<b><h2><a name="downloads" />Download</h2></b> 115 116<p>This project is maintained as a <a href=https://github.com/landley/toybox>git 117archive</a>, and also offers <a href=http://landley.net/toybox/downloads>source 118tarballs</a> and <a href=http://landley.net/toybox/bin>static binaries</a> 119of the release versions.</p> 120 121<p>The maintainer's <a href=http://landley.net/notes.html>development log</a> and the project's 122<a href=http://lists.landley.net/listinfo.cgi/toybox-landley.net>mailing 123list</a> are also good ways to track what's going on with the project.</p> 124 125<b><h2><a name="toycans" />What's the toybox logo image?</h2></b> 126 127<p>It's <a href=toycans-big.jpg>carefully stacked soda cans</a>. Specifically, 128it's a bunch of the original "Coke Zero" and "Pepsi One" cans, circa 2006, 129stacked to spell out the binary values of the ascii string "Toybox", with 130null terminator at the bottom. (The big picture's on it's side because 131the camera was held sideways to get a better shot.)</p> 132 133<p>No, it's not photoshopped, I actually had these cans until a coworker 134who 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, 135thinking they were recycling. (I still have two of each kind, but 136Pepsi One seems discontinued and Coke Zero switched its can color 137from black to grey, presumably in celebration. It was fun while it lasted...)</p> 138 139<b><h2>Footnotes</h2></b> 140 141<p><a name="1" /><a href="#1_back">[1]</a> Ok, most toolchains (gcc, llvm, pcc, libfirm...) 142are multiple packages, but the maintainer of toybox used to maintain a 143<a href=http://landley.net/tinycc>fork of tinycc</a> (an integrated 144compiler/assembler/linker which once upon a 145time did <a href=http://bellard.org/tcc/tccboot.html>build a bootable linux 146kernel</a> before its original developer abandoned the project), 147and has <a href=http://landley.net/hg/qcc/file/tip/todo/todo.txt>vague plans</a> of <a href=http://landley.net/qcc>trying 148again someday</a>. The compiler toolchain is _conceptually_ one package, 149implementable as a single multicall binary acting like make, cc, as, ld, cpp, 150strip, readelf, nm, objdump, and so on as necessary. It's just the existing 151packages that do this <strike>kinda suck</strike> don't. (In theory "make" 152belongs in qcc, in practice llvm hasn't got its own make so toybox probably 153needs to add it after 1.0 to eliminate another gpl build prerequite from 154AOSP.)</p> 155 156<p><a name="2" /><a href="#2_back">[2]</a> 157The dividing line is 158"Is there an acceptably licensed version Android can ship, or do we have 159to write one?" Since android is not "GNU/Linux" in any way, we need to 160clean out all traces of gnu software from its build to get a clean 161self-hosting system.</p> 162 163<!--#include file="footer.html" --> 164
