1 |
From: "W. Trevor King" <wking@×××××××.us> |
2 |
|
3 |
--- |
4 |
doc/HOWTO.txt | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
5 |
1 file changed, 204 insertions(+) |
6 |
create mode 100644 doc/HOWTO.txt |
7 |
|
8 |
diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt |
9 |
new file mode 100644 |
10 |
index 0000000..ea9c8f4 |
11 |
--- /dev/null |
12 |
+++ b/doc/HOWTO.txt |
13 |
@@ -0,0 +1,204 @@ |
14 |
+Catalyst is a release-buildcing tool for Gentoo. If you use Gentoo |
15 |
+and want to roll your own live CD or bootable USB stick, this is the |
16 |
+way to go. First, get a Gentoo development box and install the |
17 |
+necessary tools: |
18 |
+ |
19 |
+ # emerge -av dev-util/catalyst |
20 |
+ |
21 |
+Configure catalyst by editing `/etc/catalyst/catalyst.conf`, which is |
22 |
+well commented. This sets up defaults such as hashing algorithms and |
23 |
+storage directories. The defaults will probably be fine unless disk |
24 |
+space is an issue. |
25 |
+ |
26 |
+Assembling a starting point |
27 |
+--------------------------- |
28 |
+ |
29 |
+Portage snapshot |
30 |
+~~~~~~~~~~~~~~~~ |
31 |
+ |
32 |
+Create a snapshot of your current Portage tree (you may want to |
33 |
+`emerge --sync` first): |
34 |
+ |
35 |
+ # catalyst --snapshot 20130131 |
36 |
+ # ls /var/tmp/catalyst/snapshots/ |
37 |
+ portage-20130131.tar.bz2 |
38 |
+ portage-20130131.tar.bz2.CONTENTS |
39 |
+ portage-20130131.tar.bz2.DIGESTS |
40 |
+ |
41 |
+where the storage location is relative to the default |
42 |
+`$storedir=/var/tmp/catalyst`. |
43 |
+ |
44 |
+Stage3 tarball |
45 |
+~~~~~~~~~~~~~~ |
46 |
+ |
47 |
+Get a stage3 tarball (containing the build tools you'll need to |
48 |
+construct your stage1) from your local |
49 |
+http://www.gentoo.org/main/en/mirrors.xml[Gentoo mirror]. |
50 |
+ |
51 |
+ $GENTOO_MIRROR/releases/$ARCH/current-stage3/ |
52 |
+ |
53 |
+For example, |
54 |
+ |
55 |
+ http://distfiles.gentoo.org/releases/amd64/current-stage3/stage3-amd64-20121213.tar.bz2 |
56 |
+ |
57 |
+Grab the tarball and put it where catalyst will find it: |
58 |
+ |
59 |
+ # wget http://…/stage3-amd64-20121213.tar.bz2 |
60 |
+ # wget http://…/stage3-amd64-20121213.tar.bz2.CONTENTS |
61 |
+ # wget http://…/stage3-amd64-20121213.tar.bz2.DIGESTS.asc |
62 |
+ # sha512sum -c stage3-amd64-20121213.tar.bz2.DIGESTS.asc |
63 |
+ # gpg --verify stage3-amd64-20121213.tar.bz2.DIGESTS.asc |
64 |
+ # mv stage3-amd64-20121213.tar.bz2* /var/tmp/catalyst/builds/default/ |
65 |
+ |
66 |
+where the storage dir is `$storedir/builds/$source_subpath` |
67 |
+(`$storedir` from `catalyst.conf`, `$source_subpath` from your |
68 |
+`*.spec` file). |
69 |
+ |
70 |
+`.*spec` files |
71 |
+~~~~~~~~~~~~~~ |
72 |
+ |
73 |
+`.*spec` files tell catalyst about the system you're trying to build. |
74 |
+There are a number of examples distributed with catalyst. Look in |
75 |
+`/usr/share/doc/catalyst-*/examples/`. A minimal `*.spec` file for |
76 |
+this example is: |
77 |
+ |
78 |
+ # cat default-stage1-amd64-2013.1.spec |
79 |
+ subarch: amd64 |
80 |
+ version_stamp: 2013.1 |
81 |
+ target: stage1 |
82 |
+ rel_type: default |
83 |
+ profile: default/linux/amd64/10.0/no-multilib |
84 |
+ snapshot: 20130131 |
85 |
+ source_subpath: default/stage3-amd64-20121213 |
86 |
+ |
87 |
+You may need to adjust the `subarch`, `snapshot`, and `source_subpath` |
88 |
+fields of the `*.spec` to match your target host, Portage snapshot, |
89 |
+and stage3 tarball name respectively. |
90 |
+ |
91 |
+For more details on what can go into a `*.spec` file, see |
92 |
+`catalyst-spec(5)`. |
93 |
+ |
94 |
+Building stage1 |
95 |
+--------------- |
96 |
+ |
97 |
+Now that everything's setup, run catalyst: |
98 |
+ |
99 |
+ # catalyst -f default-stage1-amd64-2013.1.spec |
100 |
+ |
101 |
+which will build the target and install something like: |
102 |
+ |
103 |
+ # ls /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.* |
104 |
+ /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2 |
105 |
+ /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2.CONTENTS |
106 |
+ /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2.DIGESTS |
107 |
+ |
108 |
+The name is an expansion of |
109 |
+`$storedir/builds/$rel_type/$target-$subarch-$version_stamp…`. |
110 |
+ |
111 |
+Building stage2 and stage3 |
112 |
+-------------------------- |
113 |
+ |
114 |
+Once you've built the stage1 from your seed stage3, you can use that |
115 |
+stage1 to build a stage2 and stage3. The `*.spec` files are similar: |
116 |
+ |
117 |
+ $ diff -u default-stage{1,2}-amd64-2013.1.spec |
118 |
+ --- default-stage1-amd64-2013.1.spec |
119 |
+ +++ default-stage2-amd64-2013.1.spec |
120 |
+ @@ -1,7 +1,7 @@ |
121 |
+ subarch: amd64 |
122 |
+ version_stamp: 2013.1 |
123 |
+ -target: stage1 |
124 |
+ +target: stage2 |
125 |
+ rel_type: default |
126 |
+ profile: default/linux/amd64/10.0/no-multilib |
127 |
+ snapshot: 20130131 |
128 |
+ -source_subpath: default/stage3-amd64-20121213 |
129 |
+ +source_subpath: default/stage1-amd64-2013.1 |
130 |
+ $ diff default-stage{2,3}-amd64-2013.1.spec |
131 |
+ --- default-stage2-amd64-2013.1.spec |
132 |
+ +++ default-stage3-amd64-2013.1.spec |
133 |
+ @@ -1,7 +1,7 @@ |
134 |
+ subarch: amd64 |
135 |
+ version_stamp: 2013.1 |
136 |
+ -target: stage2 |
137 |
+ +target: stage3 |
138 |
+ rel_type: default |
139 |
+ profile: default/linux/amd64/10.0/no-multilib |
140 |
+ snapshot: 20130131 |
141 |
+ -source_subpath: default/stage1-amd64-2013.1 |
142 |
+ +source_subpath: default/stage2-amd64-2013.1 |
143 |
+ |
144 |
+Gentoo stages |
145 |
+------------- |
146 |
+ |
147 |
+You can't compile a big pile of source code without an already |
148 |
+compiled toolchain, which is where Gentoo's stages come in. The “base |
149 |
+system” contains the necessary build tools and supporting |
150 |
+infrastructure to get things going. The stages are: |
151 |
+ |
152 |
+1. System must be bootstrapped and the base system must be compiled |
153 |
+ (a new toolchain built with external seed tools). |
154 |
+2. Stage1 + bootstrapped (a new toolchain build with stage1 tools). |
155 |
+3. Stage2 + base system compiled (the base system built with stage2 tools). |
156 |
+4. Stage3 + non-base packages. |
157 |
+ |
158 |
+For more details on the differences between the stages, look at the |
159 |
+target helper scripts (e.g. `targets/stage1/*.sh`). |
160 |
+ |
161 |
+Building with a kernel |
162 |
+---------------------- |
163 |
+ |
164 |
+If you're shooting for a live CD or bootable USB stick, you'll need to |
165 |
+compile your own kernel. Here's how that works. |
166 |
+ |
167 |
+Genkernel |
168 |
+~~~~~~~~~ |
169 |
+ |
170 |
+When you don't know exactly which kernel options you need, add |
171 |
+something like the following to your `*.spec`: |
172 |
+ |
173 |
+ boot/kernel: gentoo |
174 |
+ boot/kernel/gentoo/sources: gentoo-sources |
175 |
+ |
176 |
+You can still set `boot/kernel/<label>/config` when you're using |
177 |
+genkernel if you want to give genkernel some hints. |
178 |
+ |
179 |
+Genkernel alternatives |
180 |
+~~~~~~~~~~~~~~~~~~~~~~ |
181 |
+ |
182 |
+If you don't want to use a genkernel, your options are fairly limited. |
183 |
+The currently suggested route is to create your own binary kernel |
184 |
+package. |
185 |
+ |
186 |
+Stage4 |
187 |
+------ |
188 |
+ |
189 |
+`examples/stage4_template.spec` is a good template for building a |
190 |
+stage4 tarball. Besides setting `target: stage4` and adjusting |
191 |
+`source_subpath`, I usually use `stage4/packages`, `stage4/rcadd`, and |
192 |
+the `boot/kernel` stuff described above. This gives an almost |
193 |
+bootable stage that you can dump on a USB flash drive. |
194 |
+ |
195 |
+Live CDs |
196 |
+-------- |
197 |
+ |
198 |
+Live CDs should be built in two stages: `livecd-stage1` (based on a |
199 |
+stage3 source) for building extra packages (along the same lines as a |
200 |
+stage4) and `livecd-stage2` (based on `livecd-stage1`) for setting up |
201 |
+the kernel, bootloader, filesystem, and other details. See |
202 |
+`examples/livecd-stage*_template.spec` for some ideas. |
203 |
+ |
204 |
+Live USBs |
205 |
+--------- |
206 |
+ |
207 |
+The easiest way to create a live USB is currently to install a live CD |
208 |
+ISO using |
209 |
+http://www.syslinux.org/wiki/index.php/Doc/isolinux#HYBRID_CD-ROM.2FHARD_DISK_MODE[isohybrid] |
210 |
+and `dd`: |
211 |
+ |
212 |
+ # isohybrid filename.iso |
213 |
+ # dd if=filename.iso of=/dev/sdX |
214 |
+ |
215 |
+replacing `X` with the appropriate drive letter for your USB disk. |
216 |
+See https://bugs.gentoo.org/show_bug.cgi?id=251719[bug 251719] for |
217 |
+details. |
218 |
-- |
219 |
1.8.1.336.g94702dd |