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