annotate README @ 918:eea4c1b35959

Move stat from pending to other, default y.
author Rob Landley <rob@landley.net>
date Sun, 02 Jun 2013 00:54:55 -0500
parents 5dcfb58916a7
children 9ccb7c975a5e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
429
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
1 Toybox: all-in-one Linux command line.
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
2
894
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
3 --- Getting started
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
4
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
5 You can download static binaries for various targets from:
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
6
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
7 http://landley.net/toybox/bin
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
8
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
9 The special name "." indicates the current directory (just like ".." means
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
10 the parent directory), and you can run a program that isn't in the $PATH by
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
11 specifying a path to it, so this should work:
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
12
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
13 wget http://landley.net/bin/toybox-x86_64
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
14 chmod +x toybox-x86_64
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
15 ./toybox-x86_64 echo hello world
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
16
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
17 --- Building toybox
429
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
18
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
19 Type "make help" for build instructions.
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
20
894
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
21 Usually you want something like:
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
22
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
23 make defconfig
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
24 CFLAGS="--static" CROSS_COMPILE=armv5l- make toybox
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
25 PREFIX=/path/to/root/filesystem make install
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
26
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
27 The CROSS_COMPILE argument is optional, and without it builds a version of
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
28 toybox to run on the current machine. Cross compiling requires an appropriately
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
29 prefixed cross compiler toolchain, several example toolchains are available at:
429
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
30
894
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
31 http;//landley.net/aboriginal/bin
429
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
32
894
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
33 For the "CROSS_COMPILE=armv5l-" example above, download
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
34 cross-compiler-armv5l.tar.bz2, extract it, and add its "bin" subdirectory to
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
35 your $PATH. (And yes, the trailing - is significant, because the prefix
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
36 includes a dash.)
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
37
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
38 For more about cross compiling, see:
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
39
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
40 http://landley.net/writing/docs/cross-compiling.html
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
41 http://landley.net/aboriginal/architectures.html
429
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
42
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
43 --- Using toybox
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
44
894
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
45 The toybox build produces a multicall binary, a "swiss-army-knife" program
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
46 that acts differently depending on the name it was called by (cp, mv, cat...).
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
47 Installing toybox adds symlinks for each command name to the $PATH.
429
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
48
894
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
49 The special "toybox" command treats its first argument as the command to run.
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
50 With no arguments, it lists available commands. This allows you to use toybox
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
51 without installing it. This is the only command that can have an arbitrary
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
52 suffix (hence "toybox-armv5l").
429
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
53
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
54 The "help" command provides information about each command (ala "help cat").
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
55
894
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
56 --- Configuring toybox
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
57
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
58 It works like the Linux kernel: allnoconfig, defconfig, and menuconfig edit
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
59 a ".config" file that selects which features to include in the resulting
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
60 binary.
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
61
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
62 The maximum sane configuration is "make defconfig": allyesconfig isn't
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
63 recommended for toybox because it enables unfinished commands and debug code.
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
64
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
65 --- Creating a Toybox-based Linux system
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
66
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
67 Toybox is not a complete operating system, it's a program that runs under
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
68 an operating system. Booting a simple system to a shell prompt requires
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
69 three packages: an operating system kernel (Linux) to drive the hardware,
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
70 a program for the system to run (toybox), and a C library to tie them
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
71 together (toybox has been tested with musl, uClibc, and glibc, on Android
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
72 systems musl is recommended).</p>
429
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
73
894
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
74 <p>The C library is part of a "toolchain", which is an integrated suite
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
75 of compiler, assembler, and linker, plus the standard headers and libraries
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
76 necessary to build C programs.</p>
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
77
429
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
78
894
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
79 Static linking (with the --static option)
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
80 copies the shared library contents into the program, resulting in
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
81 larger but more portable programs. Dynamically linked programs (the default)
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
82 Otherwise, the
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
83 "dynamically" linked programs require the
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
84 library to be present on the target system ("man ldd" and "man ld.so" for
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
85 details) statically linked programs do not.</p>
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
86
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
87 Toybox is not a kernel, it needs Linux to drive the hardware.
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
88
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
89 An example toybox-based system is Aboriginal Linux:
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
90
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
91 http://landley.net/aboriginal