toybox/README
<<
>>
Prefs
   1Toybox: all-in-one Linux command line.
   2
   3--- Getting started
   4
   5You can download static binaries for various targets from:
   6
   7  http://landley.net/toybox/bin
   8
   9The special name "." indicates the current directory (just like ".." means
  10the parent directory), and you can run a program that isn't in the $PATH by
  11specifying a path to it, so this should work:
  12
  13  wget http://landley.net/toybox/bin/toybox-x86_64
  14  chmod +x toybox-x86_64
  15  ./toybox-x86_64 echo hello world
  16
  17--- Building toybox
  18
  19Type "make help" for build instructions.
  20
  21Toybox uses the "make menuconfig; make; make install" idiom same as
  22the Linux kernel. Usually you want something like:
  23
  24  make defconfig
  25  make
  26  make install
  27
  28Or maybe:
  29
  30  LDFLAGS="--static" CROSS_COMPILE=armv5l- make defconfig toybox
  31  PREFIX=/path/to/root/filesystem/bin make install_flat
  32
  33The file "configure" defines default values for many environment
  34variables that control the toybox build; if you set a value for any of
  35these, your value is used instead of the default in that file.
  36
  37The CROSS_COMPILE argument above is optional, the default builds a version of
  38toybox to run on the current machine. Cross compiling requires an appropriately
  39prefixed cross compiler toolchain, several example toolchains are available at:
  40
  41  http://landley.net/aboriginal/bin
  42
  43For the "CROSS_COMPILE=armv5l-" example above, download
  44cross-compiler-armv5l.tar.bz2, extract it, and add its "bin" subdirectory to
  45your $PATH. (And yes, the trailing - is significant, because the prefix
  46includes a dash.)
  47
  48For more about cross compiling, see:
  49
  50  http://landley.net/writing/docs/cross-compiling.html
  51  http://landley.net/aboriginal/architectures.html
  52
  53For a more thorough description of the toybox build process, see
  54http://landley.net/toybox/code.html#building
  55
  56--- Using toybox
  57
  58The toybox build produces a multicall binary, a "swiss-army-knife" program
  59that acts differently depending on the name it was called by (cp, mv, cat...).
  60Installing toybox adds symlinks for each command name to the $PATH.
  61
  62The special "toybox" command treats its first argument as the command to run.
  63With no arguments, it lists available commands. This allows you to use toybox
  64without installing it. This is the only command that can have an arbitrary
  65suffix (hence "toybox-armv5l").
  66
  67The "help" command provides information about each command (ala "help cat").
  68
  69--- Configuring toybox
  70
  71It works like the Linux kernel: allnoconfig, defconfig, and menuconfig edit
  72a ".config" file that selects which features to include in the resulting
  73binary. You can save and re-use your .config file, although may want to
  74run "make oldconfig" to re-run the dependency resolver when migrating to
  75new versions.
  76
  77The maximum sane configuration is "make defconfig": allyesconfig isn't
  78recommended for toybox because it enables unfinished commands and debug code.
  79
  80--- Creating a Toybox-based Linux system
  81
  82Toybox is not a complete operating system, it's a program that runs under
  83an operating system. Booting a simple system to a shell prompt requires
  84three packages: an operating system kernel (Linux*) to drive the hardware,
  85one or more programs for the system to run (toybox), and a C library ("libc")
  86to tie them together (toybox has been tested with musl, uClibc, glibc,
  87and bionic).
  88
  89The C library is part of a "toolchain", which is an integrated suite
  90of compiler, assembler, and linker, plus the standard headers and libraries
  91necessary to build C programs. (And miscellaneous binaries like nm and objdump.)
  92
  93Static linking (with the --static option) copies the shared library contents
  94into the program, resulting in larger but more portable programs, which
  95can run even if they're the only file in the filesystem. Otherwise,
  96the "dynamically" linked programs require the library files to be present on
  97the target system ("man ldd" and "man ld.so" for details).
  98
  99An example toybox-based system is Aboriginal Linux:
 100
 101  http://landley.net/aboriginal/about.html
 102
 103That's designed to run under qemu, emulating several different hardware
 104architectures (x86, x86-64, arm, mips, sparc, powerpc, sh4). Each toybox
 105release is regression tested by building Linux From Scratch under this
 106toybox-based system on each supported architecture, using QEMU to emulate
 107big and little endian systems with different word size and alignment
 108requirements. (The eventual goal is to replace Linux From Scratch with
 109the Android Open Source Project.)
 110
 111* Or something providing the same API such as FreeBSD's Linux emulation layer.
 112
 113--- Presentations
 114
 1151) "Why Toybox?" talk at the Embedded Linux Conference in 2013
 116
 117    video: http://youtu.be/SGmtP5Lg_t0
 118    outline: http://landley.net/talks/celf-2013.txt
 119    linked from http://landley.net/toybox/ in nav bar on left as "Why is it?"
 120    - march 21, 2013 entry has section links.
 121
 1222) "Why Public Domain?" The rise and fall of copyleft, Ohio LinuxFest 2013
 123
 124    audio: https://archive.org/download/OhioLinuxfest2013/24-Rob_Landley-The_Rise_and_Fall_of_Copyleft.mp3
 125    outline: http://landley.net/talks/ohio-2013.txt
 126
 1273) Why did I do Aboriginal Linux (which led me here)
 128
 129    260 slide presentation:
 130    https://speakerdeck.com/landley/developing-for-non-x86-targets-using-qemu
 131
 132    How and why to make android self-hosting:
 133      http://landley.net/aboriginal/about.html#selfhost
 134
 1354) What's new with toybox (ELC 2015 status update):
 136
 137    video: http://elinux.org/ELC_2015_Presentations
 138    outline: http://landley.net/talks/celf-2015.txt
 139
 140--- Contributing
 141
 142The three important URLs for communicating with the toybox project are:
 143
 144  web page: http://landley.net/toybox
 145
 146  mailing list: http://lists.landley.net/listinfo.cgi/toybox-landley.net
 147
 148  git repo: http://github.com/landley/toybox
 149
 150The maintainer prefers patches be sent to the mailing list. If you use git,
 151the easy thing to do is:
 152
 153  git format-patch -1 $HASH
 154
 155Then send a file attachment. The list holds messages from non-subscribers
 156for moderation, but I usually get to them in a day or two.
 157
 158Although I do accept pull requests on github, I download the patches and
 159apply them with "git am" (which avoids gratuitous merge commits). Closing
 160the pull request is then the submitter's responsibility.
 161
 162If I haven't responded to your patch after one week, feel free to remind
 163me of it.
 164
 165Android's policy for toybox patches is that non-build patches should go
 166upstream first (into vanilla toybox, with discussion on the toybox mailing
 167list) and then be pulled into android's toybox repo from there. (They
 168generally resync on fridays). The exception is patches to their build scripts
 169(Android.mk and the checked-in generated/* files) which go directly to AOSP.
 170