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 variables
  34that control the toybox build; if you export any of these variables into your
  35environment, 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 (built using
  40the file "scripts/mcm-buildall.sh" in the toybox source) are available at:
  41
  42  https://mkroot.musl.cc/latest/
  43
  44For the "CROSS_COMPILE=armv5l-" example above, download
  45cross-compiler-armv5l.tar.bz2, extract it, and add its "bin" subdirectory to
  46your $PATH. (And yes, the trailing - is significant, because the prefix
  47includes a dash.)
  48
  49For more about cross compiling, see:
  50
  51  https://landley.net/toybox/faq.html#cross
  52  http://landley.net/writing/docs/cross-compiling.html
  53  http://landley.net/aboriginal/architectures.html
  54
  55For a more thorough description of the toybox build process, see:
  56
  57  http://landley.net/toybox/code.html#building
  58
  59--- Using toybox
  60
  61The toybox build produces a multicall binary, a "swiss-army-knife" program
  62that acts differently depending on the name it was called by (cp, mv, cat...).
  63Installing toybox adds symlinks for each command name to the $PATH.
  64
  65The special "toybox" command treats its first argument as the command to run.
  66With no arguments, it lists available commands. This allows you to use toybox
  67without installing it, and is the only command that can have an arbitrary
  68suffix (hence "toybox-armv5l").
  69
  70The "help" command provides information about each command (ala "help cat"),
  71and "help toybox" provides general information about toybox.
  72
  73--- Configuring toybox
  74
  75It works like the Linux kernel: allnoconfig, defconfig, and menuconfig edit
  76a ".config" file that selects which features to include in the resulting
  77binary. You can save and re-use your .config file, but may want to
  78run "make oldconfig" to re-run the dependency resolver when migrating to
  79new versions.
  80
  81The maximum sane configuration is "make defconfig": allyesconfig isn't
  82recommended as a starting point for toybox because it enables unfinished
  83commands, debug code, and optional dependencies your build environment may
  84not provide.
  85
  86--- Creating a Toybox-based Linux system
  87
  88Toybox has a built-in simple system builder (scripts/mkroot.sh) with a
  89Makefile target:
  90
  91  make root
  92  sudo chroot root/host/fs /init
  93
  94Type "exit" to get back out. If you install appropriate cross compilers and
  95point it at Linux source code, it can build simple three-package systems
  96that boot to a shell prompt under qemu:
  97
  98  make root CROSS_COMPILE=sh4-linux-musl- LINUX=~/linux
  99  cd root/sh4
 100  ./qemu-sh4.sh
 101
 102By calling scripts/mkroot.sh directly you can add additional packages
 103to the build, see scripts/root/dropbear as an example.
 104
 105The FAQ explains this in a lot more detail:
 106
 107  https://landley.net/toybox/faq.html#system
 108  https://landley.net/toybox/faq.html#mkroot
 109
 110--- Presentations
 111
 1121) "Why Toybox?" talk at the Embedded Linux Conference in 2013
 113
 114    outline: http://landley.net/talks/celf-2013.txt
 115    video: http://youtu.be/SGmtP5Lg_t0
 116
 117    The https://landley.net/toybox/about.html page has nav links breaking that
 118    talk down into sections.
 119
 1202) "Why Public Domain?" The rise and fall of copyleft, Ohio LinuxFest 2013
 121
 122    outline: http://landley.net/talks/ohio-2013.txt
 123    audio: https://archive.org/download/OhioLinuxfest2013/24-Rob_Landley-The_Rise_and_Fall_of_Copyleft.mp3
 124
 1253) Why did I do Aboriginal Linux (which led me here)
 126
 127    260 slide presentation:
 128      https://speakerdeck.com/landley/developing-for-non-x86-targets-using-qemu
 129
 130    How and why to make android self-hosting:
 131      http://landley.net/aboriginal/about.html#selfhost
 132
 133    More backstory than strictly necessary:
 134      https://landley.net/aboriginal/history.html
 135
 1364) What's new with toybox (ELC 2015 status update):
 137
 138    video: http://elinux.org/ELC_2015_Presentations
 139    outline: http://landley.net/talks/celf-2015.txt
 140
 1415) Toybox vs BusyBox (2019 ELC talk):
 142
 143    outline: http://landley.net/talks/elc-2019.txt
 144    video: https://www.youtube.com/watch?v=MkJkyMuBm3g
 145
 146--- Contributing
 147
 148The three important URLs for communicating with the toybox project are:
 149
 150  web page: http://landley.net/toybox
 151
 152  mailing list: http://lists.landley.net/listinfo.cgi/toybox-landley.net
 153
 154  git repo: http://github.com/landley/toybox
 155
 156The maintainer prefers patches be sent to the mailing list. If you use git,
 157the easy thing to do is:
 158
 159  git format-patch -1 $HASH
 160
 161Then send a file attachment. The list holds messages from non-subscribers
 162for moderation, but I usually get to them in a day or two.
 163
 164I download github pull requests as patches and apply them with "git am"
 165(which avoids gratuitous merge commits). Sometimes I even remember to close
 166the pull request.
 167
 168If I haven't responded to your patch after one week, feel free to remind
 169me of it.
 170
 171Android's policy for toybox patches is that non-build patches should go
 172upstream first (into vanilla toybox, with discussion on the toybox mailing
 173list) and then be pulled into android's toybox repo from there. (They
 174generally resync on fridays). The exception is patches to their build scripts
 175(Android.mk and the checked-in generated/* files) which go directly to AOSP.
 176
 177(As for the other meaning of "contributing", https://patreon.com/landley is
 178always welcome but I warn you up front I'm terrible about updating it.)
 179