annotate README @ 1028:5897a868313e

Jean-Christophe Dubois pointed out that if build.sh doesn't source config, it doesn't get things like NO_NATIVE_COMPILER.
author Rob Landley <rob@landley.net>
date Mon, 05 Apr 2010 18:39:09 -0500
parents bd2ea96aac53
children d98aa02a7edf
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
663
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
1 This is a brief intro, see http://impactlinux.com/fwl/documentation.html for
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
2 full documentation.
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
3
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
4 --- What is it?
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
5
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
6 Firmware Linux (FWL) is a build system that creates cross compilers and
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
7 bootable system images for various targets, such as arm, mips, powerpc, and
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
8 x86.
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
9
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
10 --- How do I use it?
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
11
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
12 List available targets:
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
13
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
14 ./build.sh
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
15
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
16 Build the mipsel (mips little endian) target:
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
17
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
18 ./build.sh mipsel
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
19
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
20 Boot the result under qemu, right out of the build directory:
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
21
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
22 ./run-from-build.sh mipsel
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
23
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
24 After the kernel boot messages scroll by, you should have a shell prompt
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
25 inside qemu. Try "cat /proc/cpuinfo" to confirm it's not the same as your
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
26 host. Type "exit" to shut it down.
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
27
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
28 Finally, look at the output in the "build" directory.
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
29
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
30 ls -l build/*.tar.bz2
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
31
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
32 For each target you built, the build tars up the cross compiler, the
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
33 root filesystem, and a bootable system image. Each system image contains an
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
34 ext2 formatted virtual hard drive image, a kernel configured for qemu, and a
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
35 run-emulator.sh shell script to invoke qemu in various ways.
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
36
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
37 If you'd like to use the cross compiler to build something else, just add
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
38 its "bin" subdirectory to the $PATH, and use the build tools prefixed with
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
39 the target name:
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
40
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
41 PATH=$(pwd)/build/cross-compiler-mipsel/bin:$PATH
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
42 mipsel-gcc -static hello.c -o hello
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
43 qemu-mipsel hello
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
44
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
45 Note that the run-emulator.sh script has several command line options:
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
46
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
47 cd build/system-image-mipsel
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
48 ./run-emulator.sh --help
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
49
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
50 If you'd like to build every target in parallel (needs about 2 gigs of ram):
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
51
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
52 ./buildall.sh --fork
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
53
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
54 The file "configure" contains several environment variables you can set to
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
55 control the behavior of FWL. (If this file doesn't set them, you can set
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
56 them in your environment before running a build.)
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
57
698
9e2a020195d3 Mention how to do "make clean" and "make distclean" equivalents.
Rob Landley <rob@landley.net>
parents: 663
diff changeset
58 The equivalent of "make clean" is "rm -rf build". The equivalent of
9e2a020195d3 Mention how to do "make clean" and "make distclean" equivalents.
Rob Landley <rob@landley.net>
parents: 663
diff changeset
59 "make distclean" is "rm -rf build packages".
9e2a020195d3 Mention how to do "make clean" and "make distclean" equivalents.
Rob Landley <rob@landley.net>
parents: 663
diff changeset
60
663
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
61 --- What's it for?
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
62
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
63 Although Firmware Linux creates reusable cross compilers, the purpose of FWL
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
64 is actually to eliminate the need for cross compiling.
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
65
711
20ba34b54140 Rename mini-native.sh to root-filesystem.sh, since that's what it builds.
Rob Landley <rob@landley.net>
parents: 698
diff changeset
66 The FWL build does all the cross compiling necessary to create a root
20ba34b54140 Rename mini-native.sh to root-filesystem.sh, since that's what it builds.
Rob Landley <rob@landley.net>
parents: 698
diff changeset
67 filesystem for a target containing a minimal native development environment,
20ba34b54140 Rename mini-native.sh to root-filesystem.sh, since that's what it builds.
Rob Landley <rob@landley.net>
parents: 698
diff changeset
68 then packages it into a system image. Once that target system is up and
20ba34b54140 Rename mini-native.sh to root-filesystem.sh, since that's what it builds.
Rob Landley <rob@landley.net>
parents: 698
diff changeset
69 running (usually under qemu), you can build your software natively in there,
20ba34b54140 Rename mini-native.sh to root-filesystem.sh, since that's what it builds.
Rob Landley <rob@landley.net>
parents: 698
diff changeset
70 and no longer need to cross compile anything from the host.
663
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
71
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
72 FWL is also designed to be readable. The build is a series of bash scripts,
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
73 with comments where necessary. They document how to make a cross compiler,
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
74 how to create a simple development environment, and how to package and boot
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
75 the result under an emulator. If you don't know how something works, read
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
76 the script. If something's unclear, ask us.
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
77
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
78 --- How does it work?
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
79
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
80 The build.sh script is a wrapper around other scripts. The main three are:
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
81
966
bd2ea96aac53 Update READMEs.
Rob Landley <rob@landley.net>
parents: 711
diff changeset
82 simple-cross-compiler.sh - create a cross compiler for the target.
663
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
83
711
20ba34b54140 Rename mini-native.sh to root-filesystem.sh, since that's what it builds.
Rob Landley <rob@landley.net>
parents: 698
diff changeset
84 root-filesystem.sh - use the cross compiler to build a root filesystem.
663
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
85
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
86 system-image.sh - build a kernel and ext2 image to run under emulator.
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
87
966
bd2ea96aac53 Update READMEs.
Rob Landley <rob@landley.net>
parents: 711
diff changeset
88 An optional (but often useful) fourth script is:
bd2ea96aac53 Update READMEs.
Rob Landley <rob@landley.net>
parents: 711
diff changeset
89
bd2ea96aac53 Update READMEs.
Rob Landley <rob@landley.net>
parents: 711
diff changeset
90 native-compiler.sh - create a more complicated compiler for the target,
bd2ea96aac53 Update READMEs.
Rob Landley <rob@landley.net>
parents: 711
diff changeset
91 statically linked against uClibc and with thread
bd2ea96aac53 Update READMEs.
Rob Landley <rob@landley.net>
parents: 711
diff changeset
92 support and uClibc++. (This can optionally be used
bd2ea96aac53 Update READMEs.
Rob Landley <rob@landley.net>
parents: 711
diff changeset
93 to create a better cross compiler, via canadian cross.)
663
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
94
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
95 This file is a brief introduction, for full documentation see
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
96
e1f187868dc4 Add a README file.
Rob Landley <rob@landley.net>
parents:
diff changeset
97 http://impactlinux.com/fwl/documentation.html