toybox/www/faq.html
<<
>>
Prefs
   1<html><head><title>toybox FAQ</title>
   2<!--#include file="header.html" -->
   3
   4<h1>Frequently Asked Questions</h1>
   5
   6<h2>General Questions</h2>
   7
   8<ul>
   9<li><h2><a href="#why_toybox">Why toybox? (What was wrong with busybox?)</a></h2></li>
  10<li><h2><a href="#capitalize">Do you capitalize toybox?</a></h2></li>
  11<li><h2><a href="#support_horizon">Why a 7 year support horizon?</a></h2></li>
  12<li><h2><a href="#releases">Why time based releases?</a></h2></li>
  13<li><h2><a href="#code">Where do I start understanding the toybox source code?</a></h2></li>
  14<li><h2><a href="#when">When were historical toybox versions released?</a></h2></li>
  15<li><h2><a href="#bugs">Where do I report bugs?</a></h2></li>
  16<li><h2><a href="#b_links">What are those /b/number links in the git log?</a></h2></li>
  17<li><h2><a href="#opensource">What is the relationship between toybox and android?</a></h2></li>
  18<li><h2><a href="#backporting">Will you backport fixes to old versions?</a></h2></li>
  19<li><h2><a href="#dotslash">What's this ./ on the front of commands in your examples?</a></h2></li>
  20
  21</ul>
  22
  23<h2>Using toybox</h2>
  24
  25<ul>
  26<!-- get binaries -->
  27<li><h2><a href="#install">How do I install toybox?</h2></li>
  28<li><h2><a href="#cross">How do I cross compile toybox?</h2></li>
  29<li><h2><a href="#targets">What architectures does toybox support?</li>
  30<li><h2><a href="#system">What part of Linux/Android does toybox provide?</h2></li>
  31<li><h2><a href="#mkroot">How do I build a working Linux system with toybox?</a></h2></li>
  32</ul>
  33
  34<hr /><h2><a name="why_toybox" />Q: "Why is there toybox? What was wrong with busybox?"</h2>
  35
  36<p>A: Toybox started back in 2006 when I (Rob Landley)
  37<a href=https://lwn.net/Articles/202106/>handed off BusyBox maintainership</a>
  38and <a href=http://landley.net/notes-2006.html#28-09-2006>started over from
  39scratch</a> on a new codebase after a
  40<a href=http://lists.busybox.net/pipermail/busybox/2006-September/058617.html>protracted licensing argument</a> took all the fun out of working on BusyBox.</p>
  41
  42<p>Toybox was just a personal project until it got
  43<a href=http://landley.net/notes-2011.html#13-11-2011>relaunched</a>
  44in November 2011 with a new goal to make Android
  45<a href=http://landley.net/aboriginal/about.html#selfhost>self-hosting</a>.
  46This involved me relicensing my own
  47code, which made people who had never used or participated in the project
  48<a href=https://lwn.net/Articles/478308/>loudly angry</a>. The switch came
  49after a lot of thinking <a href=http://landley.net/talks/ohio-2013.txt>about
  50licenses</a> and <a href=http://landley.net/notes-2011.html#21-03-2011>the
  51transition to smartphones</a>, which led to a
  52<a href=https://www.youtube.com/watch?v=SGmtP5Lg_t0>2013 talk</a> laying
  53out a
  54<a href=http://landley.net/talks/celf-2013.txt>strategy</a>
  55to make Android self-hosting using toybox. This helped
  56<a href=https://code.google.com/p/android/issues/detail?id=76861>bring
  57it to Android's attention</a>, and they
  58<a href=https://lwn.net/Articles/629362/>merged it</a> into Android M.</p>
  59
  60<p>The unfixable problem with busybox was licensing: BusyBox predates Android
  61by almost a decade, but Android still doesn't ship with it because GPLv3 came
  62out around the same time Android did and caused many people to throw
  63out the GPLv2 baby with the GPLv3 bathwater.
  64Android <a href=https://source.android.com/source/licenses.html>explicitly
  65discourages</a> use of GPL and LGPL licenses in its products, and has gradually
  66reimplemented historical GPL components (such as its bluetooth stack) under the
  67Apache license. Apple's
  68<a href=http://meta.ath0.com/2012/02/05/apples-great-gpl-purge/>less subtle</a> response was to freeze xcode at the last GPLv2 releases
  69(GCC 4.2.1 with binutils 2.17) for over 5 years while sponsoring the
  70development of new projects (clang/llvm/lld) to replace them,
  71implementing a
  72<a href=https://www.osnews.com/story/24572/apple-ditches-samba-in-favour-of-homegrown-replacement/>new SMB server</a> from scratch to
  73<a href=https://archive.org/details/copyleftconf2020-allison>replace samba</a>,
  74switching <a href=https://www.theverge.com/2019/6/4/18651872/apple-macos-catalina-zsh-bash-shell-replacement-features>bash with zsh</a>, and so on.
  75Toybox itself exists because somebody in a legacy position
  76just wouldn't shut up about GPLv3, otherwise I would probably
  77still happily be maintaining BusyBox. (For more on how I wound
  78up working on busybox in the first place,
  79<a href=http://landley.net/aboriginal/history.html>see here</a>.)</p>
  80
  81<hr /><h2><a name="capitalize" />Q: Do you capitalize toybox?</h2>
  82
  83<p>A: Only at the start of a sentence. The command name is all lower case so
  84it seems silly to capitalize the project name, but not capitalizing the
  85start of sentences is awkward, so... compromise. (It is _not_ "ToyBox".)</p>
  86
  87<hr /><h2><a name="support_horizon">Q: Why a 7 year support horizon?</a></h2>
  88
  89<p>A: Our <a href=http://lists.busybox.net/pipermail/busybox/2006-September/058440.html>longstanding rule of thumb</a> is to try to run and build on
  90hardware and distributions released up to 7 years ago, and feel ok dropping
  91support for stuff older than that. (This is a little longer than Ubuntu's
  92Long Term Support, but not by much.)</p>
  93
  94<p>My original theory was "4 to 5 of the 18-month cycles of moore's law should cover
  95the vast majority of the installed base of PC hardware", loosely based on some
  96research I did <a href=http://www.catb.org/esr/halloween/halloween9.html#id2867629>back in 2003</a>
  97and <a href=http://catb.org/esr/writings/world-domination/world-domination-201.html#id248066>updated in 2006</a>
  98which said that low end systems were 2 iterations of moore's
  99law below the high end systems, and that another 2-3 iterations should cover
 100the useful lifetime of most systems no longer being sold but still in use and
 101potentially being upgraded to new software releases.</p>
 102
 103<p>That analysis missed <a href=http://landley.net/notes-2011.html#26-06-2011>industry
 104changes</a> in the 1990's that stretched the gap
 105from low end to high end from 2 cycles to 4 cycles, and ignored
 106<a href=https://landley.net/notes-2010.html#09-10-2010>the switch</a> from PC to smartphone cutting off the R&D air supply of the
 107laptop market. Meanwhile the Moore's Law <a href=https://en.wikipedia.org/wiki/Logistic_function>s-curve</a> started bending back down (as they
 108<a href=https://en.wikipedia.org/wiki/Diffusion_of_innovations>always do</a>)
 109back in 2000, and these days is pretty flat: the drive for faster clock
 110speeds <a href=http://www.anandtech.com/show/613>stumbled</a>
 111and <a href=http://www.pcworld.com/article/118603/article.html>died</a>, with
 112the subsequent drive to go "wide" maxing out for most applications
 113around 4x SMP with maybe 2 megabyte caches. These days the switch from exponential to
 114linear growth in hardware capabilities is
 115<a href=https://www.cnet.com/news/end-of-moores-law-its-not-just-about-physics/>common knowledge</a> and
 116<a href=http://www.acm.org/articles/people-of-acm/2016/david-patterson>widely
 117accepted</a>.</p>
 118
 119<p>But the 7 year rule of thumb stuck around anyway: if a kernel or libc
 120feature is less than 7 years old, I try to have a build-time configure test
 121for it to let the functionality cleanly drop out. I also keep old Ubuntu
 122images around in VMs to perform the occasional defconfig build there to
 123see what breaks. (I'm not perfect about this, but I accept bug reports.)</p>
 124
 125<hr /><h2><a name="releases" />Q: Why time based releases?</h2>
 126<p>A: Toybox targets quarterly releases (a similar schedule to the Linux
 127kernel) because Martin Michlmayr's excellent
 128<a href=http://www.youtube.com/watch?v=IKsQsxubuAA>talk on the
 129subject</a> was convincing. This is actually two questions, "why have
 130releases" and "why schedule them".</p>
 131
 132<p>Releases provide synchronization points where the developers certify
 133"it worked for me". Each release is a known version with predictable behavior,
 134and right or wrong at least everyone should be seeing
 135similar results so might be able to google an unexpected outcome.
 136Releases focus end-user testing on specific versions
 137where issues can be reproduced, diagnosed, and fixed.
 138Releases also force the developers to do periodic tidying, packaging,
 139documentation review, finish up partially implemented features languishing
 140in their private trees, and give regular checkpoints to measure progress.</p>
 141
 142<p>Changes accumulate over time: different feature sets, data formats,
 143control knobs... Toybox's switch from "ls -q" to "ls -b" as the default output
 144format was not-a-bug-it's-a "design improvement", but the
 145difference is academic if the change breaks somebody's script.
 146Releases give you the option to schedule upgrades as maintenance, not to rock
 147the boat just now, and use a known working release version until later.</p>
 148
 149<p>The counter-argument is that "continuous integration"
 150can be made robust with sufficient automated testing. But like the
 151<a href=https://web.archive.org/web/20131123071427/http://www.shirky.com/weblog/2013/11/healthcare-gov-and-the-gulf-between-planning-and-reality/>waterfall method</a>, this places insufficent
 152emphasis on end-user feedback and learning from real world experience.
 153Developer testing is either testing that the code does what the developers
 154expect given known inputs running in an established environment, or it's
 155regression testing against bugs previously found in the field. No plan
 156survives contact with the enemy, and technology always breaks once it
 157leaves the lab and encounters real world data and use cases in new
 158runtime and build environments.</p>
 159
 160<p>The best way to give new users a reasonable first experience is to point
 161them at specific stable versions where development quiesced and
 162extra testing occurred. There will still be teething troubles, but multiple
 163people experiencing the _same_ teething troubles can potentially
 164help each other out.</p>
 165
 166<p>Releases on a schedule are better than releases "when it's ready" for
 167the same reason a regularly scheduled bus beats one that leaves when it's
 168"full enough": the schedule lets its users make plans. Even if the bus leaves
 169empty you know when the next one arrives so missing this one isn't a disaster.
 170and starting the engine to leave doesn't provoke a last-minute rush of nearby
 171not-quite-ready passengers racing to catch it causing further delay and
 172repeated start/stop cycles as it ALMOST leaves.
 173(The video in the first paragraph goes into much greater detail.)</p>
 174
 175<hr /><h2><a name="code" />Q: Where do I start understanding the source code?</h2>
 176
 177<p>A: Toybox is written in C. There are longer writeups of the
 178<a href=design.html>design ideas</a> and a <a href=code.html>code walkthrough</a>,
 179and the <a href=about.html>about page</a> summarizes what we're trying to
 180accomplish, but here's a quick start:</p>
 181
 182<p>Toybox uses the standard three stage configure/make/install
 183<a href=code.html#building>build</a>, in this case "<b>make defconfig;
 184make; make install</b>". Type "<b>make help</b>" to
 185see available make targets.</p>
 186
 187<p><u>The configure stage</u> is copied from the Linux kernel (in the "kconfig"
 188directory), and saves your selections in the file ".config" at the top
 189level. The "<b>make defconfig</b>" target selects the
 190maximum sane configuration (enabling all the commands and features that
 191aren't unfinished, or only intended as examples, or debug code...) and is
 192probably what you want. You can use "<b>make menuconfig</b>" to manually select
 193specific commands to include, through an interactive menu (cursor up and
 194down, enter to descend into a sub-menu, space to select an entry, ? to see
 195an entry's help text, esc to exit). The menuconfig help text is the
 196same as the command's "<b>--help</b>" output.</p>
 197
 198<p><u>The "make" stage</u> creates a toybox binary (which is stripped, look in
 199generated/unstripped for the debug versions), and "<b>make install</b>" adds a bunch of
 200symlinks to toybox under the various command names. Toybox determines which
 201command to run based on the filename, or you can use the "toybox" name in which case the first
 202argument is the command to run (ala "toybox ls -l").</p>
 203
 204<p><u>You can also build
 205individual commands as standalone executables</u>, ala "make sed cat ls".
 206The "make change" target builds all of them, as in "change for a $20".</p>
 207
 208<p><u>The main() function is in main.c</u> at the top level,
 209along with setup plumbing and selecting which command to run this time.
 210The function toybox_main() in the same file implements the "toybox"
 211multiplexer command that lists and selects the other commands.</p>
 212
 213<p><u>The individual command implementations are under "toys"</u>, and are grouped
 214into categories (mostly based on which standard they come from, posix, lsb,
 215android...) The "pending" directory contains unfinished commands, and the
 216"examples" directory contains example code that aren't really useful commands.
 217Commands in those two directories
 218are _not_ selected by defconfig. (Most of the files in the pending directory
 219are third party submissions that have not yet undergone
 220<a href=cleanup.html>proper code review</a>.)</p>
 221
 222<p><u>Common infrastructure shared between commands is under "lib"</u>. Most
 223commands call lib/args.c to parse their command line arguments before calling
 224the command's own main() function, which uses the option string in
 225the command's NEWTOY() macro. This is similar to the libc function getopt(),
 226but more powerful, and is documented at the top of lib/args.c. A NULL option
 227string prevents this code from being called for that command.</p>
 228
 229<p><u>The build/install infrastructure is shell scripts under
 230"scripts"</u> (starting with scripts/make.sh and scripts/install.sh).
 231<u>These populate the "generated" directory</u> with headers
 232created from other files, which are <a href=code.html#generated>described</a>
 233in the code walkthrough. All the
 234build's temporary files live under generated, including the .o files built
 235from the .c files (in generated/obj). The "make clean" target deletes that
 236directory. ("make distclean" also deletes your .config and deletes the
 237kconfig binaries that process .config.)</p>
 238
 239<p><u>Each command's .c file contains all the information for that command</u>, so
 240adding a command to toybox means adding a single file under "toys".
 241Usually you <a href=code.html#adding>start a new command</a> by copying an
 242existing command file to a new filename
 243(toys/examples/hello.c, toys/examples/skeleton.c, toys/posix/cat.c,
 244and toys/posix/true.c have all been used for this purpose) and then replacing
 245all instances of its old name with the new name (which should match the
 246new filename), and modifying the help text, argument string, and what the
 247code does. You might have to "make distclean" before your new command
 248shows up in defconfig or menuconfig.</p>
 249
 250<p><u>The toybox test suite lives in the "tests" directory</u>, and is
 251driven by scripts/test.sh and scripts/runtest.sh. From the top
 252level you can "make tests" to test everything, or "make test_sed" to test a
 253single command's standalone version (which should behave identically,
 254but that's why we test). You can set TEST_HOST=1 to test the host version
 255instead of the toybox version (in theory they should work the same),
 256and VERBOSE=all to see diffs of the expected and actual output for all
 257failing tests. The default VERBOSE=fail stops at the first such failure.</p>
 258
 259<hr /><h2><a name="when" />Q: When were historical toybox versions released?</h2>
 260
 261<p>A: For vanilla releases, check the
 262<a href=https://github.com/landley/toybox/tags>date on the commit tag</a>
 263or <a href=https://landley.net/toybox/downloads/binaries/>the
 264example binaries</a> against the output of "toybox --version".
 265Between releases the --version
 266information is in "git describe --tags" format with "tag-count-hash" showing the
 267most recent commit tag, the number of commits since that tag, and
 268the hash of the current commit.</p>
 269
 270<p>Android makes its own releases on its own
 271<a href=https://en.wikipedia.org/wiki/Android_version_history>schedule</a>
 272using its own version tags, but lists corresponding upstream toybox release
 273versions <a href=https://android.googlesource.com/platform/system/core/+/master/shell_and_utilities/README.md>here</a>. For more detail you can look up
 274<a href=https://android.googlesource.com/platform/external/toybox/+refs>AOSP's
 275git tags</a>. (The <a href=https://source.android.com/setup/start>Android Open Source Project</a> is the "upstream" android vendors
 276start form when making their own releases. Google's phones run AOSP versions
 277verbatim, other vendors tend to take those releases as starting points to
 278modify.)</p>
 279
 280<p>If you want to find the vanilla toybox commit corresponding to an AOSP
 281toybox version, find the most recent commit in the android log that isn't from a
 282@google or @android address and search for it in the vanilla commit log.
 283(The timestamp should match but the hash will differ,
 284because each git hash includes the previous
 285git hash in the data used to generate it so all later commits have a different
 286hash if any of the tree's history differs; yes Linus Torvalds published 3 years
 287before Satoshi Nakamoto.) Once you've identified the vanilla commit's hash,
 288"git describe --tags $HASH" in the vanilla tree should give you the --version
 289info for that one.</p>
 290
 291<hr /><h2><a name="bugs" />Q: Where do I report bugs?</h2>
 292
 293<p>A: Ideally on the <a href=http://lists.landley.net/listinfo.cgi/toybox-landley.net>mailing list</a>, although <a href=mailto:rob@landley.net>emailing the
 294maintainer</a> is a popular if slightly less reliable alternative.
 295Issues submitted to <a href=https://github.com/landley/toybox>github</a>
 296are generally dealt with less promptly, but mostly get done eventually.
 297AOSP has its <a href=https://source.android.com/setup/contribute/report-bugs>own bug reporting mechanism</a> (although for toybox they usually forward them
 298to the mailing list) and Android vendors usually forward them to AOSP which
 299forwards them to the list.</p>
 300
 301<p>Note that if we can't reproduce a bug, we probably can't fix it.
 302Not only does this mean providing enough information for us to see the
 303behavior ourselves, but ideally doing so in a reasonably current version.
 304The older it is the greater the chance somebody else found and fixed it
 305already, so the more out of date the version you're reporting a bug against
 306the less effort we're going to put into reproducing the problem.</p>
 307
 308<hr /><h2><a name="b_links" />Q: What are those /b/number bug report
 309links in the git log?</h2>
 310
 311<p>A: It's a Google thing. Replace /b/$NUMBER with
 312https://issuetracker.google.com/$NUMBER to read it outside the googleplex.</p>
 313
 314<hr /><a name="opensource" /><h2>Q: What is the relationship between toybox and android?</h2>
 315
 316<p>A: The <a href=about.html>about page</a> tries to explain that,
 317and Linux Weekly News has covered toybox's history a
 318<a href=https://lwn.net/Articles/202106/>little</a>
 319<a href=https://lwn.net/Articles/478308/>over</a>
 320<a href=https://lwn.net/Articles/616272/>the</a>
 321<a href=https://lwn.net/Articles/629362/>years</a>.</p>
 322
 323<p>Toybox is a traditional open source project created and maintained
 324by hobbyist (volunteer) developers, originally for Linux but these days
 325also running on Android, BSD, and MacOS. The project started in 2006
 326and its original author (Rob Landley)
 327continues to maintain the open source project.</p>
 328
 329<p>Android's base OS maintainer (Elliott Hughes, I.E. enh)
 330<a href=https://github.com/landley/toybox/commit/69a9f257234a>ported</a>
 331<a href=https://github.com/landley/toybox/commit/6a29bb1ebe62>toybox</a>
 332to Android in 2014, merged it into Android M (Marshmallow), and remains
 333Android's toybox maintainer. (He explained it in his own words in
 334<a href=http://androidbackstage.blogspot.com/2016/07/episode-53-adb-on-adb.html>this podcast</a>, starting either 18 or 20 minutes in depending how
 335much backstory you want.)</p>
 336
 337<p>Android's policy for toybox development is to push patches to the
 338open source project (submitting them via the mailing list) then
 339"git pull" the public tree into Android's tree. To avoid merge conflicts, Android's
 340tree doesn't change any of the existing toybox files but instead adds <a href=https://android.googlesource.com/platform/external/toybox/+/refs/heads/master/Android.bp>parallel
 341build infrastructure</a> off to one side. (Toybox uses a make wrapper around bash
 342scripts, AOSP builds with soong/ninja instead and checks in a snapshot of the
 343generated/ directory to avoid running kconfig each build).
 344Android's changes to toybox going into the open source tree first
 345and being pulled from there into Android keeps the two trees in
 346sync, and makes sure each change undergoes full open source design review
 347and discussion.</p>
 348
 349<p>Rob acknowledges Android is by far the largest userbase for the project,
 350but develops on a standard 64-bit Linux+glibc distro while building embedded
 35132-bit big-endian nommu musl systems requiring proper data alignment for work,
 352and is not a Google employee so does not have access
 353to the Google build cluster of powerful machines capable of running the full
 354AOSP build in a reasonable amount of time. Rob is working to get android
 355building under android (the list of toybox tools Android's build uses is
 356<a href=https://android.googlesource.com/platform/prebuilts/build-tools/+/refs/heads/master/path/linux-x86/>here</a>,
 357and what else it needs from its build environment is
 358<a href=https://android.googlesource.com/platform/build/soong/+/refs/heads/master/ui/build/paths/config.go>here</a>), and he hopes someday to not only make a usable development
 359environment out of it but also nudge the base OS towards a more granular
 360package management system allowing you to upgrade things like toybox without
 361a complete reinstall and reboot, plus the introduction of a "posix container"
 362within which you can not only run builds, but selinux lets you run binaries
 363you've just built). In the meantime, Rob tests static bionic
 364builds via the Android NDK when he remembers, but has limited time to work
 365on toybox because it's not his day job. (The products his company makes ship
 366toybox and they do sponsor the project's development, but it's one of many
 367responsibilities at work.)</p>
 368
 369<p>Elliott is the Android base OS maintainer, in which role he manages
 370a team of engineers. He also has limited time for toybox, both because it's one
 371of many packages he's responsible for (he maintains bionic, used to maintain
 372dalvik...) and because he allowed himself to be promoted into management
 373and thus spends less time coding than he does sitting in meetings where testers
 374talk to security people about vendor issues.</p>
 375
 376<p>Android has many other coders and security people who submit the occasional
 377toybox patch, but of the last 1000 commits at the <a href=https://github.com/landley/toybox/commit/88b34c4bd3f8>time
 378of writing</a> this FAQ entry, Elliott submitted 276 and all other google.com
 379or android.com addresses combined totaled 17. (Rob submitted 591, leaving
 380116 from other sources, but for both Rob and Elliott there's a lot of "somebody
 381else pointed out an issue, and then we wrote a patch". A lot of patches
 382from both "Author:" lines thank someone else for the suggestion in the
 383commit comment.)</p>
 384
 385<hr /><a name="backporting" /><h2>Q: Will you backport fixes to old versions?</h2>
 386
 387<p>A: Probably not. The easiest thing to do is get your issue fixed upstream
 388in the current release, then get the newest version of the
 389project built and running in the old environment.</p>
 390
 391<p>Backporting fixes generally isn't something open source projects run by
 392volunteer developers do because the goal of the project's development community
 393is to extend and improve the project. We're happy to respond to our users'
 394needs, but if you're coming to the us for free tech support we're going
 395to ask you to upgrade to a current version before we try to diagnose your
 396problem.</p>
 397
 398<p>The volunteers are happy to fix any bugs you point out in the current
 399versions because doing so helps everybody and makes the project better. We
 400want to make the current version work for you. But diagnosing, debugging, and
 401backporting fixes to old versions doesn't help anybody but you, so isn't
 402something we do for free. The cost of volunteer tech support is using a
 403reasonably current version of the project.</p>
 404
 405<p>If you're using an old version built with an old
 406compiler on an old OS (kernel and libc), there's a fairly large chance
 407whatever problem you're
 408seeing already got fixed, and to get that fix all you have to do is upgrade
 409to a newer version. Diagnosing a problem that wasn't our bug means we spent
 410time that only helps you, without improving the project.
 411If you don't at least _try_ a current version, you're asking us for free
 412personalized tech support.</p>
 413
 414<p>Reproducing bugs in current versions also makes our job easier.
 415The further back in time
 416you are, the more work it is for us digging back in the history to figure
 417out what we hadn't done yet in your version. If spot a problem in a git
 418build pulled 3 days ago, it's obvious what changed and easy to fix or back out.
 419If you ask about the current release version 3 months after it came out,
 420we may have to think a while to remember what we did and there are a number of
 421possible culprits, but it's still tractable. If you ask about 3 year old
 422code, we have to reconstruct the history and the problem could be anything,
 423there's a lot more ground to cover and we haven't seen it in a while.</p>
 424
 425<p>As a rule of thumb, volunteers will generally answer polite questions about
 426a given version for about three years after its release before it's so old
 427we don't remember the answer off the top of our head. And if you want us to
 428put any _effort_ into tracking it down, we want you to put in a little effort
 429of your own by confirming it's still a problem with the current version
 430(I.E. we didn't fix it already). It's
 431also hard for us to fix a problem of yours if we can't reproduce it because
 432we don't have any systems running an environment that old.</p>
 433
 434<p>If you don't want to upgrade, you have the complete source code and thus
 435the ability to fix it yourself, or can hire a consultant to do it for you. If
 436you got your version from a vendor who still supports the older version, they
 437can help you. But there are limits as to what volunteers will feel obliged to
 438do for you.</p>
 439
 440<p>Commercial companies have different incentives. Your OS vendor, or
 441hardware vendor for preinstalled systems, may have their own bug reporting
 442mechanism and update channel providing backported fixes. And a paid consultant
 443will happily set up a special environment just to reproduce your problem.</p>
 444
 445<hr /><h2><a name="install" />Q: How do I install toybox?</h2>
 446
 447<p>A:
 448Multicall binaries like toybox behave differently based on the filename
 449used to call them, so if you "mv toybox ls; ./ls -l" it acts like ls. Creating
 450symlinks or hardlinks and adding them to the $PATH lets you run the
 451commands normally by name, so that's probably what you want to do.</p>
 452
 453<p>If you already have a <a href=https://landley.net/toybox/downloads/binaries/>toybox binary</a>
 454you can install a tree of command symlinks to
 455<a href=http://git.musl-libc.org/cgit/musl/tree/include/paths.h>the
 456standard path</a>
 457locations (<b>export PATH=/bin:/usr/bin:/sbin:/usr/sbin</b>) by doing:</p>
 458
 459<blockquote><p><b>for i in $(/bin/toybox --long); do ln -s /bin/toybox $i; done</b></p></blockquote>
 460
 461<p>Or you can install all the symlinks in the same directory as the toybox binary
 462(<b>export PATH="$PWD:$PATH"</b>) via:</p>
 463
 464<blockquote><p><b>for i in $(./toybox); do ln -s toybox $i; done</b></p></blockquote></p>
 465
 466<p>When building from source, use the "<b>make install</b>" and
 467"<b>make install_flat</b>"
 468targets with an appropriate <b>PREFIX=/target/path</b> either
 469exported or on the make command line. When cross compiling,
 470"<b>make list</b>" outputs the command names enabled by defconfig.
 471For more information, see "<b>make help</b>".</p>
 472
 473<p>The command name "toybox" takes the second argument as the name of the
 474command to run, so "./toybox ls -l" also behaves like ls. The "toybox"
 475name is special in that it can have a suffix (toybox-i686 or toybox-1.2.3)
 476and still be recognized, so you can have multiple versions of toybox in the
 477same directory.</p>
 478
 479<p>When toybox doesn't recognize its
 480filename as a command, it dereferences one
 481level of symlink. So if your script needs "gsed" you can "ln -s sed gsed",
 482then when you run "gsed" toybox knows how to be "sed".</p>
 483
 484<hr /><h2><a name="dotslash" />Q: What's this ./ on the front of commands in your examples?</h2>
 485
 486<p>A: When you don't give a path to a command's executable file,
 487linux command shells search the directories listed in the $PATH envionment
 488variable (in order), which usually doesn't include the current directory
 489for security reasons. The
 490magic name "." indicates the current directory (the same way ".." means
 491the parent directory and starting with "/" means the root directory)
 492so "./file" gives a path to the executable file, and thus runs a command
 493out of the current directory where just typing "file" won't find it.
 494For historical reasons PATH is colon-separated, and treats an
 495empty entry (including leading/trailing colon) as "check the current
 496directory", so if you WANT to add the current directory to PATH you
 497can PATH="$PATH:" but doing so is a TERRIBLE idea.</p>
 498
 499<p>Toybox's shell (toysh) checks for built-in commands before looking at the
 500$PATH (using the standard "bash builtin" logic just with lots more builtins),
 501so "ls" doesn't have to exist in your filesystem for toybox to find it. When
 502you give a path to a command the shell won't run the built-in version
 503but will run the file at that location. (But the multiplexer command
 504won't: "toybox /bin/ls" runs the built-in ls, you can't point it at an
 505arbitrary file out of the filesystem and have it run that. You could
 506"toybox nice /bin/ls" though.)</p>
 507
 508<hr /><h2><a name="standalone" />Q: How do I make individual/standalone toybox command binaries?</h2>
 509
 510<p>After running the configure step (generally "make defconfig")
 511you can "make list" to see available command names you can use as build
 512targets to build just that command
 513(ala "make sed"). Commands built this way do not contain a multiplexer and
 514don't care what the command filename is.</p>
 515
 516<p>The "make change" target (as in change for a $20) builds every command
 517standalone (in the "change" subdirectory). Note that this is collectively
 518about 10 times as large as the multiplexer version, both in disk space and
 519runtime memory. (Even more when statically linked.)</p>
 520
 521<hr /><h2><a name="cross" />Q: How do I cross compile toybox?</h2>
 522
 523<p>A: You need a compiler "toolchain" capable of producing binaries that
 524run on your target. A <a href=https://landley.net/toybox/downloads/binaries/toolchains>toolchain</a> is an
 525integrated suite of compiler, assembler, and linker, plus the standard
 526headers and
 527libraries necessary to build C programs. (And a few miscellaneous binaries like
 528nm and objdump that display info about <a href=https://en.wikipedia.org/wiki/Executable_and_Linkable_Format>ELF files</a>.)</p>
 529
 530<p>Toybox supports the standard $CROSS_COMPILE prefix environnment variable,
 531same as the Linux kernel build uses. This is used to prefix all the tools
 532(target-cc, target-ld, target-strip) during the build, meaning the prefix
 533usually ends with a "-" that's easy to forget but kind of important
 534("target-cc" and "targetcc" are not the same name).</p>
 535
 536<p>You can either provide a
 537full path in the CROSS_COMPILE string, or add the appropriate bin directory
 538to your $PATH. I.E:</p>
 539
 540<blockquote>
 541<b><p>make LDFLAGS=--static CROSS_COMPILE=~/musl-cross-make/ccc/m68k-linux-musl-cross/bin/m68k-linux-musl- distclean defconfig toybox</p></b>
 542</blockquote>
 543
 544<p>Is equivalent to:</p>
 545
 546<blockquote><b><p>
 547export "PATH=~/musl-cross-make/ccc/m68k-linux-musl-cross/bin:$PATH"<br />
 548LDFLAGS=--static CROSS_COMPILE=m68k-linux-musl- make distclean defconfig toybox
 549</p></b></blockquote>
 550
 551<p>Both of those examples use static linking so you can install just
 552the single file to target, or test them with "qemu-m68k toybox". Feel free
 553to dynamically link instead if you prefer, mkroot offers a "dynamic"
 554add-on to copy the compiler's shared libraries into the new root
 555filesystem.</p>
 556
 557<p>Although you can individually override $CC and $STRIP and such,
 558providing the prefix twice applies it twice, ala
 559"CROSS_COMPILE=prefix- CC=prefix-cc" gives "prefix-prefix-cc".</p>
 560
 561<p>Toybox's <a href=#mkroot>system builder</a> can use a simpler $CROSS
 562variable to specify the target name(s) to build for if you've installed
 563<a href=#cross2>compatible</a> cross compilers under the "ccc" directory.
 564Behind the scenes this uses wildcard expansion to set $CROSS_COMPILE to
 565an appropriate "path/prefix-".</p>
 566
 567<hr /><h2><a name="targets">Q: What architectures does toybox support?</h2>
 568
 569<p>Toybox runs on 64 bit and 32 bit processors, little endian and big endian,
 570tries to respect alignment, and will enable nommu support when fork() is
 571unavailable (or when TOYBOX_FORCE_NOMMU is enabled in the config to
 572work around broken nommu toolchains), but otherwise tries to be
 573processor agnostic (although some commands such as strace can't avoid
 574a processor-specific if/else staircase.).</p>
 575
 576<P>Several commands (such as ps/top) are unavoidably full of Linux assumptions.
 577Some subset of the commands have been made to run on BSD and MacOS X, and
 578lib/portability.* and scripts/genconfig.sh exist to catch some known
 579variations.</p>
 580</p>
 581
 582<p>Each release gets tested against two compilers (llvm, gcc), three C
 583libraries (bionic, musl, glibc), and a half-dozen different processor
 584types, in the following combinations:</p>
 585
 586<a name="cross1" />
 587<p><a href="#cross1">1) gcc+glibc = host toolchain</a></p>
 588
 589<p>Most Linux distros come with that as a host compiler, which is used by
 590default when you build normally
 591(<b>make distclean defconfig toybox</b>, or <b>make menuconfig</b> followed
 592by <b>make</b>).</p>
 593
 594<p>You can use LDFLAGS=--static if you want static binaries, but static
 595glibc is hugely inefficient ("hello world" is 810k on x86-64) and throws a
 596zillion linker warnings because one of its previous maintainers
 597<a href=https://www.akkadia.org/drepper/no_static_linking.html>was insane</a>
 598(which meant at the time he refused to fix
 599<a href=https://elinux.org/images/2/2d/ELC2010-gc-sections_Denys_Vlasenko.pdf>obvious bugs</a>), plus it uses dlopen() at runtime to implement basic things like
 600<a href=https://stackoverflow.com/questions/15165306/compile-a-static-binary-which-code-there-a-function-gethostbyname>DNS lookup</a> (which is almost impossible
 601to support properly from a static binary because you wind up with two
 602instances of malloc() managing two heaps which corrupt as soon as a malloc()
 603from one is free()d into the other, although glibc added
 604<a href=https://stackoverflow.com/questions/14289488/use-dlsym-on-a-static-binary>improper support</a> which still requires the shared libraries to be
 605installed on the system alongside the static binary:
 606<a href=https://www.youtube.com/watch?v=Ih-3vK2qLls>in brief, avoid</a>).
 607These days glibc is <a href=https://blog.aurel32.net/175>maintained
 608by a committee</a> instead of a single
 609maintainer, if that's an improvement. (As with Windows and
 610Cobol, most people just try to get on with their lives.)</p>
 611
 612<a name="cross2" />
 613<p><a href="#cross2">2) gcc+musl = musl-cross-make</a></p>
 614
 615<p>These cross compilers are built from the
 616<a href=http://musl.libc.org/>musl-libc</a> maintainer's
 617<a href=https://github.com/richfelker/musl-cross-make>musl-cross-make</a>
 618project, built by running toybox's <a href=https://github.com/landley/toybox/blob/master/scripts/mcm-buildall.sh>scripts/mcm-buildall.sh</a> in that directory,
 619and then symlink the resulting "ccc" subdirectory into toybox where
 620"make root CROSS=" can find them, ala:</p>
 621
 622<blockquote><b><pre>
 623cd ~
 624git clone https://github.com/landley/toybox
 625git clone https://github.com/richfelker/musl-cross-make
 626cd musl-cross-make
 627../toybox/scripts/mcm-buildall.sh # this takes a while
 628ln -s $(realpath ccc) ../toybox/ccc
 629</pre></b></blockquote>
 630
 631<p>Since this takes a long time to run, and builds lots of targets
 632(cross and native), we've uploaded
 633<a href=downloads/binaries/toolchains/latest>the resulting binaries</a>
 634so you can wget and extract a tarball or two instead of
 635compiling them all yourself. (See the README in that directory for details.
 636Yes there's a big source tarball in there for license compliance reasons.)</p>
 637
 638<p>Instead of CROSS= you can also specify a CROSS_COMPILE= prefix
 639in the same format the Linux kernel build uses. You can either provide a
 640full path in the CROSS_COMPILE string, or add the appropriate bin directory
 641to your $PATH. I.E:</p>
 642
 643<blockquote>
 644<b><p>make LDFLAGS=--static CROSS_COMPILE=~/musl-cross-make/ccc/m68k-linux-musl-cross/bin/m68k-linux-musl- distclean defconfig toybox</p></b>
 645</blockquote>
 646
 647<p>Is equivalent to:</p>
 648
 649<blockquote><b><p>
 650export "PATH=~/musl-cross-make/ccc/m68k-linux-musl-cross/bin:$PATH"<br />
 651LDFLAGS=--static make distclean defconfig toybox CROSS=m68k-linux-musl-
 652</p></b></blockquote>
 653
 654<p>Note: these examples use static linking because a dynamic musl binary
 655won't run on your host unless you install musl's libc.so into the system
 656libraries (which is an accident waiting to happen adding a second C library
 657to most glibc linux distribution) or play with $LD_LIBRARY_PATH.
 658(The <a href=https://github.com/landley/toybox/blob/master/scripts/root/dynamic>dynamic</a> package
 659in mkroot copies the shared libraries out of the toolchain to create a dynamic
 660linking environment in the root filesystem, but it's not nearly as well
 661tested.)</p>
 662
 663<a name="cross3" />
 664<p><a href="#cross3">3) llvm+bionic = Android NDK</a></p>
 665
 666<p>The <a href=https://developer.android.com/ndk/downloads>Android
 667Native Development Kit</a> provides an llvm toolchain with the bionic
 668libc used by Android. To turn it into something toybox can use, you
 669just have to add an appropriately prefixed "cc" symlink to the other
 670prefixed tools, ala:</p>
 671
 672<blockquote><b><pre>
 673unzip android-ndk-r21b-linux-x86_64.zip
 674cd android-ndk-21b/toolchains/llvm/prebuilt/linux-x86_64/bin
 675ln -s x86_64-linux-android29-clang x86_64-linux-android-cc
 676PATH="$PWD:$PATH"
 677cd ~/toybox
 678make distclean
 679make LDFLAGS=--static CROSS_COMPILE=x86_64-linux-android- defconfig toybox
 680</pre></b></blockquote>
 681
 682<p>Again, you need to static link unless you want to install bionic on your
 683host. Binaries statically linked against bionic are almost as big as with
 684glibc, but at least it doesn't have the dlopen() issues. (You still can't
 685sanely use dlopen() from a static binary, but bionic doesn't use dlopen()
 686internally to implement basic features.)</p>
 687
 688<p>Note: although the resulting toybox will run in a standard
 689Linux system, even "hello world"
 690statically linked against bionic segfaults before calling main()
 691when /dev/null isn't present. This presents mkroot with a chicken and
 692egg problem for both chroot and qemu cases, because mkroot's init script
 693has to mount devtmpfs on /dev to provide /dev/null before the shell binary
 694can run mkroot's init script.
 695Since mkroot runs as a normal user, we can't "mknod dev/null" at build
 696time to create a "null" device in the filesystem we're packaging up so
 697initramfs doesn't start with an empty /dev, and the
 698<a href=https://lkml.org/lkml/2016/6/22/686>kernel</a>
 699<a href=https://lkml.org/lkml/2017/5/14/180>developers</a>
 700<a href=https://lkml.org/lkml/2017/9/13/651>repeatedly</a>
 701<a href=https://lkml.org/lkml/2020/5/14/1584>rejected</a> a patch to
 702make the Linux kernel honor DEVTMPFS_MOUNT in initramfs. Teaching toybox
 703cpio to accept synthetic filesystem metadata,
 704presumably in <a href=https://www.kernel.org/doc/Documentation/filesystems/ramfs-rootfs-initramfs.txt>get_init_cpio</a> format, remains a todo item.</p>
 705
 706<hr /><h2><a name="system" />Q: What part of Linux/Android does toybox provide?</h2>
 707
 708<p>A:
 709Toybox is one of three packages (linux, libc, command line) which together provide a bootable unix-style command line operating system.
 710Toybox provides the "command line" part, with a
 711<a href=https://en.wikipedia.org/wiki/Bash_(Unix_shell)>bash</a> compatible
 712<a href=https://en.wikipedia.org/wiki/Unix_shell>command line interpreter</a>
 713and over two hundred <a href=https://landley.net/toybox/help.html>commands</a>
 714to call from it, as documented in
 715<a href=https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/>posix</a>,
 716the <a href=https://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/cmdbehav.html>Linux Standard Base</a>, and the
 717<a href=https://man7.org/linux/man-pages/dir_section_1.html>Linux Manual
 718Pages</a>.</p>
 719
 720<p>Toybox is not by itself a complete operating system, it's a set of standard command line utilities that run in an operating system.
 721Booting a simple system to a shell prompt requires a kernel to drive the hardware (such as Linux, or BSD with a Linux emulation layer), programs for the system to run (such as toybox's commands), and a C library ("libc") to connect them together.</p>
 722
 723<p>Toybox has a policy of requiring no external dependencies other than the
 724kernel and C library (at least for defconfig builds). Our "software bill
 725of materials" (SBOM) defaults to just "the C library", both at build time
 726and and runtime. You can optionally enable support for
 727additional libraries in menuconfig (such as openssl, zlib, or selinux),
 728but toybox either provides its own built-in versions of such functionality
 729(which the libraries provide larger, more complex, often assembly optimized
 730alternatives to), or allows things like selinux support to cleanly drop
 731out.</p>
 732
 733<p>Static linking (with the --static option) copies library contents
 734into the resulting binary, creating larger but more portable programs which
 735can run even if they're the only file in the filesystem. Otherwise,
 736the "dynamically" linked programs require each shared library file to be
 737present on the target system, either copied out of the toolchain or built
 738again from source (with potential version skew if they don't match the toolchain
 739versions exactly), plus a dynamic linker executable installed at a specific
 740absolute path. See the
 741<a href=https://www.man7.org/linux/man-pages/man1/ldd.1.html>ldd</a>,
 742<a href=https://www.man7.org/linux/man-pages/man8/ld.so.8.html>ld.so</a>,
 743and <a href=https://www.man7.org/linux/man-pages/man7/libc.7.html>libc</a>
 744man pages for details.</p>
 745
 746<p>Most embedded systems will add another package to the kernel/libc/cmdline
 747above containing the dedicated "application" that the embedded system exists to
 748run, plus any other packages that application depends on.
 749Build systems add a native version of the toolchain packages so
 750they can compile additional software on the resulting system. Desktop systems
 751add a GUI and additional application packages like web browsers
 752and video players. A linux distro like Debian adds hundreds of packages.
 753Android adds around a thousand.</p>
 754
 755<p>But all of these systems conceptually sit on a common three-package
 756"kernel/libc/cmdline" base (often inefficiently implemented and broken up
 757into more packages), and toybox aims to provide a simple, reproducible,
 758auditable version of the cmdline portion of that base.</p>
 759
 760<hr /><h2><a name="mkroot" />Q: How do you build a working Linux system with toybox?</h2>
 761
 762<p>A: Toybox has a built-in <a href=https://github.com/landley/toybox/blob/master/scripts/mkroot.sh>system builder</a>, with the Makefile target "<b>make
 763root</b>". To enter the resulting root filesystem, "<b>sudo chroot
 764root/host/fs /init</b>". Type "exit" to get back out.</p>
 765
 766<p>Prebuilt binary versions of these system images, suitable for running
 767under the emulator <a href=https://qemu.org>qemu</a>, are uploaded to
 768<a href=https://landley.net/toybox/downloads/binaries/mkroot/>the website</a>
 769each release if you'd like to try before building from source.</p>
 770
 771<p>You can cross compile simple three package (toybox+libc+linux) systems
 772configured to boot to a shell prompt under qemu by setting CROSS_COMPILE= to a
 773<a href=#cross>cross compiler</a> prefix (or by installing cross compilers
 774in the "ccc" subdirectory and specifying a target type with CROSS=)
 775and also pointing the build at a Linux kernel source directory, ala:</p>
 776
 777<blockquote><p><b>make root CROSS=sh4 LINUX=~/linux</b></p></blockquote>
 778
 779<p>Then you can <b>cd root/sh4; ./qemu-sh4.sh</b> to launch the emulator.
 780(You'll need the appropriate qemu-system-* emulator binary installed.)
 781Type "exit" when done and it should shut down the emulator on the way out,
 782similar to exiting the chroot version. (Except this is more like you ssh'd
 783to a remote machine: the emulator created its own CPU with its own memory
 784and I/O devices, and booted a kernel in it.)</p>
 785
 786<p>The build finds the <a href=#system>three packages</a> needed to produce
 787this system because 1) you're in a toybox source directory, 2) your cross
 788compiler has a libc built into it, 3) you tell it where to find a Linux kernel
 789source directory with LINUX= on the command line. If you don't say LINUX=,
 790it skips that part of the build and just produces a root filesystem directory
 791(root/$CROSS/fs or root/host/fs if no $CROSS target specified), which you
 792can chroot into if your architecture can run those binaries. (For PID other
 793than 1, the /init script at the top of the directory sets up and cleans up
 794the /proc mount points, so <b>chroot root/i686/fs /init</b> is a reasonable
 795"poke around and look at things" smoketest.)</p>
 796
 797<p>The CROSS= shortcut expects a "ccc" symlink in the toybox source directory
 798pointing at a directory full of cross compilers. The ones I test this with are
 799built from the musl-libc maintainer's
 800<a href=https://github.com/richfelker/musl-cross-make>musl-cross-make</a>
 801project, built by running toybox's
 802<a href=https://github.com/landley/toybox/blob/master/scripts/mcm-buildall.sh>scripts/mcm-buildall.sh</a> in a musl-cross-make checkout directory,
 803and then symlinking the resulting "ccc" subdirectory into toybox where CROSS=
 804can find them:</p>
 805
 806<blockquote><b><pre>
 807cd ~
 808git clone https://github.com/landley/toybox
 809git clone https://github.com/richfelker/musl-cross-make
 810cd musl-cross-make
 811../toybox/scripts/mcm-buildall.sh # this takes a while
 812ln -s $(realpath ccc) ../toybox/ccc
 813</pre></b></blockquote>
 814
 815<p>If you don't want to do that, you can download <a href=http://landley.net/toybox/downloads/binaries/toolchains/latest>prebuilt binary versions</a>
 816and extract them into a "ccc" subdirectory under the toybox source.</p>
 817
 818<p>Once you've installed the cross compilers, "<b>make root CROSS=help</b>"
 819should list all the available cross compilers it recognizes under ccc,
 820something like:</p>
 821
 822<blockquote><b><p>
 823aarch64 armv4l armv5l armv7l armv7m armv7r i486 i686 m68k microblaze mips mips64 mipsel powerpc powerpc64 powerpc64le s390x sh2eb sh4 x32 x86_64
 824</p></b></blockquote>
 825
 826<p>(A long time ago I
 827<a href=http://landley.net/aboriginal/architectures.html>tried to explain</a>
 828what some of these architectures were.)</p>
 829
 830<p>You can build all the targets at once, and can add additonal packages
 831to the build, by calling the script directly and listing packages on
 832the command line:</p>
 833
 834<blockquote>
 835<p><b>scripts/mkroot.sh CROSS=all LINUX=~/linux dropbear</b></p>
 836</blockquote>
 837
 838<p>An example package build script (building the dropbear ssh server, adding a
 839port forward from 127.0.0.1:2222 to the qemu command line, and providing a
 840ssh2dropbear.sh convenience script to the output directory) is provided
 841in the scripts/root directory. If you add your own scripts elsewhere, just
 842give a path to them on the command line. (No, I'm not merging more package build
 843scripts, I <a href=https://speakerdeck.com/landley/developing-for-non-x86-targets-using-qemu?slide=78>learned that lesson</a> long ago. But if you
 844want to write your own, feel free.)</p>
 845
 846<p>(Note: currently mkroot.sh cheats. If you don't have a .config it'll
 847make defconfig and add CONFIG_SH and CONFIG_ROUTE to it, because the new
 848root filesystem kinda needs those commands to function properly. If you already
 849have a .config that
 850_doesn't_ have CONFIG_SH in it, you won't get a shell prompt or be able to run
 851the init script without a shell. This is currently a problem because sh
 852and route are still in pending and thus not in defconfig, so "make root"
 853cheats and adds them. I'm working on it. tl;dr if make root doesn't work
 854"rm .config" and run it again, and all this should be fixed up in future when
 855those two commands are promoted out of pending so "make defconfig" would have
 856what you need anyway. It's designed to let yout tweak your config, which is
 857why it uses the .config that's there when there is one, but the default is
 858currently wrong because it's not quite finished yet. All this should be
 859cleaned up in a future release, before 1.0.)</p>
 860
 861
 862
 863<!--#include file="footer.html" -->
 864