README

   1 Toybox: all-in-one Linux command line.
   2
   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
  18
  19 Type "make help" for build instructions.
  20
  21 Usually you want something like:
  22
  23   make defconfig
  24   LDFLAGS="--static" CROSS_COMPILE=armv5l- make toybox
  25   PREFIX=/path/to/root/filesystem make install
  26
  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
  42
  43 --- Using toybox
  44
  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.
  48
  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").
  53
  54 The "help" command provides information about each command (ala "help cat").
  55
  56 --- Configuring toybox
  57
  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.
  61
  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, glibc, and bionic).
  72
  73 The C library is part of a "toolchain", which is an integrated suite
  74 of compiler, assembler, and linker, plus the standard headers and libraries
  75 necessary to build C programs.
  76
  77 Static linking (with the --static option) copies the shared library contents
  78 into the program, resulting in larger but more portable programs, which
  79 can run even if they're the only file in the filesystem. Otherwise,
  80 the "dynamically" linked programs require the library files to be present on
  81 the target system ("man ldd" and "man ld.so" for details).
  82
  83 An example toybox-based system is Aboriginal Linux:
  84
  85   http://landley.net/aboriginal/about.html
  86
  87 That's designed to run under qemu, emulating several different hardware
  88 architectures (x86, x86-64, arm, mips, sparc, powerpc, sh4). Each toybox
  89 release is regression tested by building Linux From Scratch under this
  90 toybox-based system on each supported architecture, using QEMU to emulate
  91 big and little endian systems with different word size and alignment
  92 requirements.
  93
  94 --- Presentations
  95
  96 1) "Why Toybox?" 2013 talk here at CELF
  97
  98     video: http://youtu.be/SGmtP5Lg_t0
  99     outline: http://landley.net/talks/celf-2013.txt
 100     linked from http://landley.net/toybox/ in nav bar on left as "Why is it?"
 101     - march 21, 2013 entry has section links.
 102
 103 2) "Why Public Domain?" The rise and fall of copyleft, Ohio LinuxFest 2013
 104
 105     audio: https://archive.org/download/OhioLinuxfest2013/24-Rob_Landley-The_Rise_and_Fall_of_Copyleft.mp3
 106     outline: http://landley.net/talks/ohio-2013.txt
 107
 108 3) Why did I do Aboriginal Linux (which led me here)
 109
 110     260 slide presentation:
 111     https://speakerdeck.com/landley/developing-for-non-x86-targets-using-qemu
 112
 113     How and why to make android self-hosting:
 114       http://landley.net/aboriginal/about.html#selfhost
 115
 116 4) What's new with toybox (ELC 2015 status update):
 117
 118     video: http://elinux.org/ELC_2015_Presentations
 119     outline: http://landley.net/talks/celf-2015.txt