annotate README @ 1525:95cb37adb024 draft

Factor out printf-style escape parsing logic from echo.c.
author Rob Landley <rob@landley.net>
date Sat, 18 Oct 2014 17:14:12 -0500
parents fee58d039b72
children
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
1356
fee58d039b72 The readme, a text file, has an HTML close paragraph tag.
Rob Landley <rob@landley.net>
parents: 1176
diff changeset
72 systems musl is recommended).
429
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
73
1176
9ccb7c975a5e The README trailed off into unfinished confusion at the end, fix up the obvious parts.
Rob Landley <rob@landley.net>
parents: 894
diff changeset
74 The C library is part of a "toolchain", which is an integrated suite
894
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
1176
9ccb7c975a5e The README trailed off into unfinished confusion at the end, fix up the obvious parts.
Rob Landley <rob@landley.net>
parents: 894
diff changeset
76 necessary to build C programs.
429
27104029d771 Add a basic README and an example to "make help".
Rob Landley <rob@landley.net>
parents:
diff changeset
77
1176
9ccb7c975a5e The README trailed off into unfinished confusion at the end, fix up the obvious parts.
Rob Landley <rob@landley.net>
parents: 894
diff changeset
78 Static linking (with the --static option) copies the shared library contents
9ccb7c975a5e The README trailed off into unfinished confusion at the end, fix up the obvious parts.
Rob Landley <rob@landley.net>
parents: 894
diff changeset
79 into the program, resulting in larger but more portable programs, which
9ccb7c975a5e The README trailed off into unfinished confusion at the end, fix up the obvious parts.
Rob Landley <rob@landley.net>
parents: 894
diff changeset
80 can run even if they'rr the only file in the filesystem. Otherwise,
9ccb7c975a5e The README trailed off into unfinished confusion at the end, fix up the obvious parts.
Rob Landley <rob@landley.net>
parents: 894
diff changeset
81 the "dynamically" linked programs require the library files to be present on
9ccb7c975a5e The README trailed off into unfinished confusion at the end, fix up the obvious parts.
Rob Landley <rob@landley.net>
parents: 894
diff changeset
82 the target system ("man ldd" and "man ld.so" for details).
894
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
83
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
84 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
85
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
86 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
87
5dcfb58916a7 Another stab at recapitulating phylogeny in a README file.
Rob Landley <rob@landley.net>
parents: 429
diff changeset
88 http://landley.net/aboriginal