1Toybox: all-in-one Linux command line. 2 3--- Getting started 4 5You can download static binaries for various targets from: 6 7 http://landley.net/toybox/bin 8 9The special name "." indicates the current directory (just like ".." means 10the parent directory), and you can run a program that isn't in the $PATH by 11specifying a path to it, so this should work: 12 13 wget http://landley.net/toybox/bin/toybox-x86_64 14 chmod +x toybox-x86_64 15 ./toybox-x86_64 echo hello world 16 17--- Building toybox 18 19Type "make help" for build instructions. 20 21Toybox uses the "make menuconfig; make; make install" idiom same as 22the Linux kernel. Usually you want something like: 23 24 make defconfig 25 make 26 make install 27 28Or maybe: 29 30 LDFLAGS="--static" CROSS_COMPILE=armv5l- make defconfig toybox 31 PREFIX=/path/to/root/filesystem/bin make install_flat 32 33The file "configure" defines default values for many environment variables 34that control the toybox build; if you export any of these variables into your 35environment, your value is used instead of the default in that file. 36 37The CROSS_COMPILE argument above is optional, the default builds a version of 38toybox to run on the current machine. Cross compiling requires an appropriately 39prefixed cross compiler toolchain, several example toolchains (built using 40the file "scripts/mcm-buildall.sh" in the toybox source) are available at: 41 42 https://mkroot.musl.cc/latest/ 43 44For the "CROSS_COMPILE=armv5l-" example above, download 45cross-compiler-armv5l.tar.bz2, extract it, and add its "bin" subdirectory to 46your $PATH. (And yes, the trailing - is significant, because the prefix 47includes a dash.) 48 49For more about cross compiling, see: 50 51 https://landley.net/toybox/faq.html#cross 52 http://landley.net/writing/docs/cross-compiling.html 53 http://landley.net/aboriginal/architectures.html 54 55For a more thorough description of the toybox build process, see: 56 57 http://landley.net/toybox/code.html#building 58 59--- Using toybox 60 61The toybox build produces a multicall binary, a "swiss-army-knife" program 62that acts differently depending on the name it was called by (cp, mv, cat...). 63Installing toybox adds symlinks for each command name to the $PATH. 64 65The special "toybox" command treats its first argument as the command to run. 66With no arguments, it lists available commands. This allows you to use toybox 67without installing it, and is the only command that can have an arbitrary 68suffix (hence "toybox-armv5l"). 69 70The "help" command provides information about each command (ala "help cat"), 71and "help toybox" provides general information about toybox. 72 73--- Configuring toybox 74 75It works like the Linux kernel: allnoconfig, defconfig, and menuconfig edit 76a ".config" file that selects which features to include in the resulting 77binary. You can save and re-use your .config file, but may want to 78run "make oldconfig" to re-run the dependency resolver when migrating to 79new versions. 80 81The maximum sane configuration is "make defconfig": allyesconfig isn't 82recommended as a starting point for toybox because it enables unfinished 83commands, debug code, and optional dependencies your build environment may 84not provide. 85 86--- Creating a Toybox-based Linux system 87 88Toybox has a built-in simple system builder (scripts/mkroot.sh) with a 89Makefile target: 90 91 make root 92 sudo chroot root/host/fs /init 93 94Type "exit" to get back out. If you install appropriate cross compilers and 95point it at Linux source code, it can build simple three-package systems 96that boot to a shell prompt under qemu: 97 98 make root CROSS_COMPILE=sh4-linux-musl- LINUX=~/linux 99 cd root/sh4 100 ./qemu-sh4.sh 101 102By calling scripts/mkroot.sh directly you can add additional packages 103to the build, see scripts/root/dropbear as an example. 104 105The FAQ explains this in a lot more detail: 106 107 https://landley.net/toybox/faq.html#system 108 https://landley.net/toybox/faq.html#mkroot 109 110--- Presentations 111 1121) "Why Toybox?" talk at the Embedded Linux Conference in 2013 113 114 outline: http://landley.net/talks/celf-2013.txt 115 video: http://youtu.be/SGmtP5Lg_t0 116 117 The https://landley.net/toybox/about.html page has nav links breaking that 118 talk down into sections. 119 1202) "Why Public Domain?" The rise and fall of copyleft, Ohio LinuxFest 2013 121 122 outline: http://landley.net/talks/ohio-2013.txt 123 audio: https://archive.org/download/OhioLinuxfest2013/24-Rob_Landley-The_Rise_and_Fall_of_Copyleft.mp3 124 1253) Why did I do Aboriginal Linux (which led me here) 126 127 260 slide presentation: 128 https://speakerdeck.com/landley/developing-for-non-x86-targets-using-qemu 129 130 How and why to make android self-hosting: 131 http://landley.net/aboriginal/about.html#selfhost 132 133 More backstory than strictly necessary: 134 https://landley.net/aboriginal/history.html 135 1364) What's new with toybox (ELC 2015 status update): 137 138 video: http://elinux.org/ELC_2015_Presentations 139 outline: http://landley.net/talks/celf-2015.txt 140 1415) Toybox vs BusyBox (2019 ELC talk): 142 143 outline: http://landley.net/talks/elc-2019.txt 144 video: https://www.youtube.com/watch?v=MkJkyMuBm3g 145 146--- Contributing 147 148The three important URLs for communicating with the toybox project are: 149 150 web page: http://landley.net/toybox 151 152 mailing list: http://lists.landley.net/listinfo.cgi/toybox-landley.net 153 154 git repo: http://github.com/landley/toybox 155 156The maintainer prefers patches be sent to the mailing list. If you use git, 157the easy thing to do is: 158 159 git format-patch -1 $HASH 160 161Then send a file attachment. The list holds messages from non-subscribers 162for moderation, but I usually get to them in a day or two. 163 164I download github pull requests as patches and apply them with "git am" 165(which avoids gratuitous merge commits). Sometimes I even remember to close 166the pull request. 167 168If I haven't responded to your patch after one week, feel free to remind 169me of it. 170 171Android's policy for toybox patches is that non-build patches should go 172upstream first (into vanilla toybox, with discussion on the toybox mailing 173list) and then be pulled into android's toybox repo from there. (They 174generally resync on fridays). The exception is patches to their build scripts 175(Android.mk and the checked-in generated/* files) which go directly to AOSP. 176 177(As for the other meaning of "contributing", https://patreon.com/landley is 178always welcome but I warn you up front I'm terrible about updating it.) 179