www/about.html

   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
   7 a single <a href=license.html>BSD-licensed</a> executable. It's simple, small, fast, and reasonably
   8 standards-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>
  12 by improving Android's command line utilities so it can
  13 build an installable Android Open Source Project image
  14 entirely from source under a stock Android system. After a talk at the 2013
  15 Embedded 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
  19 began shipping toybox in Android Mashmallow.</p>
  20
  21 <p>Toybox aims to provide one quarter of a theoretical "minimal native
  22 development environment", which is the simplest Linux system capable of
  23 rebuilding itself from source code and then building
  24 <a href=http://linuxfromscratch.org/lfs>Linux From Scratch</a>
  25 and the <a href=https://source.android.com>Android Open Source Project</a>
  26 under the result. In theory, this should only require four packages:
  27 1) a set of posix-ish command line utilities,
  28 2) a compiler<a name="1_back"></a><sup><font size=-3><a href=#1>[1]</a></font></sup>,
  29 3) a C library, and 4) a kernel. This provides a reproducible and auditable
  30 base system, which with the addition of a few convienciences (vi, top,
  31 shell command line history...) can provide a usable interactive experience
  32 rather 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>
  37 starts with links to three previous talks on the history and motivation of
  38 the project: "Why Toybox", "Why Public Domain", and "Why did I do
  39 Aboriginal Linux (which led me here)?". If you're really bored,
  40 there'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>,
  45 got its minimal native development environment down to seven packages in
  46 its 1.0 release (busybox, uClibc, gcc, binutils, make, bash, and linux)
  47 and built Linux From Scratch under the result. That project
  48 <a href=http://landley.net/aboriginal/history.html>was the reason</a>
  49 toybox's maintainer became busybox maintainer, having done so
  50 much work to extend busybox to replace all the gnu tools in a Linux From
  51 Scratch build that the previous maintainer handed over the project (to
  52 spend more time on buildroot).</p>
  53
  54 <p>Despite the maintainer's history with busybox, toybox is a fresh
  55 from-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
  58 shipped with Android due to the license. As long as we're starting over anyway,
  59 we can do a better job.</p>
  60
  61 <p>These days, toybox is replacing busybox
  62 in Aboriginal Linux one command at a time, and each toybox release is
  63 regression tested by building Aboriginal Linux with it, then building
  64 Linux From Scratch under the result with the new toybox commands.
  65 The list of commands remaining is tracked <a href=roadmap.html#dev_env>in
  66 the roadmap</a>, and the replacing busybox in Aboriginal Linux is
  67 one 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
  71 prerequisites</a>. In theory some of those can be built from source
  72 as external packages (we're clearly not including our own java implementation),
  73 but some early prerequisites may need to be added to bootstrap AOSP far enough
  74 to build them (such as a read-only version of "git":
  75 how 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.
  82 There is also a <a href=roadmap.html>roadmap</a> listing all planned commands
  83 for 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
  86 compete enough to be useful. Configuring "allyesconfig" enables partially
  87 implemented 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
  93 Single Unix Specification version 4</a>) where applicable. This does not mean
  94 that toybox is implementing every SUSv4 utility: some such as SCCS and ed are
  95 obsolete, while others such as c99 are outside the scope of the project.
  96 Toybox also isn't implementing full internationalization support: it should be
  97 8-bit clean and handle UTF-8, but otherwise we leave this to X11 and higher
  98 layers. And some things (like $CDPATH support in "cd") await a good
  99 explanation of why to bother with them. (POSIX provides an important
 100 frame of reference, but is not an infallable set of commandments to be blindly
 101 obeyed. We do try to document our deviations from it in the comment section
 102 at the start of each command under toys/posix.)</p>
 103
 104 <p>The other major sources of commands are the Linux man pages, the
 105 Linux Standard Base, and testing the behavior of existing command
 106 implementations (although not generally looking at their
 107 source code), including the commands in Android's toolbox. SUSv4 does not
 108 include many basic commands such as "mount", "init", and "mke2fs", which are
 109 kind 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
 117 archive</a>, and also offers <a href=http://landley.net/toybox/downloads>source
 118 tarballs</a> and <a href=http://landley.net/toybox/bin>static binaries</a>
 119 of 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
 123 list</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,
 128 it's a bunch of the original "Coke Zero" and "Pepsi One" cans, circa 2006,
 129 stacked to spell out the binary values of the ascii string "Toybox", with
 130 null terminator at the bottom. (The big picture's on it's side because
 131 the 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
 134 who 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,
 135 thinking they were recycling. (I still have two of each kind, but
 136 Pepsi One seems discontinued and Coke Zero switched its can color
 137 from 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...)
 142 are multiple packages, but the maintainer of toybox used to maintain a
 143 <a href=http://landley.net/tinycc>fork of tinycc</a> (an integrated
 144 compiler/assembler/linker which once upon a
 145 time did <a href=http://bellard.org/tcc/tccboot.html>build a bootable linux
 146 kernel</a> before its original developer abandoned the project),
 147 and has <a href=http://landley.net/hg/qcc/file/tip/todo/todo.txt>vague plans</a> of <a href=http://landley.net/qcc>trying
 148 again someday</a>. The compiler toolchain is _conceptually_ one package,
 149 implementable as a single multicall binary acting like make, cc, as, ld, cpp,
 150 strip, readelf, nm, objdump, and so on as necessary. It's just the existing
 151 packages that do this <strike>kinda suck</strike> don't. (In theory "make"
 152 belongs in qcc, in practice llvm hasn't got its own make so toybox probably
 153 needs to add it after 1.0 to eliminate another gpl build prerequite from
 154 AOSP.)</p>
 155
 156 <p><a name="2" /><a href="#2_back">[2]</a>
 157 The dividing line is
 158 "Is there an acceptably licensed version Android can ship, or do we have
 159 to write one?" Since android is not "GNU/Linux" in any way, we need to
 160 clean out all traces of gnu software from its build to get a clean
 161 self-hosting system.</p>
 162
 163 <!--#include file="footer.html" -->