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