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 | |
| 33 | The file "configure" defines default values for many environment |
| 34 | variables that control the toybox build; if you set a value for any of |
| 35 | these, your value is used instead of the default in that file. |
| 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 |
| 39 | prefixed cross compiler toolchain, several example toolchains are available at: |
| 40 | |
| 41 | http;//landley.net/aboriginal/bin |
| 42 | |
| 43 | For the "CROSS_COMPILE=armv5l-" example above, download |
| 44 | cross-compiler-armv5l.tar.bz2, extract it, and add its "bin" subdirectory to |
| 45 | your $PATH. (And yes, the trailing - is significant, because the prefix |
| 46 | includes a dash.) |
| 47 | |
| 48 | For more about cross compiling, see: |
| 49 | |
| 50 | http://landley.net/writing/docs/cross-compiling.html |
| 51 | http://landley.net/aboriginal/architectures.html |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 52 | |
Rob Landley | 1cbc283 | 2015-10-28 21:41:45 -0500 | [diff] [blame] | 53 | For a more thorough description of the toybox build process, see |
| 54 | http://landley.net/toybox/code.html#building |
| 55 | |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 56 | --- Using toybox |
| 57 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 58 | The toybox build produces a multicall binary, a "swiss-army-knife" program |
| 59 | that acts differently depending on the name it was called by (cp, mv, cat...). |
| 60 | Installing toybox adds symlinks for each command name to the $PATH. |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 61 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 62 | The special "toybox" command treats its first argument as the command to run. |
| 63 | With no arguments, it lists available commands. This allows you to use toybox |
| 64 | without installing it. This is the only command that can have an arbitrary |
| 65 | suffix (hence "toybox-armv5l"). |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 66 | |
| 67 | The "help" command provides information about each command (ala "help cat"). |
| 68 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 69 | --- Configuring toybox |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 70 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 71 | It works like the Linux kernel: allnoconfig, defconfig, and menuconfig edit |
| 72 | a ".config" file that selects which features to include in the resulting |
Rob Landley | e8bd47b | 2016-05-02 18:59:57 -0500 | [diff] [blame] | 73 | binary. You can save and re-use your .config file, although may want to |
| 74 | run "make oldconfig" to re-run the dependency resolver when migrating to |
| 75 | new versions. |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 76 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 77 | The maximum sane configuration is "make defconfig": allyesconfig isn't |
| 78 | recommended for toybox because it enables unfinished commands and debug code. |
| 79 | |
| 80 | --- Creating a Toybox-based Linux system |
| 81 | |
| 82 | Toybox is not a complete operating system, it's a program that runs under |
| 83 | an operating system. Booting a simple system to a shell prompt requires |
Rob Landley | e8bd47b | 2016-05-02 18:59:57 -0500 | [diff] [blame] | 84 | three packages: an operating system kernel (Linux*) to drive the hardware, |
| 85 | one or more programs for the system to run (toybox), and a C library ("libc") |
| 86 | to tie them together (toybox has been tested with musl, uClibc, glibc, |
| 87 | and bionic). |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 88 | |
Rob Landley | a7c3e29 | 2014-01-01 13:24:03 -0600 | [diff] [blame] | 89 | The C library is part of a "toolchain", which is an integrated suite |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 90 | of compiler, assembler, and linker, plus the standard headers and libraries |
Rob Landley | e8bd47b | 2016-05-02 18:59:57 -0500 | [diff] [blame] | 91 | necessary to build C programs. (And miscellaneous binaries like nm and objdump.) |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 92 | |
Rob Landley | a7c3e29 | 2014-01-01 13:24:03 -0600 | [diff] [blame] | 93 | Static linking (with the --static option) copies the shared library contents |
| 94 | into the program, resulting in larger but more portable programs, which |
Rob Landley | a6916cd | 2015-04-07 14:59:32 -0500 | [diff] [blame] | 95 | can run even if they're the only file in the filesystem. Otherwise, |
Rob Landley | a7c3e29 | 2014-01-01 13:24:03 -0600 | [diff] [blame] | 96 | the "dynamically" linked programs require the library files to be present on |
| 97 | the target system ("man ldd" and "man ld.so" for details). |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 98 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 99 | An example toybox-based system is Aboriginal Linux: |
| 100 | |
Rob Landley | a6916cd | 2015-04-07 14:59:32 -0500 | [diff] [blame] | 101 | http://landley.net/aboriginal/about.html |
| 102 | |
| 103 | That's designed to run under qemu, emulating several different hardware |
| 104 | architectures (x86, x86-64, arm, mips, sparc, powerpc, sh4). Each toybox |
| 105 | release is regression tested by building Linux From Scratch under this |
| 106 | toybox-based system on each supported architecture, using QEMU to emulate |
| 107 | big and little endian systems with different word size and alignment |
Rob Landley | e8bd47b | 2016-05-02 18:59:57 -0500 | [diff] [blame] | 108 | requirements. (The eventual goal is to replace Linux From Scratch with |
| 109 | the Android Open Source Project.) |
| 110 | |
| 111 | * Or something providing the same API such as FreeBSD's Linux emulation layer. |
Rob Landley | a6916cd | 2015-04-07 14:59:32 -0500 | [diff] [blame] | 112 | |
| 113 | --- Presentations |
| 114 | |
Rob Landley | e8bd47b | 2016-05-02 18:59:57 -0500 | [diff] [blame] | 115 | 1) "Why Toybox?" talk at the Embedded Linux Conference in 2013 |
Rob Landley | a6916cd | 2015-04-07 14:59:32 -0500 | [diff] [blame] | 116 | |
| 117 | video: http://youtu.be/SGmtP5Lg_t0 |
| 118 | outline: http://landley.net/talks/celf-2013.txt |
| 119 | linked from http://landley.net/toybox/ in nav bar on left as "Why is it?" |
| 120 | - march 21, 2013 entry has section links. |
| 121 | |
| 122 | 2) "Why Public Domain?" The rise and fall of copyleft, Ohio LinuxFest 2013 |
| 123 | |
| 124 | audio: https://archive.org/download/OhioLinuxfest2013/24-Rob_Landley-The_Rise_and_Fall_of_Copyleft.mp3 |
| 125 | outline: http://landley.net/talks/ohio-2013.txt |
| 126 | |
| 127 | 3) Why did I do Aboriginal Linux (which led me here) |
| 128 | |
| 129 | 260 slide presentation: |
| 130 | https://speakerdeck.com/landley/developing-for-non-x86-targets-using-qemu |
| 131 | |
| 132 | How and why to make android self-hosting: |
| 133 | http://landley.net/aboriginal/about.html#selfhost |
| 134 | |
| 135 | 4) What's new with toybox (ELC 2015 status update): |
| 136 | |
| 137 | video: http://elinux.org/ELC_2015_Presentations |
| 138 | outline: http://landley.net/talks/celf-2015.txt |
Rob Landley | b057bac | 2015-12-01 11:13:08 -0600 | [diff] [blame] | 139 | |
Rob Landley | e8bd47b | 2016-05-02 18:59:57 -0500 | [diff] [blame] | 140 | --- Contributing |
| 141 | |
| 142 | The three important URLs for communicating with the toybox project are: |
| 143 | |
| 144 | web page: http://landley.net/toybox |
| 145 | |
| 146 | mailing list: http://lists.landley.net/listinfo.cgi/toybox-landley.net |
| 147 | |
| 148 | git repo: http://github.com/landley/toybox |
| 149 | |
| 150 | The maintainer prefers patches be sent to the mailing list. If you use git, |
| 151 | the easy thing to do is: |
| 152 | |
| 153 | git format-patch -1 $HASH |
| 154 | |
| 155 | Then send a file attachment. The list holds messages from non-subscribers |
| 156 | for moderation, but I usually get to them in a day or two. |
| 157 | |
| 158 | Although I do accept pull requests on github, I download the patches and |
| 159 | apply them with "git am" (which avoids gratuitous merge commits). Closing |
| 160 | the pull request is then the submitter's responsibility. |
| 161 | |
| 162 | If I haven't responded to your patch after one week, feel free to remind |
| 163 | me of it. |
| 164 | |
| 165 | Android's policy for toybox patches is that non-build patches should go |
| 166 | upstream first (into vanilla toybox, with discussion on the toybox mailing |
| 167 | list) and then be pulled into android's toybox repo from there. (They |
| 168 | generally resync on fridays). The exception is patches to their build scripts |
| 169 | (Android.mk and the checked-in generated/* files) which go directly to AOSP. |
| 170 | |
Rob Landley | b057bac | 2015-12-01 11:13:08 -0600 | [diff] [blame] | 171 | --- Code of conduct |
| 172 | |
| 173 | We're using twitter's https://engineering.twitter.com/opensource/code-of-conduct |
| 174 | except email rob@landley.net with complaints. |
Rob Landley | e8bd47b | 2016-05-02 18:59:57 -0500 | [diff] [blame] | 175 | |
| 176 | (Yes, I try to pay more attention to marginalized programmers, which somehow |
| 177 | manages to include 51% of the population. If somebody has to be three times as |
| 178 | good to get half the recognition, why WOULDN'T you adjust for that?) |