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 (a] 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?) 179
