Blame - www/about.html - fp2-dev/platform/external/toybox

blob: 61c57a656a600ed31c8131043477704b77daaf13 [file] [log] [blame]

Rob Landley	349ff52	2014-01-04 13:09:42 -0600	[diff] [blame]	1	<html><head><title>What is toybox?</title>
Rob Landley	589f5cd	2010-01-05 10:41:52 -0600	[diff] [blame]	2	<!--#include file="header.html" -->
				3
Rob Landley	5889691	2014-09-20 14:12:55 -0500	[diff] [blame]	4	<h2><a name="what" />What is toybox?</h2>
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	5
Rob Landley	e566f3a	2013-06-16 20:02:38 -0500	[diff] [blame]	6	<p>Toybox combines the most 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>
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	9
Rob Landley	e566f3a	2013-06-16 20:02:38 -0500	[diff] [blame]	10	<p>Toybox's 1.0 release goal is to turn generic Android into a
				11	development environment capable of compiling <a href=http://www.linuxfromscratch.org>Linux From Scratch</a>.
				12	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
				13	gcc 4.2.1+binutils 2.17) should be
				14	able to rebuild itself from source code without needing any other packages.</p>
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	15
Rob Landley	5889691	2014-09-20 14:12:55 -0500	[diff] [blame]	16	<b><h2><a name="status" />What commands are implemented in toybox?</h2></b>
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	17
Rob Landley	689f095	2012-08-25 14:24:24 -0500	[diff] [blame]	18	<p>The current list of commands implemented by toybox is on the
				19	<a href=status.html>status page</a>, which is updated each release.
Rob Landley	e566f3a	2013-06-16 20:02:38 -0500	[diff] [blame]	20	There is also <a href=roadmap.html>roadmap</a> listing all planned commands for the
Rob Landley	689f095	2012-08-25 14:24:24 -0500	[diff] [blame]	21	1.0 release.</p>
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	22
				23	<p>In general, configuring toybox for "defconfig" enables all the commands
				24	compete enough to be useful. Configuring "allyesconfig" enables partially
Rob Landley	689f095	2012-08-25 14:24:24 -0500	[diff] [blame]	25	implemented commands as well, along with debugging features.</p>
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	26
Rob Landley	4c2484f	2012-01-22 19:41:42 -0600	[diff] [blame]	27	<p>Several toybox commands can do things other vesions can't. For example
				28	the toybox "df" isn't confused by initramfs the way other df implementations
Rob Landley	689f095	2012-08-25 14:24:24 -0500	[diff] [blame]	29	are. (If initramfs is visible, df shows it like any other mount point.)</p>
Rob Landley	bd91551	2008-01-07 20:28:26 -0600	[diff] [blame]	30
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	31	<b><h3>Command Shell</h3></b>
Rob Landley	5889691	2014-09-20 14:12:55 -0500	[diff] [blame]	32	<p>The toybox shell (toysh) aims to be a reasonable bash replacement. It
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	33	implements the "sh" and "toysh" commands, plus the built-in commands "cd" and
				34	"exit". This is the largest single sub-project in toybox.</p>
				35
				36	<p>The following additional commands may be built into the shell (but not as
				37	separate executables): cd, exit, if, while, for, function, fg, bg, jobs, source,
