Mercurial > hg > toybox
annotate README @ 1667:aa6487c2c5f8 draft
fix typo in printf
author | Elliott Hughes <enh@google.com> |
---|---|
date | Tue, 20 Jan 2015 15:52:41 -0600 |
parents | fee58d039b72 |
children |
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 |