1<html><head><title>What is toybox?</title>
   2<!--#include file="header.html" -->
   4<h2><a name="what" />What is toybox?</h2>
   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=>POSIX-2008</a> and <a href=>LSB 4.1</a>).</p>
  10<p>Toybox's main goal is to make Android
  11<a href=>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=>outline</a>,
  17<a href=>video</a>), Google
  18<a href=>merged toybox into AOSP</a> and
  19began shipping toybox in Android Mashmallow.</p>
  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=>Linux From Scratch</a>
  25and the <a href=>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>
  34<b><h2><a name="why" />Why is toybox?</h2></b>
  36<p>The <a href=>2013 toybox talk</a>
  37at ELC was devoted to this question, and has the following sections:</p>
  40<li>0m29s <a href=>The smartphone is replacing the PC</a></li>
  41  <ul>
  42  <li>4m22s <a href=>Software needed to become self-hosting</a></li>
  43  <li>6m20s <a href=>Do we care if android or iphone wins?</a></li>
  44  </ul>
  45<li>9m45s <a href=>Android not vanilla: oppose or accept?</a></li>
  46  <ul>
  47  <li>11m30s <a href=>Open source can't do User Interfaces</a></li>
  48  </ul>
  49<li>15m09s <a href=>Android is not copyleft: oppose or accept?</a></li>
  50<li>18m23s <a href=>Security issues</a></li>
  51<li>21m15s <a href=>Solutions to the software problems</a></li>
  52  <ul>
  53  <li>22m55s <a href=>What toybox needs to be/do</a></li>
  54  <li>28m17s <a href=>What is toybox?</a></li>
  55    <ul>
  56    <li>28m58s <a href=>Why toybox started...</a></li>
  57    <li>37m50s <a href=>What does toybox actually implement?</a></li>
  58    </ul>
  59  </ul>
  62<p>The <a href=>2015 toybox talk</a>
  63starts with links to three previous talks on the history and motivation of
  64the project: "Why Toybox", "Why Public Domain", and "Why did I do
  65Aboriginal Linux (which led me here)?". If you're really bored,
  66there's even a half-finished
  67<a href=>a history page</a>.</p>
  69<p>The toybox maintainer's earlier minimal self-hosting system project,
  70<a href=>Aboriginal Linux</a>,
  71got its minimal native development environment down to seven packages in
  72its 1.0 release (busybox, uClibc, gcc, binutils, make, bash, and linux)
  73and built Linux From Scratch under the result. That project
  74<a href=>was the reason</a>
  75toybox's maintainer became busybox maintainer, having done so
  76much work to extend busybox to replace all the gnu tools in a Linux From
  77Scratch build that the previous maintainer handed over the project (to
  78spend more time on buildroot).</p>
  80<p>Despite the maintainer's history with busybox, toybox is a fresh
  81from-scratch implementation under an
  82<a href=>android-compatible</a>
  83<a href=license.html>license</a>. Busybox predates Android, but has never
  84shipped with Android due to the license. As long as we're starting over anyway,
  85we can do a better job.</p>
  87<p>These days, toybox is replacing busybox
  88in Aboriginal Linux one command at a time, and each toybox release is
  89regression tested by building Aboriginal Linux with it, then building
  90Linux From Scratch under the result with the new toybox commands.
  91The list of commands remaining is tracked <a href=roadmap.html#dev_env>in
  92the roadmap</a>, and the replacing busybox in Aboriginal Linux is
  93one of the main goals for toybox' 1.0 release.</p>
  95<p>Building LFS requres fewer commands than building AOSP, which has a lot more
  96<a href=>build
  97prerequisites</a>. In theory some of those can be built from source
  98as external packages (we're clearly not including our own java implementation),
  99but some early prerequisites may need to be added to bootstrap AOSP far enough
 100to build them (such as a read-only version of "git":
 101how does repo download the AOSP source otherwise?)
 102<a name="2_back"></a><sup><font size=-3><a href=#2>[2]</a></font></sup></p>
 104<b><h2><a name="status" />What commands are planned/implemented in toybox?</h2></b>
 106<p>The current list of commands implemented by toybox is on the
 107<a href=status.html>status page</a>, which is updated each release.
 108There is also a <a href=roadmap.html>roadmap</a> listing all planned commands
 109for the 1.0 release and the reasons for including them.</p>
 111<p>In general, configuring toybox with "make defconfig" enables all the commands
 112compete enough to be useful. Configuring "allyesconfig" enables partially
 113implemented commands as well, along with debugging features.</p>
 115<b><h3>Relevant Standards</h3></b>
 117<p>Most commands are implemented according to POSIX-2008 (I.E.
 118<a href=>The
 119Single Unix Specification version 4</a>) where applicable. This does not mean
 120that toybox is implementing every SUSv4 utility: some such as SCCS and ed are
 121obsolete, while others such as c99 are outside the scope of the project.
 122Toybox also isn't implementing full internationalization support: it should be
 1238-bit clean and handle UTF-8, but otherwise we leave this to X11 and higher
 124layers. And some things (like $CDPATH support in "cd") await a good
 125explanation of why to bother with them. (POSIX provides an important
 126frame of reference, but is not an infallable set of commandments to be blindly
 127obeyed. We do try to document our deviations from it in the comment section
 128at the start of each command under toys/posix.)</p>
 130<p>The other major sources of commands are the Linux man pages, the
 131Linux Standard Base, and testing the behavior of existing command
 132implementations (although not generally looking at their
 133source code), including the commands in Android's toolbox. SUSv4 does not
 134include many basic commands such as "mount", "init", and "mke2fs", which are
 135kind of nice to have.</p>
 137<p>For more on this see the <a href=roadmap.html>roadmap</a> and
 138<a href=design.html>design goals</a>.</p>
 140<b><h2><a name="downloads" />Download</h2></b>
 142<p>This project is maintained as a <a href=>git
 143archive</a>, and also offers <a href=>source
 144tarballs</a> and <a href=>static binaries</a>
 145of the release versions.</p>
 147<p>The maintainer's <a href=>development log</a> and the project's
 148<a href=>mailing
 149list</a> are also good ways to track what's going on with the project.</p>
 151<b><h2><a name="toycans" />What's the toybox logo image?</h2></b>
 153<p>It's <a href=toycans-big.jpg>carefully stacked soda cans</a>. Specifically,
 154it's a bunch of the original "Coke Zero" and "Pepsi One" cans, circa 2006,
 155stacked to spell out the binary values of the ascii string "Toybox", with
 156null terminator at the bottom. (The big picture's on it's side because
 157the camera was held sideways to get a better shot.)</p>
 159<p>No, it's not photoshopped, I actually had these cans until a coworker
 160who Totally Did Not Get It <sup><font size=-3><a href=>tm</a></font></sup> threw them out one day after I'd gone home,
 161thinking they were recycling. (I still have two of each kind, but
 162Pepsi One seems discontinued and Coke Zero switched its can color
 163from black to grey, presumably in celebration. It was fun while it lasted...)</p>
 167<p><a name="1" /><a href="#1_back">[1]</a> Ok, most toolchains (gcc, llvm, pcc, libfirm...)
 168are multiple packages, but the maintainer of toybox used to maintain a
 169<a href=>fork of tinycc</a> (an integrated
 170compiler/assembler/linker which once upon a
 171time did <a href=>build a bootable linux
 172kernel</a> before its original developer abandoned the project),
 173and has <a href=>vague plans</a> of <a href=>trying
 174again someday</a>. The compiler toolchain is _conceptually_ one package,
 175implementable as a single multicall binary acting like make, cc, as, ld, cpp,
 176strip, readelf, nm, objdump, and so on as necessary. It's just the existing
 177packages that do this <strike>kinda suck</strike> don't. (In theory "make"
 178belongs in qcc, in practice llvm hasn't got its own make so toybox probably
 179needs to add it after 1.0 to eliminate another gpl build prerequite from
 182<p><a name="2" /><a href="#2_back">[2]</a>
 183The dividing line is
 184"Is there an acceptably licensed version Android can ship, or do we have
 185to write one?" Since android is not "GNU/Linux" in any way, we need to
 186clean out all traces of gnu software from its build to get a clean
 187self-hosting system.</p>
 189<!--#include file="footer.html" -->