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/toybox/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. You can save and re-use your .config file, although may want to
  74 run "make oldconfig" to re-run the dependency resolver when migrating to
  75 new versions.
  76
  77 The maximum sane configuration is "make defconfig": allyesconfig isn't
  78 recommended for toybox because it enables unfinished commands and debug code.
  79
  80 --- Creating a Toybox-based Linux system
  81
  82 Toybox is not a complete operating system, it's a program that runs under
  83 an operating system. Booting a simple system to a shell prompt requires
  84 three packages: an operating system kernel (Linux*) to drive the hardware,
  85 one or more programs for the system to run (toybox), and a C library ("libc")
  86 to tie them together (toybox has been tested with musl, uClibc, glibc,
  87 and bionic).
  88
  89 The C library is part of a "toolchain", which is an integrated suite
  90 of compiler, assembler, and linker, plus the standard headers and libraries
  91 necessary to build C programs. (And miscellaneous binaries like nm and objdump.)
  92
  93 Static linking (with the --static option) copies the shared library contents
  94 into the program, resulting in larger but more portable programs, which
  95 can run even if they're the only file in the filesystem. Otherwise,
  96 the "dynamically" linked programs require the library files to be present on
  97 the target system ("man ldd" and "man ld.so" for details).
  98
  99 An example toybox-based system is Aboriginal Linux:
 100
 101   http://landley.net/aboriginal/about.html
 102
 103 That's designed to run under qemu, emulating several different hardware
 104 architectures (x86, x86-64, arm, mips, sparc, powerpc, sh4). Each toybox
 105 release is regression tested by building Linux From Scratch under this
 106 toybox-based system on each supported architecture, using QEMU to emulate
 107 big and little endian systems with different word size and alignment
 108 requirements. (The eventual goal is to replace Linux From Scratch with
 109 the Android Open Source Project.)
 110
 111 * Or something providing the same API such as FreeBSD's Linux emulation layer.
 112
 113 --- Presentations
 114
 115 1) "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
 122 2) "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
 127 3) 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
 135 4) 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
 142 The 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
 150 The maintainer prefers patches be sent to the mailing list. If you use git,
 151 the easy thing to do is:
 152
 153   git format-patch -1 $HASH
 154
 155 Then send a file attachment. The list holds messages from non-subscribers
 156 for moderation, but I usually get to them in a day or two.
 157
 158 Although I do accept pull requests on github, I download the patches and
 159 apply them with "git am" (which avoids gratuitous merge commits). Closing
 160 the pull request is then the submitter's responsibility.
 161
 162 If I haven't responded to your patch after one week, feel free to remind
 163 me of it.
 164
 165 Android's policy for toybox patches is that non-build patches should go
 166 upstream first (into vanilla toybox, with discussion on the toybox mailing
 167 list) and then be pulled into android's toybox repo from there. (They
 168 generally 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
 171 --- Code of conduct
 172
 173 We're using twitter's https://engineering.twitter.com/opensource/code-of-conduct
 174 except email rob@landley.net with complaints.
 175
 176 (Yes, I try to pay more attention to marginalized programmers, which somehow
 177 manages to include 51% of the population. If somebody has to be three times as
 178 good to get half the recognition, why WOULDN'T you adjust for that?)