blob: 9ff7368110bda0078d45c6db843b4e24bca7c3cd [file] [log] [blame]
Toybox: all-in-one Linux command line.
--- Getting started
You can download static binaries for various targets from:
The special name "." indicates the current directory (just like ".." means
the parent directory), and you can run a program that isn't in the $PATH by
specifying a path to it, so this should work:
chmod +x toybox-x86_64
./toybox-x86_64 echo hello world
--- Building toybox
Type "make help" for build instructions.
Usually you want something like:
make defconfig
LDFLAGS="--static" CROSS_COMPILE=armv5l- make toybox
PREFIX=/path/to/root/filesystem make install
The CROSS_COMPILE argument is optional, and without it builds a version of
toybox to run on the current machine. Cross compiling requires an appropriately
prefixed cross compiler toolchain, several example toolchains are available at:
For the "CROSS_COMPILE=armv5l-" example above, download
cross-compiler-armv5l.tar.bz2, extract it, and add its "bin" subdirectory to
your $PATH. (And yes, the trailing - is significant, because the prefix
includes a dash.)
For more about cross compiling, see:
--- Using toybox
The toybox build produces a multicall binary, a "swiss-army-knife" program
that acts differently depending on the name it was called by (cp, mv, cat...).
Installing toybox adds symlinks for each command name to the $PATH.
The special "toybox" command treats its first argument as the command to run.
With no arguments, it lists available commands. This allows you to use toybox
without installing it. This is the only command that can have an arbitrary
suffix (hence "toybox-armv5l").
The "help" command provides information about each command (ala "help cat").
--- Configuring toybox
It works like the Linux kernel: allnoconfig, defconfig, and menuconfig edit
a ".config" file that selects which features to include in the resulting
The maximum sane configuration is "make defconfig": allyesconfig isn't
recommended for toybox because it enables unfinished commands and debug code.
--- Creating a Toybox-based Linux system
Toybox is not a complete operating system, it's a program that runs under
an operating system. Booting a simple system to a shell prompt requires
three packages: an operating system kernel (Linux) to drive the hardware,
a program for the system to run (toybox), and a C library to tie them
together (toybox has been tested with musl, uClibc, glibc, and bionic).
The C library is part of a "toolchain", which is an integrated suite
of compiler, assembler, and linker, plus the standard headers and libraries
necessary to build C programs.
Static linking (with the --static option) copies the shared library contents
into the program, resulting in larger but more portable programs, which
can run even if they're the only file in the filesystem. Otherwise,
the "dynamically" linked programs require the library files to be present on
the target system ("man ldd" and "man" for details).
An example toybox-based system is Aboriginal Linux:
That's designed to run under qemu, emulating several different hardware
architectures (x86, x86-64, arm, mips, sparc, powerpc, sh4). Each toybox
release is regression tested by building Linux From Scratch under this
toybox-based system on each supported architecture, using QEMU to emulate
big and little endian systems with different word size and alignment
--- Presentations
1) "Why Toybox?" 2013 talk here at CELF
linked from in nav bar on left as "Why is it?"
- march 21, 2013 entry has section links.
2) "Why Public Domain?" The rise and fall of copyleft, Ohio LinuxFest 2013
3) Why did I do Aboriginal Linux (which led me here)
260 slide presentation:
How and why to make android self-hosting:
4) What's new with toybox (ELC 2015 status update):