www/about.html - platform/external/toybox - Git at Google

 <html><head><title>What is toybox?</title>
 <!--#include file="header.html" -->

 <h2><a name="what" />What is toybox?</h2>

 <p>Toybox combines the most common Linux command line utilities together into
 a single <a href=license.html>BSD-licensed</a> executable. It's simple, small, fast, and reasonably
 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>

 <p>Toybox's 1.0 release goal is to turn generic Android into a
 development environment capable of compiling <a href=http://www.linuxfromscratch.org>Linux From Scratch</a>.
 A tiny system <a href=/aboriginal>built from</a> just toybox, linux, <a href=http://musl-libc.org>a C library</a>, and a C compiler (such as LLVM or
 gcc 4.2.1+binutils 2.17) should be
 able to rebuild itself from source code without needing any other packages.</p>

 <b><h2><a name="status" />What commands are implemented in toybox?</h2></b>

 <p>The current list of commands implemented by toybox is on the
 <a href=status.html>status page</a>, which is updated each release.
 There is also <a href=roadmap.html>roadmap</a> listing all planned commands for the
 1.0 release.</p>

 <p>In general, configuring toybox for "defconfig" enables all the commands
 compete enough to be useful.  Configuring "allyesconfig" enables partially
 implemented commands as well, along with debugging features.</p>

 <p>Several toybox commands can do things other vesions can't.  For example
 the toybox "df" isn't confused by initramfs the way other df implementations
 are. (If initramfs is visible, df shows it like any other mount point.)</p>

 <b><h3>Command Shell</h3></b>
 <p>The toybox shell (toysh) aims to be a reasonable bash replacement.  It
 implements the "sh" and "toysh" commands, plus the built-in commands "cd" and
 "exit".  This is the largest single sub-project in toybox.</p>

 <p>The following additional commands may be built into the shell (but not as
 separate executables): cd, exit, if, while, for, function, fg, bg, jobs, source,
 <a href="http://opengroup.org/onlinepubs/9699919799/utilities/alias.html">alias</a>,
 export, set, unset, read, trap, and exec.  (Note: not done yet.)</p>

 </ul>

 <h2><a name="commands" />Which commands are planned?</h2>

 <p>The toybox <a href=todo.txt>todo list</a> mentions many potential commands
 which may be added to this project.  (Whether that file is readable by anybody
 but the project's maintainer is open to debate.)  The roadmap wiki in the
 nav bar has a more human readable version.</p>

 <p>The criteria for a toybox 1.0 release is that a system built from just the
 Linux kernel, toybox, C library (such as uClibc), and a compiler (such as
 tinycc) can rebuild itself from source code.</p>

 <b><h3>Relevant Standards</h3></b>

 <p>Most commands are implemented according to
 <a href=http://opengroup.org/onlinepubs/9699919799/idx/utilities.html>The
 Single Unix Specification version 4</a> where applicable. This does not mean
 that toybox is implementing every SUSv4 utility: some such as SCCS and ed are
 obsolete, while others such as c99 are outside the scope of the project.
 Toybox also isn't implementing full internationalization support: it should be
 8-bit clean and handle UTF-8, but otherwise we leave this to X11 and higher
 layers. And some things (like $CDPATH support in "cd") await a good
 explanation of why to bother with them. (The standard provides an important
 frame of reference, but is not infallable set of commandments to be blindly
 obeyed.)</p>

 <p>The other major sources of commands are the Linux man pages, and testing
 the behavior of existing commands (although not generally looking at their
 source code), including the commands in Android's toolbox. SUSv4 does not
 include many basic commands such as "mount", "init", and "mke2fs", which are
 kind of nice to have.</p>

 <b><h2><a name="downloads" />Download</h2></b>

 <p>This project is maintained as a <a href=https://github.com/landley/toybox>git
 archive</a>, and also offers <a href=http://landley.net/toybox/downloads>source
 tarballs</a> and <a href=http://landley.net/toybox/bin>static binaries</a>
 of the release versions.</p>

 <p>The maintainer's <a href=/notes.html>development log</a> and the project's
 <a href=http://lists.landley.net/listinfo.cgi/toybox-landley.net>mailing
 list</a> are also good ways to track what's going on with the project.</p>

 <b><h2><a name="why" />Why is toybox?</h2></b>

 <p>The <a href=http://landley.net/talks/celf-2015.txt>2015 toybox talk</a>
 starts with links to three previous talks on the history and motivation of
 the project: "Why Toybox", "Why Public Domain", and "Why did I do
 Aboriginal Linux (which led me here)?".</p>

 <b><h2><a name="toycans" />What's the toybox logo image?</h2></b>

 <p>It's <a href=toycans-big.jpg>carefully stacked soda cans</a>.  Specifically,
 it's a bunch of the original "Coke Zero" and "Pepsi One" cans, circa 2006,
 stacked to spell out the binary values of the ascii string "Toybox", with
 null terminator at the bottom.  (The big picture's on it's side because
 the camera was held sideways to get a better shot.)</p>

 <p>No, it's not photoshopped, I actually had these cans until a coworker
 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,
 thinking they were recycling.  (I still have two of each kind, but
 Pepsi One seems discontinued and Coke Zero switched its can color
 from black to grey, presumably in celebration.  It was fun while it lasted...)</p>

 <!--#include file="footer.html" -->
	<html><head><title>What is toybox?</title>
	<!--#include file="header.html" -->

	<h2><a name="what" />What is toybox?</h2>

	<p>Toybox combines the most common Linux command line utilities together into
	a single <a href=license.html>BSD-licensed</a> executable. It's simple, small, fast, and reasonably
	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>

	<p>Toybox's 1.0 release goal is to turn generic Android into a
	development environment capable of compiling <a href=http://www.linuxfromscratch.org>Linux From Scratch</a>.
	A tiny system <a href=/aboriginal>built from</a> just toybox, linux, <a href=http://musl-libc.org>a C library</a>, and a C compiler (such as LLVM or
	gcc 4.2.1+binutils 2.17) should be
	able to rebuild itself from source code without needing any other packages.</p>

	<b><h2><a name="status" />What commands are implemented in toybox?</h2></b>

	<p>The current list of commands implemented by toybox is on the
	<a href=status.html>status page</a>, which is updated each release.
	There is also <a href=roadmap.html>roadmap</a> listing all planned commands for the
	1.0 release.</p>

	<p>In general, configuring toybox for "defconfig" enables all the commands
	compete enough to be useful. Configuring "allyesconfig" enables partially
	implemented commands as well, along with debugging features.</p>

	<p>Several toybox commands can do things other vesions can't. For example
	the toybox "df" isn't confused by initramfs the way other df implementations
	are. (If initramfs is visible, df shows it like any other mount point.)</p>

	<b><h3>Command Shell</h3></b>
	<p>The toybox shell (toysh) aims to be a reasonable bash replacement. It
	implements the "sh" and "toysh" commands, plus the built-in commands "cd" and
	"exit". This is the largest single sub-project in toybox.</p>

	<p>The following additional commands may be built into the shell (but not as
	separate executables): cd, exit, if, while, for, function, fg, bg, jobs, source,
	<a href="http://opengroup.org/onlinepubs/9699919799/utilities/alias.html">alias</a>,
	export, set, unset, read, trap, and exec. (Note: not done yet.)</p>

	</ul>

	<h2><a name="commands" />Which commands are planned?</h2>

	<p>The toybox <a href=todo.txt>todo list</a> mentions many potential commands
	which may be added to this project. (Whether that file is readable by anybody
	but the project's maintainer is open to debate.) The roadmap wiki in the
	nav bar has a more human readable version.</p>

	<p>The criteria for a toybox 1.0 release is that a system built from just the
	Linux kernel, toybox, C library (such as uClibc), and a compiler (such as
	tinycc) can rebuild itself from source code.</p>

	<b><h3>Relevant Standards</h3></b>

	<p>Most commands are implemented according to
	<a href=http://opengroup.org/onlinepubs/9699919799/idx/utilities.html>The
	Single Unix Specification version 4</a> where applicable. This does not mean
	that toybox is implementing every SUSv4 utility: some such as SCCS and ed are
	obsolete, while others such as c99 are outside the scope of the project.
	Toybox also isn't implementing full internationalization support: it should be
	8-bit clean and handle UTF-8, but otherwise we leave this to X11 and higher
	layers. And some things (like $CDPATH support in "cd") await a good
	explanation of why to bother with them. (The standard provides an important
	frame of reference, but is not infallable set of commandments to be blindly
	obeyed.)</p>

	<p>The other major sources of commands are the Linux man pages, and testing
	the behavior of existing commands (although not generally looking at their
	source code), including the commands in Android's toolbox. SUSv4 does not
	include many basic commands such as "mount", "init", and "mke2fs", which are
	kind of nice to have.</p>

	<b><h2><a name="downloads" />Download</h2></b>

	<p>This project is maintained as a <a href=https://github.com/landley/toybox>git
	archive</a>, and also offers <a href=http://landley.net/toybox/downloads>source
	tarballs</a> and <a href=http://landley.net/toybox/bin>static binaries</a>
	of the release versions.</p>

	<p>The maintainer's <a href=/notes.html>development log</a> and the project's
	<a href=http://lists.landley.net/listinfo.cgi/toybox-landley.net>mailing
	list</a> are also good ways to track what's going on with the project.</p>

	<b><h2><a name="why" />Why is toybox?</h2></b>

	<p>The <a href=http://landley.net/talks/celf-2015.txt>2015 toybox talk</a>
	starts with links to three previous talks on the history and motivation of
	the project: "Why Toybox", "Why Public Domain", and "Why did I do
	Aboriginal Linux (which led me here)?".</p>

	<b><h2><a name="toycans" />What's the toybox logo image?</h2></b>

	<p>It's <a href=toycans-big.jpg>carefully stacked soda cans</a>. Specifically,
	it's a bunch of the original "Coke Zero" and "Pepsi One" cans, circa 2006,
	stacked to spell out the binary values of the ascii string "Toybox", with
	null terminator at the bottom. (The big picture's on it's side because
	the camera was held sideways to get a better shot.)</p>

	<p>No, it's not photoshopped, I actually had these cans until a coworker
	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,
	thinking they were recycling. (I still have two of each kind, but
	Pepsi One seems discontinued and Coke Zero switched its can color
	from black to grey, presumably in celebration. It was fun while it lasted...)</p>

	<!--#include file="footer.html" -->