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 Toybox uses the "make menuconfig; make; make install" idiom same as
  22 the Linux kernel. Usually you want something like:
  23
  24   make defconfig
  25   make
  26   make install
  27
  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
  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
  52
  53 For a more thorough description of the toybox build process, see
  54 http://landley.net/toybox/code.html#building
  55
  56 --- Using toybox
  57
  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.
  61
  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").
  66
  67 The "help" command provides information about each command (ala "help cat").
  68
  69 --- Configuring toybox
  70
  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
  73 binary.
  74
  75 The maximum sane configuration is "make defconfig": allyesconfig isn't
  76 recommended for toybox because it enables unfinished commands and debug code.
  77
  78 --- Creating a Toybox-based Linux system
  79
  80 Toybox is not a complete operating system, it's a program that runs under
  81 an operating system. Booting a simple system to a shell prompt requires
  82 three packages: an operating system kernel (Linux) to drive the hardware,
  83 a program for the system to run (toybox), and a C library to tie them
  84 together (toybox has been tested with musl, uClibc, glibc, and bionic).
  85
  86 The C library is part of a "toolchain", which is an integrated suite
  87 of compiler, assembler, and linker, plus the standard headers and libraries
  88 necessary to build C programs.
  89
  90 Static linking (with the --static option) copies the shared library contents
  91 into the program, resulting in larger but more portable programs, which
  92 can run even if they're the only file in the filesystem. Otherwise,
  93 the "dynamically" linked programs require the library files to be present on
  94 the target system ("man ldd" and "man ld.so" for details).
  95
  96 An example toybox-based system is Aboriginal Linux:
  97
  98   http://landley.net/aboriginal/about.html
  99
 100 That's designed to run under qemu, emulating several different hardware
 101 architectures (x86, x86-64, arm, mips, sparc, powerpc, sh4). Each toybox
 102 release is regression tested by building Linux From Scratch under this
 103 toybox-based system on each supported architecture, using QEMU to emulate
 104 big and little endian systems with different word size and alignment
 105 requirements.
 106
 107 --- Presentations
 108
 109 1) "Why Toybox?" 2013 talk here at CELF
 110
 111     video: http://youtu.be/SGmtP5Lg_t0
 112     outline: http://landley.net/talks/celf-2013.txt
 113     linked from http://landley.net/toybox/ in nav bar on left as "Why is it?"
 114     - march 21, 2013 entry has section links.
 115
 116 2) "Why Public Domain?" The rise and fall of copyleft, Ohio LinuxFest 2013
 117
 118     audio: https://archive.org/download/OhioLinuxfest2013/24-Rob_Landley-The_Rise_and_Fall_of_Copyleft.mp3
 119     outline: http://landley.net/talks/ohio-2013.txt
 120
 121 3) Why did I do Aboriginal Linux (which led me here)
 122
 123     260 slide presentation:
 124     https://speakerdeck.com/landley/developing-for-non-x86-targets-using-qemu
 125
 126     How and why to make android self-hosting:
 127       http://landley.net/aboriginal/about.html#selfhost
 128
 129 4) What's new with toybox (ELC 2015 status update):
 130
 131     video: http://elinux.org/ELC_2015_Presentations
 132     outline: http://landley.net/talks/celf-2015.txt