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 | |
| 13 | wget http://landley.net/bin/toybox-x86_64 |
| 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 | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 21 | Usually you want something like: |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 22 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 23 | make defconfig |
| 24 | CFLAGS="--static" CROSS_COMPILE=armv5l- make toybox |
| 25 | PREFIX=/path/to/root/filesystem make install |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 26 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 27 | The CROSS_COMPILE argument is optional, and without it builds a version of |
| 28 | toybox to run on the current machine. Cross compiling requires an appropriately |
| 29 | prefixed cross compiler toolchain, several example toolchains are available at: |
| 30 | |
| 31 | http;//landley.net/aboriginal/bin |
| 32 | |
| 33 | For the "CROSS_COMPILE=armv5l-" example above, download |
| 34 | cross-compiler-armv5l.tar.bz2, extract it, and add its "bin" subdirectory to |
| 35 | your $PATH. (And yes, the trailing - is significant, because the prefix |
| 36 | includes a dash.) |
| 37 | |
| 38 | For more about cross compiling, see: |
| 39 | |
| 40 | http://landley.net/writing/docs/cross-compiling.html |
| 41 | http://landley.net/aboriginal/architectures.html |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 42 | |
| 43 | --- Using toybox |
| 44 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 45 | The toybox build produces a multicall binary, a "swiss-army-knife" program |
| 46 | that acts differently depending on the name it was called by (cp, mv, cat...). |
| 47 | Installing toybox adds symlinks for each command name to the $PATH. |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 48 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 49 | The special "toybox" command treats its first argument as the command to run. |
| 50 | With no arguments, it lists available commands. This allows you to use toybox |
| 51 | without installing it. This is the only command that can have an arbitrary |
| 52 | suffix (hence "toybox-armv5l"). |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 53 | |
| 54 | The "help" command provides information about each command (ala "help cat"). |
| 55 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 56 | --- Configuring toybox |
Rob Landley | 09e8bde | 2012-02-04 12:20:39 -0600 | [diff] [blame] | 57 | |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 58 | It works like the Linux kernel: allnoconfig, defconfig, and menuconfig edit |
| 59 | a ".config" file that selects which features to include in the resulting |
| 60 | binary. |
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 maximum sane configuration is "make defconfig": allyesconfig isn't |
| 63 | recommended for toybox because it enables unfinished commands and debug code. |
| 64 | |
| 65 | --- Creating a Toybox-based Linux system |
| 66 | |
| 67 | Toybox is not a complete operating system, it's a program that runs under |
| 68 | an operating system. Booting a simple system to a shell prompt requires |
| 69 | three packages: an operating system kernel (Linux) to drive the hardware, |
| 70 | a program for the system to run (toybox), and a C library to tie them |
| 71 | together (toybox has been tested with musl, uClibc, and glibc, on Android |
| 72 | systems musl is recommended).</p> |
| 73 | |
Rob Landley | a7c3e29 | 2014-01-01 13:24:03 -0600 | [diff] [blame] | 74 | 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] | 75 | of compiler, assembler, and linker, plus the standard headers and libraries |
Rob Landley | a7c3e29 | 2014-01-01 13:24:03 -0600 | [diff] [blame] | 76 | necessary to build C programs. |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 77 | |
Rob Landley | a7c3e29 | 2014-01-01 13:24:03 -0600 | [diff] [blame] | 78 | Static linking (with the --static option) copies the shared library contents |
| 79 | into the program, resulting in larger but more portable programs, which |
| 80 | can run even if they'rr the only file in the filesystem. Otherwise, |
| 81 | the "dynamically" linked programs require the library files to be present on |
| 82 | the target system ("man ldd" and "man ld.so" for details). |
Rob Landley | 0b87b2e | 2013-05-07 22:50:33 -0500 | [diff] [blame] | 83 | |
| 84 | Toybox is not a kernel, it needs Linux to drive the hardware. |
| 85 | |
| 86 | An example toybox-based system is Aboriginal Linux: |
| 87 | |
| 88 | http://landley.net/aboriginal |