Name Date Size

..27-Apr.-20224 KiB

.github/workflows/H06-Jan.-20224 KiB

.gitignoreH A D06-Jan.-2022114

Config.inH A D12-Apr.-20225.8 KiB

configureH A D01-Jul.-2022926

kconfig/H20-Jun.-20224 KiB

lib/H30-Jun.-20224 KiB

LICENSEH A D06-Jan.-2022666

main.cH A D01-Apr.-20228.6 KiB

MakefileH A D04-Apr.-20222.1 KiB

READMEH A D06-Jan.-20226.2 KiB

scripts/HToday4 KiB

tests/H30-Jun.-20224 KiB

toys/H06-Jan.-20224 KiB

toys.hH A D06-May-20223.6 KiB

www/H23-May-20224 KiB

README

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