Home | History | Annotate | only in /external/toybox
Up to higher level directory
NameDateSize
.config21-Aug-20186.5K
Android.mk21-Aug-20189.8K
Config.in21-Aug-20185.3K
configure21-Aug-20181.2K
generated/21-Aug-2018
kconfig/21-Aug-2018
lib/21-Aug-2018
LICENSE21-Aug-2018820
main.c21-Aug-20187K
Makefile21-Aug-20181.7K
MODULE_LICENSE_BSD21-Aug-20180
NOTICE21-Aug-2018820
README21-Aug-20186.5K
run-tests-on-android.sh21-Aug-20181.3K
scripts/21-Aug-2018
tests/21-Aug-2018
toys/21-Aug-2018
toys.h21-Aug-20183.3K
www/21-Aug-2018

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