From 0b87b2e71324a20bdb7839ac95742d6208d5c321 Mon Sep 17 00:00:00 2001 From: Rob Landley Date: Tue, 7 May 2013 22:50:33 -0500 Subject: Another stab at recapitulating phylogeny in a README file. --- README | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 75 insertions(+), 14 deletions(-) (limited to 'README') diff --git a/README b/README index 4526b1b0..4fc2472c 100644 --- a/README +++ b/README @@ -1,30 +1,91 @@ Toybox: all-in-one Linux command line. ---- Building Toybox +--- Getting started + +You can download static binaries for various targets from: + + http://landley.net/toybox/bin + +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: + + wget http://landley.net/bin/toybox-x86_64 + chmod +x toybox-x86_64 + ./toybox-x86_64 echo hello world + +--- Building toybox Type "make help" for build instructions. -Mostly you want: +Usually you want something like: + + make defconfig + CFLAGS="--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: + + http;//landley.net/aboriginal/bin + +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.) - CFLAGS="--static" CROSS_COMPILE=armv5l- make defconfig toybox install +For more about cross compiling, see: -Or "make menuconfig", which produces the same sort of .config file as the -Linux kernel. + http://landley.net/writing/docs/cross-compiling.html + http://landley.net/aboriginal/architectures.html --- Using toybox -The build produces a "swiss-army-knife" style multifunction binary, which acts -differently depending on the name it was called as (cp, mv, cat...), and -installs symlinks under each command name to populate $PATH. +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 "toybox" command itself uses its first argument as the command name to run -(ala "toybox ls -l"). With no arguments, it lists available commands. (This -allows you to use the commands even without the symlinks.) +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"). -The toybox web page is at "http://landley.net/toybox". +--- 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 +binary. + +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, and glibc, on Android +systems musl is recommended).

+ +

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. Dynamically linked programs (the default) +Otherwise, the +"dynamically" linked programs require the +library to be present on the target system ("man ldd" and "man ld.so" for +details) statically linked programs do not.

+ +Toybox is not a kernel, it needs Linux to drive the hardware. -Have fun, +An example toybox-based system is Aboriginal Linux: -Rob + http://landley.net/aboriginal -- cgit v1.2.3