Mercurial > hg > toybox
annotate README @ 1068:7ada6da9540a draft 0.4.6
Ah, that's why commit 1057 was skipped last pull: it was unfinished. Oops. (Fix it.)
author | Rob Landley <rob@landley.net> |
---|---|
date | Wed, 11 Sep 2013 12:09:53 -0500 |
parents | 5dcfb58916a7 |
children | 9ccb7c975a5e |
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 |