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