10f66f451Sopenharmony_ci<html><head><title>What is toybox?</title> 20f66f451Sopenharmony_ci<!--#include file="header.html" --> 30f66f451Sopenharmony_ci 40f66f451Sopenharmony_ci<h2><a name="what" />What is toybox?</h2> 50f66f451Sopenharmony_ci 60f66f451Sopenharmony_ci<p>Toybox combines many common Linux command line utilities together into 70f66f451Sopenharmony_cia single <a href=license.html>BSD-licensed</a> executable. It's simple, small, fast, and reasonably 80f66f451Sopenharmony_cistandards-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> 90f66f451Sopenharmony_ci 100f66f451Sopenharmony_ci<p>Toybox's main goal is to make Android 110f66f451Sopenharmony_ci<a href=http://landley.net/aboriginal/about.html#selfhost>self-hosting</a> 120f66f451Sopenharmony_ciby improving Android's command line utilities so it can 130f66f451Sopenharmony_cibuild an installable Android Open Source Project image 140f66f451Sopenharmony_cientirely from source under a stock Android system. After a talk at the 2013 150f66f451Sopenharmony_ciEmbedded Linux Conference explaining this plan 160f66f451Sopenharmony_ci(<a href=http://landley.net/talks/celf-2013.txt>outline</a>, 170f66f451Sopenharmony_ci<a href=https://www.youtube.com/watch?v=SGmtP5Lg_t0>video</a>), Google 180f66f451Sopenharmony_ci<a href=https://lwn.net/Articles/629362/>merged toybox into AOSP</a> and 190f66f451Sopenharmony_cibegan shipping toybox in Android Marshmallow in 2015.</p> 200f66f451Sopenharmony_ci 210f66f451Sopenharmony_ci<p>Toybox aims to provide one quarter of a theoretical "minimal native 220f66f451Sopenharmony_cidevelopment environment", which is the simplest Linux system capable of 230f66f451Sopenharmony_cirebuilding itself from source code and then building 240f66f451Sopenharmony_ci<a href=http://linuxfromscratch.org/lfs>Linux From Scratch</a> 250f66f451Sopenharmony_ciand the <a href=https://source.android.com>Android Open Source Project</a> 260f66f451Sopenharmony_ciunder the result. In theory, this should only require four packages: 270f66f451Sopenharmony_ci1) a set of posix-ish command line utilities, 280f66f451Sopenharmony_ci2) a compiler<a name="1_back"></a><sup><font size=-3><a href=#1>[1]</a></font></sup>, 290f66f451Sopenharmony_ci3) a C library, and 4) a kernel. This provides a reproducible and auditable 300f66f451Sopenharmony_cibase system, which with the addition of a few convienciences (vi, top, 310f66f451Sopenharmony_cishell command line history...) can provide a usable interactive experience 320f66f451Sopenharmony_cirather than just a headless build server.</p> 330f66f451Sopenharmony_ci 340f66f451Sopenharmony_ci<b><h2><a name="why" />Why is toybox?</h2></b> 350f66f451Sopenharmony_ci 360f66f451Sopenharmony_ci<p>The <a href=http://landley.net/talks/celf-2013.txt>2013 toybox talk</a> 370f66f451Sopenharmony_ciat ELC was devoted to this question, and has the following sections:</p> 380f66f451Sopenharmony_ci 390f66f451Sopenharmony_ci<ul> 400f66f451Sopenharmony_ci<li>0m29s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=0m29s>The smartphone is replacing the PC</a></li> 410f66f451Sopenharmony_ci <ul> 420f66f451Sopenharmony_ci <li>4m22s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=4m22s>Software needed to become self-hosting</a></li> 430f66f451Sopenharmony_ci <li>6m20s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=6m20s>Do we care if android or iphone wins?</a></li> 440f66f451Sopenharmony_ci </ul> 450f66f451Sopenharmony_ci<li>9m45s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=9m45s>Android not vanilla: oppose or accept?</a></li> 460f66f451Sopenharmony_ci <ul> 470f66f451Sopenharmony_ci <li>11m30s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=11m30s>Open source can't do User Interfaces</a></li> 480f66f451Sopenharmony_ci </ul> 490f66f451Sopenharmony_ci<li>15m09s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=15m09s>Android is not copyleft: oppose or accept?</a></li> 500f66f451Sopenharmony_ci<li>18m23s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=18m23s>Security issues</a></li> 510f66f451Sopenharmony_ci<li>21m15s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=21m15s>Solutions to the software problems</a></li> 520f66f451Sopenharmony_ci <ul> 530f66f451Sopenharmony_ci <li>22m55s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=22m55s>What toybox needs to be/do</a></li> 540f66f451Sopenharmony_ci <li>28m17s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=28m17s>What is toybox?</a></li> 550f66f451Sopenharmony_ci <ul> 560f66f451Sopenharmony_ci <li>28m58s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=28m58s>Why toybox started...</a></li> 570f66f451Sopenharmony_ci <li>37m50s <a href=http://www.youtube.com/watch?v=SGmtP5Lg_t0#t=37m50s>What does toybox actually implement?</a></li> 580f66f451Sopenharmony_ci </ul> 590f66f451Sopenharmony_ci </ul> 600f66f451Sopenharmony_ci</ul> 610f66f451Sopenharmony_ci 620f66f451Sopenharmony_ci<p>A more recent talk from 2019 compares 630f66f451Sopenharmony_ci<a href=https://www.youtube.com/watch?v=MkJkyMuBm3g#t=1m18s>BusyBox vs toybox</a> 640f66f451Sopenharmony_ciand explains the design decisions behind both. 650f66f451Sopenharmony_ci(A 2015 toybox talk was part of the channel 660f66f451Sopenharmony_ci<a href=https://marc.info/?l=linux-embedded&m=158159902514847&w=2>accidentally deleted</a> off youtube by the Linux Foundation, 670f66f451Sopenharmony_cibut the <a href=https://landley.net/talks/celf-2015.txt>outline</a> is 680f66f451Sopenharmony_cistill available.)</p> 690f66f451Sopenharmony_ci 700f66f451Sopenharmony_ci<b><h2><a name="context" />What context was toybox created in?</h2></b> 710f66f451Sopenharmony_ci 720f66f451Sopenharmony_ci<p>The toybox maintainer's previous minimal self-hosting system project, 730f66f451Sopenharmony_ci<a href=http://landley.net/aboriginal/about.html>Aboriginal Linux</a>, 740f66f451Sopenharmony_cigot a native development environment down to only seven packages in 750f66f451Sopenharmony_ciits 1.0 release (busybox, uClibc, gcc, binutils, make, bash, and linux) 760f66f451Sopenharmony_ciand then built Linux From Scratch under the result. That project 770f66f451Sopenharmony_ci<a href=http://landley.net/aboriginal/history.html>was the reason</a> 780f66f451Sopenharmony_citoybox's maintainer became busybox maintainer, having done so 790f66f451Sopenharmony_cimuch work to extend busybox to replace all the gnu tools in a Linux From 800f66f451Sopenharmony_ciScratch build that the previous maintainer handed over the project (to 810f66f451Sopenharmony_cispend more time on buildroot).</p> 820f66f451Sopenharmony_ci 830f66f451Sopenharmony_ci<p>Despite the maintainer's history with busybox, toybox is a fresh 840f66f451Sopenharmony_cifrom-scratch implementation under an 850f66f451Sopenharmony_ci<a href=https://source.android.com/source/licenses.html>android-compatible</a> 860f66f451Sopenharmony_ci<a href=license.html>license</a>. Busybox predates Android, but has never 870f66f451Sopenharmony_cishipped with Android due to the license. As long as we're starting over anyway, 880f66f451Sopenharmony_ciwe can do a better job.</p> 890f66f451Sopenharmony_ci 900f66f451Sopenharmony_ci<p>Toybox's current minimal native development environment builder is a new 910f66f451Sopenharmony_ci<a href=https://github.com/landley/toybox/blob/master/scripts/mkroot.sh>tiny 920f66f451Sopenharmony_ciimplementation</a> integrated into the toybox source. 930f66f451Sopenharmony_ciThe "make root" target will create a simple toybox chroot 940f66f451Sopenharmony_ci(by default in the root/host directory), and adding a LINUX= argument to 950f66f451Sopenharmony_cithe make command line pointing to Linux kernel source code creates a tiny 960f66f451Sopenharmony_cibootable system with a wrapper script to run it under the emulator 970f66f451Sopenharmony_ci<a href=https://qemu.org>qemu</a>.</p> 980f66f451Sopenharmony_ci 990f66f451Sopenharmony_ci<p>The list of commands remaining before we can build Linux From Scratch under 1000f66f451Sopenharmony_cithe result (with an appropriate 1010f66f451Sopenharmony_ci<a href=https://github.com/landley/toybox/blob/master/scripts/mcm-buildall.sh>compiler</a>) 1020f66f451Sopenharmony_ciis tracked <a href=roadmap.html#dev_env>in 1030f66f451Sopenharmony_cithe roadmap</a>, and doing so is one of the main goals for toybox's 1.0 1040f66f451Sopenharmony_cirelease.</p> 1050f66f451Sopenharmony_ci 1060f66f451Sopenharmony_ci<p>Building LFS requres fewer commands than building AOSP, which has a lot more 1070f66f451Sopenharmony_ci<a href=http://source.android.com/source/initializing.html>build 1080f66f451Sopenharmony_ciprerequisites</a>. In theory some of those can be built from source 1090f66f451Sopenharmony_cias external packages (we're clearly not including our own java implementation), 1100f66f451Sopenharmony_cibut some early prerequisites may need to be added to bootstrap AOSP far enough 1110f66f451Sopenharmony_cito build them (such as a read-only version of "git": 1120f66f451Sopenharmony_cihow does repo download the AOSP source otherwise?) 1130f66f451Sopenharmony_ci<a name="2_back"></a><sup><font size=-3><a href=#2>[2]</a></font></sup></p> 1140f66f451Sopenharmony_ci 1150f66f451Sopenharmony_ci<b><h2><a name="status" />What commands are planned/implemented in toybox?</h2></b> 1160f66f451Sopenharmony_ci 1170f66f451Sopenharmony_ci<p>The current list of commands implemented by toybox is on the 1180f66f451Sopenharmony_ci<a href=status.html>status page</a>, which is updated each release. 1190f66f451Sopenharmony_ciThere is also a <a href=roadmap.html>roadmap</a> listing all planned commands 1200f66f451Sopenharmony_cifor the 1.0 release and the reasons for including them.</p> 1210f66f451Sopenharmony_ci 1220f66f451Sopenharmony_ci<p>In general, configuring toybox with "make defconfig" enables all the commands 1230f66f451Sopenharmony_cicompete enough to be useful. Configuring "allyesconfig" enables partially 1240f66f451Sopenharmony_ciimplemented commands as well, along with debugging features.</p> 1250f66f451Sopenharmony_ci 1260f66f451Sopenharmony_ci<b><h3>Relevant Standards</h3></b> 1270f66f451Sopenharmony_ci 1280f66f451Sopenharmony_ci<p>Most commands are implemented according to POSIX-2008 (I.E. 1290f66f451Sopenharmony_ci<a href=http://opengroup.org/onlinepubs/9699919799/idx/utilities.html>The 1300f66f451Sopenharmony_ciSingle Unix Specification version 4</a>) where applicable. This does not mean 1310f66f451Sopenharmony_cithat toybox is implementing every SUSv4 utility: some such as SCCS and ed are 1320f66f451Sopenharmony_ciobsolete, while others such as c99 are outside the scope of the project. 1330f66f451Sopenharmony_ciToybox also isn't implementing full internationalization support: it should be 1340f66f451Sopenharmony_ci8-bit clean and handle UTF-8, but otherwise we leave this to X11 and higher 1350f66f451Sopenharmony_cilayers. And some things (like $CDPATH support in "cd") await a good 1360f66f451Sopenharmony_ciexplanation of why to bother with them. (POSIX provides an important 1370f66f451Sopenharmony_ciframe of reference, but is not an infallable set of commandments to be blindly 1380f66f451Sopenharmony_ciobeyed. We do try to document our deviations from it in the comment section 1390f66f451Sopenharmony_ciat the start of each command under toys/posix.)</p> 1400f66f451Sopenharmony_ci 1410f66f451Sopenharmony_ci<p>The other major sources of commands are the Linux man pages, the 1420f66f451Sopenharmony_ciLinux Standard Base, and testing the behavior of existing command 1430f66f451Sopenharmony_ciimplementations (although not generally looking at their 1440f66f451Sopenharmony_cisource code), including the commands in Android's toolbox. SUSv4 does not 1450f66f451Sopenharmony_ciinclude many basic commands such as "mount", "init", and "mke2fs", which are 1460f66f451Sopenharmony_cikind of nice to have.</p> 1470f66f451Sopenharmony_ci 1480f66f451Sopenharmony_ci<p>For more on this see the <a href=roadmap.html>roadmap</a> and 1490f66f451Sopenharmony_ci<a href=design.html>design goals</a>.</p> 1500f66f451Sopenharmony_ci 1510f66f451Sopenharmony_ci<b><h2><a name="downloads" />Download</h2></b> 1520f66f451Sopenharmony_ci 1530f66f451Sopenharmony_ci<p>This project is maintained as a <a href=https://github.com/landley/toybox>git 1540f66f451Sopenharmony_ciarchive</a>, and also offers <a href=http://landley.net/toybox/downloads>source 1550f66f451Sopenharmony_citarballs</a> and <a href=http://landley.net/toybox/bin>static binaries</a> 1560f66f451Sopenharmony_ciof the release versions.</p> 1570f66f451Sopenharmony_ci 1580f66f451Sopenharmony_ci<p>The maintainer's <a href=http://landley.net/notes.html>development log</a> and the project's 1590f66f451Sopenharmony_ci<a href=http://lists.landley.net/listinfo.cgi/toybox-landley.net>mailing 1600f66f451Sopenharmony_cilist</a> are also good ways to track what's going on with the project.</p> 1610f66f451Sopenharmony_ci 1620f66f451Sopenharmony_ci<b><h2><a name="toycans" />What's the toybox logo image?</h2></b> 1630f66f451Sopenharmony_ci 1640f66f451Sopenharmony_ci<p>It's <a href=toycans-big.jpg>carefully stacked soda cans</a>. Specifically, 1650f66f451Sopenharmony_ciit's a bunch of the original "Coke Zero" and "Pepsi One" cans, circa 2006, 1660f66f451Sopenharmony_cistacked to spell out the binary values of the ascii string "Toybox", with 1670f66f451Sopenharmony_cinull terminator at the bottom. (The big picture's on it's side because 1680f66f451Sopenharmony_cithe camera was held sideways to get a better shot.)</p> 1690f66f451Sopenharmony_ci 1700f66f451Sopenharmony_ci<p>No, it's not photoshopped, I actually had these cans until a coworker 1710f66f451Sopenharmony_ciwho 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, 1720f66f451Sopenharmony_cithinking they were recycling. (I still have two of each kind, but 1730f66f451Sopenharmony_ciPepsi One seems discontinued and Coke Zero switched its can color 1740f66f451Sopenharmony_cifrom black to grey, presumably in celebration. It was fun while it lasted...)</p> 1750f66f451Sopenharmony_ci 1760f66f451Sopenharmony_ci<b><h2>Footnotes</h2></b> 1770f66f451Sopenharmony_ci 1780f66f451Sopenharmony_ci<p><a name="1" /><a href="#1_back">[1]</a> Ok, most toolchains (gcc, llvm, pcc, libfirm...) 1790f66f451Sopenharmony_ciare multiple packages, but the maintainer of toybox used to maintain a 1800f66f451Sopenharmony_ci<a href=http://landley.net/tinycc>fork of tinycc</a> (an integrated 1810f66f451Sopenharmony_cicompiler/assembler/linker which once upon a 1820f66f451Sopenharmony_citime did <a href=http://bellard.org/tcc/tccboot.html>build a bootable linux 1830f66f451Sopenharmony_cikernel</a> before its original developer abandoned the project), 1840f66f451Sopenharmony_ciand has <a href=http://landley.net/hg/qcc/file/tip/todo/todo.txt>vague plans</a> of <a href=http://landley.net/qcc>trying 1850f66f451Sopenharmony_ciagain someday</a>. The compiler toolchain is _conceptually_ one package, 1860f66f451Sopenharmony_ciimplementable as a single multicall binary acting like make, cc, as, ld, cpp, 1870f66f451Sopenharmony_cistrip, readelf, nm, objdump, and so on as necessary. It's just the existing 1880f66f451Sopenharmony_cipackages that do this <strike>kinda suck</strike> don't. (In theory "make" 1890f66f451Sopenharmony_cibelongs in qcc, in practice llvm hasn't got its own make so toybox probably 1900f66f451Sopenharmony_cineeds to add it after 1.0 to eliminate another gpl build prerequite from 1910f66f451Sopenharmony_ciAOSP.)</p> 1920f66f451Sopenharmony_ci 1930f66f451Sopenharmony_ci<p><a name="2" /><a href="#2_back">[2]</a> 1940f66f451Sopenharmony_ciThe dividing line is 1950f66f451Sopenharmony_ci"Is there an acceptably licensed version Android can ship, or do we have 1960f66f451Sopenharmony_cito write one?" Since android is not "GNU/Linux" in any way, we need to 1970f66f451Sopenharmony_ciclean out all traces of gnu software from its build to get a clean 1980f66f451Sopenharmony_ciself-hosting system.</p> 1990f66f451Sopenharmony_ci 2000f66f451Sopenharmony_ci<!--#include file="footer.html" --> 201