Rob Landley	4c2484f	2012-01-22 19:41:42 -0600	[diff] [blame]	38	<a href="http://opengroup.org/onlinepubs/9699919799/utilities/alias.html">alias</a>,
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	39	export, set, unset, read, trap, and exec. (Note: not done yet.)</p>
				40
				41	</ul>
				42
				43	<h2><a name="commands" />Which commands are planned?</h2>
				44
				45	<p>The toybox <a href=todo.txt>todo list</a> mentions many potential commands
				46	which may be added to this project. (Whether that file is readable by anybody
Rob Landley	4c2484f	2012-01-22 19:41:42 -0600	[diff] [blame]	47	but the project's maintainer is open to debate.) The roadmap wiki in the
				48	nav bar has a more human readable version.</p>
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	49
				50	<p>The criteria for a toybox 1.0 release is that a system built from just the
Rob Landley	4c2484f	2012-01-22 19:41:42 -0600	[diff] [blame]	51	Linux kernel, toybox, C library (such as uClibc), and a compiler (such as
				52	tinycc) can rebuild itself from source code.</p>
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	53
				54	<b><h3>Relevant Standards</h3></b>
				55
				56	<p>Most commands are implemented according to
Rob Landley	4c2484f	2012-01-22 19:41:42 -0600	[diff] [blame]	57	<a href=http://opengroup.org/onlinepubs/9699919799/idx/utilities.html>The
Rob Landley	9a69a92	2013-02-23 18:32:08 -0600	[diff] [blame]	58	Single Unix Specification version 4</a> where applicable. This does not mean
Rob Landley	5889691	2014-09-20 14:12:55 -0500	[diff] [blame]	59	that toybox is implementing every SUSv4 utility: some such as SCCS and ed are
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	60	obsolete, while others such as c99 are outside the scope of the project.
				61	Toybox also isn't implementing full internationalization support: it should be
				62	8-bit clean and handle UTF-8, but otherwise we leave this to X11 and higher
Rob Landley	9a69a92	2013-02-23 18:32:08 -0600	[diff] [blame]	63	layers. And some things (like $CDPATH support in "cd") await a good
				64	explanation of why to bother with them. (The standard provides an important
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	65	frame of reference, but is not infallable set of commandments to be blindly
				66	obeyed.)</p>
				67
				68	<p>The other major sources of commands are the Linux man pages, and testing
				69	the behavior of existing commands (although not generally looking at their
Rob Landley	9a69a92	2013-02-23 18:32:08 -0600	[diff] [blame]	70	source code), including the commands in Android's toolbox. SUSv4 does not
Rob Landley	4c2484f	2012-01-22 19:41:42 -0600	[diff] [blame]	71	include many basic commands such as "mount", "init", and "mke2fs", which are
				72	kind of nice to have.</p>
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	73
				74	<b><h2><a name="downloads" />Download</h2></b>
				75
Rob Landley	e0269f1	2015-04-05 20:00:33 -0500	[diff] [blame]	76	<p>This project is maintained as a <a href=https://github.com/landley/toybox>git
				77	archive</a>, and also offers <a href=http://landley.net/toybox/downloads>source
				78	tarballs</a> and <a href=http://landley.net/toybox/bin>static binaries</a>
				79	of the release versions.</p>
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	80
				81	<p>The maintainer's <a href=/notes.html>development log</a> and the project's
Rob Landley	4c2484f	2012-01-22 19:41:42 -0600	[diff] [blame]	82	<a href=http://lists.landley.net/listinfo.cgi/toybox-landley.net>mailing
Rob Landley	e258af3	2008-01-05 18:09:49 -0600	[diff] [blame]	83	list</a> are also good ways to track what's going on with the project.</p>
				84
Rob Landley	e0269f1	2015-04-05 20:00:33 -0500	[diff] [blame]	85	<b><h2><a name="why" />Why is toybox?</h2></b>
Rob Landley	689f095	2012-08-25 14:24:24 -0500	[diff] [blame]	86
Rob Landley	e0269f1	2015-04-05 20:00:33 -0500	[diff] [blame]	87	<p>The <a href=http://landley.net/talks/celf-2015.txt>2015 toybox talk</a>
				88	starts with links to three previous talks on the history and motivation of
				89	the project: "Why Toybox", "Why Public Domain", and "Why did I do
Elliott Hughes	5174697	2015-04-17 02:52:11 -0500	[diff] [blame]	90	Aboriginal Linux (which led me here)?".</p>
Rob Landley	689f095	2012-08-25 14:24:24 -0500	[diff] [blame]	91
Rob Landley	08671ef	2009-09-30 23:30:26 -0500	[diff] [blame]	92	<b><h2><a name="toycans" />What's the toybox logo image?</h2></b>
Rob Landley	b9d0cf1	2008-01-05 18:13:19 -0600	[diff] [blame]	93
				94	<p>It's <a href=toycans-big.jpg>carefully stacked soda cans</a>. Specifically,
				95	it's a bunch of the original "Coke Zero" and "Pepsi One" cans, circa 2006,
Rob Landley	797a4c3	2008-01-05 18:23:30 -0600	[diff] [blame]	96	stacked to spell out the binary values of the ascii string "Toybox", with
				97	null terminator at the bottom. (The big picture's on it's side because
				98	the camera was held sideways to get a better shot.)</p>
				99
				100	<p>No, it's not photoshopped, I actually had these cans until a coworker
				101	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,
				102	thinking they were recycling. (I still have two of each kind, but
				103	Pepsi One seems discontinued and Coke Zero switched its can color
				104	from black to grey, presumably in celebration. It was fun while it lasted...)</p>
Rob Landley	589f5cd	2010-01-05 10:41:52 -0600	[diff] [blame]	105
				106	<!--#include file="footer.html" -->