<!--#include file="header.html" -->
-<h1>Simplicity first: spending your complexity budget wisely.</h1>
+<p><h1>Code style</h1></p>
<p>The primary goal of toybox is _simple_ code. Keeping the code small is
-second, with speed and lots of features coming in somewhere after that.</p>
-
-<p>These goals are usually complementary: simplifying code generally reduces
-its size (both in terms of binary size and runtime memory usage), and avoiding
-unnecessary work makes code run faster. Smaller code also tends to run faster
-on modern hardware due to CPU cacheing: fitting your code into L1 cache is
-great, and staying in L2 cache is still pretty good.</p>
+second, with speed and lots of features coming in somewhere after that.
+(For more on that, see the <a href=design.html>design</a> page.)</p>
<p>A simple implementation usually takes up fewer lines of source code,
meaning more code can fit on the screen at once, meaning the programmer can
see more of it on the screen and thus keep more if in their head at once.
-This helps code auditing and thus reduces bugs.</p>
-
-<p>Ken Thompson's maximum "when in doubt, use brute force" is an admonishment
-to start with the simplest possible approach and only optimize as needed.
-Although implementing a given set of features is the eventual purpose of
-toybox, we choose to weight simplicity more heavily than anything else.
-Complexity is what we spend to get features (and occasionally smaller size
-or faster running time than the simplest possible implementation). Sometimes
-a feature, speedup, or code shrink isn't worth the complexity cost. We want to
-get "the best bang for the byte" we can, but sometimes being more explicit
-is preferable to being clever enough to outsmart yourself. (Even the best
-programmers are only human.)</p>
-
-<p>Environmental dependencies are a type of complexity, so needing other
-packages to build or run is a big downside. For example, we don't use curses
-when we can simply output ansi escape sequences and trust all terminal
-programs written in the past 30 years to be able to support them. (A common
-use case is to download a statically linked toybox binary to an arbitrary
-Linux system, and use it in an otherwise unknown environment. It _must_ be
-completely self-contained to support this.)</p>
-
-<p><h1>Code style</h1></p>
+This helps code auditing and thus reduces bugs. That said, sometimes being
+more explicit is preferable to being clever enough to outsmart yourself:
+don't be so terse your code is unreadable.</p>
<p>Toybox source is formatted to be read with 4-space tab stops. Each file
starts with a special comment telling vi to set the tab stop to 4. Note that
<b><h2>Design goals</h2></b>
-<p>Toybox should be simple, small, and fast. Often, these things need to be
-balanced off against each other. In general, simple is slightly more
-important than small, and small is slightly more important than fast, but
-it should be possible to get 80% of the way to each goal before they really
-start to fight.</p>
+<p>Toybox should be simple, small, fast, and full featured. Often, these
+things need to be balanced off against each other. In general, keeping the
+code simple the most important (and hardest) goal, and small is slightly more
+important than fast. Features are the reason we write code in the first
+place but this has all been implemented before so if we can't do a better
+job why bother? It should be possible to get 80% of the way to each goal
+before they really start to fight.</p>
+
+<p>Here they are in reverse order of importance:</p>
+
+<b><h3>Features</h3></b>
+
+<p>The <a href=roadmap.html>roadmap</a> has the list of features we're
+trying to implement, and the reasons for them. After the 1.0 release
+some of that material may get moved here.</p>
+
+<p>Some things are simply outside the scope of the project: even though
+posix defines commands for compiling and linking, we're not going to include
+a compiler or linker (and support for a potentially infinite number of hardware
+targets). And until somebody comes up with a ~30k ssh implementation, we're
+going to point you at dropbear or polarssl.</p>
+
+<p>Environmental dependencies are a type of complexity, so needing other
+packages to build or run is a big downside. For example, we don't use curses
+when we can simply output ansi escape sequences and trust all terminal
+programs written in the past 30 years to be able to support them. (A common
+use case is to download a statically linked toybox binary to an arbitrary
+Linux system, and use it in an otherwise unknown environment; being
+self-contained helps support this.)</p>
<b><h3>Fast</h3></b>
<p>It's easy to say lots about optimizing for speed (which is why this section
-is so long), but at the same time it's the one we care the least about.
+is so long), but at the same time it's the optimization we care the least about.
The essence of speed is being as efficient as possible, which means doing as
little work as possible. A design that's small and simple gets you 90% of the
way there, and most of the rest is either fine-tuning or more trouble than
<p>Avoid special cases. Whenever you see similar chunks of code in more than
one place, it might be possible to combine them and have the users call shared
-code. (This is the most commonly cited trick, which doesn't make it easy.)</p>
+code. (This is the most commonly cited trick, which doesn't make it easy. If
+seeing two lines of code do the same thing makes you slightly uncomfortable,
+you've got the right mindset.)</p>
<p>Some specific advice: Using a char in place of an int when doing math
produces significantly larger code on some platforms (notably arm),
port to new processors, easy to audit for security holes, and easy to
understand. (Comments help, but they're no substitute for simple code.)</p>
+<p>Prioritizing simplicity tends to serve our other goals: simplifying code
+generally reduces its size (both in terms of binary size and runtime memory
+usage), and avoiding unnecessary work makes code run faster. Smaller code
+also tends to run faster on modern hardware due to CPU cacheing: fitting your
+code into L1 cache is great, and staying in L2 cache is still pretty good.</p>
+
+
<p><a href=http://www.joelonsoftware.com/articles/fog0000000069.html>Joel
Spolsky argues against throwing code out and starting over</a>, and he has
good points: an existing debugged codebase contains a huge amount of baked
<b><h2>Portability issues</h2></b>
<b><h3>Platforms</h3></b>
-<p>Toybox should run on every hardware platform Linux runs on. Other
-posix/susv3 environments (perhaps MacOS X or newlib+libgloss) are vaguely
-interesting but only if they're easy to support; I'm not going to spend much
-effort on them.</p>
+<p>Toybox should run on Android (alas, with bionic), and every other hardware
+platform Linux runs on. Other posix/susv4 environments (perhaps MacOS X or
+newlib+libgloss) are vaguely interesting but only if they're easy to support;
+I'm not going to spend much effort on them.</p>
<p>I don't do windows.</p>
<!--#include file="header.html" -->
-<h2>Currently implemented commands:</h2>
-<p>
-basename, bzcat, cal, cat, catv, chroot, chvt, cksum, count, cp, df, dirname,
-dmesg, echo, env, false, head, help, link, mkswap, nc, netcat, nice, nohup,
-oneit, patch, pwd, rmdir, seq, setsid, sha1sum, sleep, sort, sync, tee, true,
-truncate, tty, uname, unlink, unshare, wc, which, xargs, yes
-</p>
-
-<h2>Shell wrappers:</h2>
-<p>dos2unix, tac, unix2dos</p>
+<h2>See <a href=roadmap.html>roadmap</a> for current and planned
+command list.</h2>
<h2>News</h2>
+<hr><b>March 3, 2012</b>
+
+<blockquote><p>"They went unnoticed at Goonhilly, passed over Cape Canaveral
+without a blip, and Woomera and Jodrell Bank looked straight through them.
+Which was a pity, because it was exactly the sort of thing they'd been looking
+for all these years."</p></p>- The Hitchhiker's Guide to the Galaxy.</p>
+</p></blockquote>
+
+<p>Here's <a href=downloads/toybox-0.2.1.tar.bz2>toybox 0.2.1</a> based
+on <a href=http://landley.net/hg/toybox/shortlog/512>commit 512</a>. This
+time around, there are statically linked <a href=downloads/binaries>prebuilt
+binaries</a> for various embedded targets.</p>
+
+<p>It's been a busy few weeks, almost entirely due to new contributors. (I
+have not quite been keeping up.)</p>
+
+<p>Elie De Brauwer contributed free, uptime, swapon, swapoff, lsmod, mknod,
+insmod, rmmod, and fixed a bug in basename. Andre Renaud contributed ls, ln,
+realpath, and hostname. Andres Heck contributed pidof and killall. Daniel
+Walter wrote kill and extended id. Timothy Elliott contributed tail and tests
+for cmp. Frank Bergmann sent a warning fix. Bryce Fricke added -i to cp.
+Nathan McSween pointed out an optimization. Georgi Chorbadzhiyski fixed
+cross compiling to work more reliably.</p>
+
+<p>(My own contribution this time around was just tightening up other people's
+code, a build fix to unshare, some random bugfixes, and so on. My only new
+code this time around was writing a bash replacement for the existing python
+bloat-o-meter.)</p>
+
+<p>Last time (the 0.2.0 release) included the first pass at an id command from
+Tim Bird, env and basename from Tryn Mirell, cmp and head from Timothy Elliott,
+more bugfixes from Nathan McSween and Elie De Brauwer, and Luis Felipe Strano
+Moraes did a first pass at the who command plus other bugfixes and
+optimizations.</p>
+
+<p>(For that release I did xargs, cal, truncate, unlink, nohup, tty, wc, link,
+dirname, unshare, and various infrastructure tweaks, but it took me 3 months
+and those guys did their stuff in a week or so.)</p>
+
<hr><b>February 12, 2012</b>
<blockquote><p>
projects / platform / upstream / toybox.git / commitdiff