/[gentoo]/xml/htdocs/doc/en/draft/bootstrapping-guide.xml
Gentoo

Contents of /xml/htdocs/doc/en/draft/bootstrapping-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.2 - (show annotations) (download) (as text)
Wed Nov 30 05:14:15 2005 UTC (9 years ago) by swift
Branch: MAIN
Changes since 1.1: +76 -1 lines
File MIME type: application/xml
The simple part...

1 <?xml version='1.0' encoding="UTF-8"?>
2
3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bootstrapping-guide.xml,v 1.1 2005/11/26 16:23:25 swift Exp $ -->
4
5 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
6
7 <guide link="/doc/en/draft/bootstrapping-guide.xml">
8 <title>Gentoo Bootstrapping Guide</title>
9
10 <author title="Author">
11 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
12 </author>
13
14 <abstract>
15 Bootstrapping means to build a toolchain so that it is ready to build the rest
16 of your system. Gentoo is a perfect operating system to perform such
17 installation while retaining support from the software management system,
18 Portage.
19 </abstract>
20
21 <!-- The content of this document is licensed under the CC-BY-SA license -->
22 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
23 <license/>
24
25 <version>0.1</version>
26 <date>2005-07-25</date>
27
28 <chapter>
29 <title>What is Bootstrapping?</title>
30 <section>
31 <title>Definition</title>
32 <body>
33
34 <warn>
35 Not only is this guide still in its early stage, it is also built on theoretical
36 information found on the Internet and not from experience. It should be taken
37 with a big grain of salt until the steps in it are verified and accepted by more
38 experienced people.
39 </warn>
40
41 <p>
42 If we were to believe the stories, <e>bootstrapping</e> - the term - originates
43 from a German legend about Baron M√ľnchhausen who was able to save himself from
44 drowning in a swamp by pulling himself up by his hairs.
45 </p>
46
47 <p>
48 In computer theory, bootstrapping has several meanings. All of them boil down to
49 building more complex systems from simple ones. This document will discuss
50 bootstrapping a toolchain: building a full cross-compilation environment able to
51 build software for the target system.
52 </p>
53
54 </body>
55 </section>
56 <section>
57 <title>Toolchain Bootstrapping</title>
58 <body>
59
60 <p>
61 The process of bootstrapping a toolchain is two-fold.
62 </p>
63
64 <p>
65 At first, you use an existing toolchain to create a cross-compilation
66 environment, a toolchain capable of running on one system but building software
67 for a different one. The second step is to use the cross-compilation toolchain
68 to rebuild itself so that it builds code native to the system it is booted on.
69 </p>
70
71 <p>
72 There are three important terms we use in this definition:
73 </p>
74
75 <ul>
76 <li>the <e>host</e> system is the system on which the programs are ran, </li>
77 <li>
78 the <e>build</e> system is the system on which a particular package is being
79 built, and
80 </li>
81 <li>
82 the <e>target</e> system is the system for which the software generates
83 output (like the compiler)
84 </li>
85 </ul>
86
87 <p>
88 After the toolchain is bootstrapped, the third stage is to build the rest of the
89 system using the native toolchain.
90 </p>
91
92 </body>
93 </section>
94 </chapter>
95
96 <chapter>
97 <title>Installing Gentoo on an Unsupported Platform</title>
98 <section>
99 <title>Creating the Cross-Compilation Environment</title>
100 <body>
101
102 </body>
103 </section>
104 <section>
105 <title>Filling the Environment</title>
106 <body>
107
108 </body>
109 </section>
110 <section>
111 <title>Bootstrapping the Toolchain</title>
112 <body>
113
114 </body>
115 </section>
116 <section>
117 <title>Building the Core System Packages</title>
118 <body>
119
120 </body>
121 </section>
122 <section>
123 <title>Porting Portage</title>
124 <body>
125
126 </body>
127 </section>
128 <section>
129 <title>Creating a Stage1 Tarball</title>
130 <body>
131
132 </body>
133 </section>
134 <section>
135 <title>Creating a Bootable Environment</title>
136 <body>
137
138 </body>
139 </section>
140 <section>
141 <title>Finishing Off</title>
142 <body>
143
144 </body>
145 </section>
146 </chapter>
147
148 <chapter>
149 <title>Bootstrapping the System</title>
150 <section>
151 <title>Installing Gentoo</title>
152 <body>
153
154 <p>
155 With the bootable environment at your disposal, you can now boot the target
156 system into a small Linux environment. Once booted, follow the installation
157 instructions inside the <uri link="/doc/en/handbook">Gentoo Handbook</uri> to
158 the point where you chroot into your Gentoo environment. Of course, since you
159 only have a stage1 tarball at your disposal, you should use that one instead of
160 the stage3 used in the installation instructions.
161 </p>
162
163 <p>
164 After chrooting the system, you should update the Portage tree.
165 </p>
166
167 <pre caption="Updating the Portage tree">
168 # <i>emerge --sync</i>
169 </pre>
170
171 </body>
172 </section>
173 <section>
174 <title>Using the Bootstrap Script</title>
175 <body>
176
177 <p>
178 Next, we'll rebuild the toolchain provided by the stage1 tarball natively.
179 Gentoo provides a script that does this for you.
180 </p>
181
182 <pre caption="Rebuilding the toolchain">
183 # <i>/usr/portage/scripts/bootstrap.sh</i>
184 </pre>
185
186 </body>
187 </section>
188 <section>
189 <title>Building the Core System</title>
190 <body>
191
192 <p>
193 With the toolchain rebuild and ready for general usage, we'll build the core
194 system packages for the system:
195 </p>
196
197 <pre caption="Building the core system packages">
198 # <i>emerge --emptytree system</i>
199 </pre>
200
201 </body>
202 </section>
203 <section>
204 <title>Finishing the Installation</title>
205 <body>
206
207 <p>
208 Now that the core system packages are built, you can continue using the
209 installation instructions in the Gentoo Handbook. You will probably get a few
210 complaints by Portage telling you certain packages are masked. This is because
211 your architecture isn't supported by Gentoo yet, in which case you need to
212 unmask the packages in <path>/etc/portage/package.keywords</path> like you did
213 previously.
214 </p>
215
216 </body>
217 </section>
218 </chapter>
219
220 <chapter>
221 <title>Frequently Asked Questions</title>
222 <section>
223 <title>
224 Should I bootstrap when I want my entire system to use changed CFLAGS,
225 CXXFLAGS, USE settings and profile changes?
226 </title>
227 <body>
228
229 <p>
230 No. After your changes, you should rebuild the toolchain first, after which you
231 can rebuild the entire system using the new toolchain. When your system suffers
232 from circular dependencies, you'll need to rebuild the participants in that
233 circle. For instance, if <c>openssl</c> depends on <c>python</c> which depends
234 on <c>perl</c> which depends on <c>openssl</c> again (yes, this is a fictuous
235 example), rebuild all those packages too.
236 </p>
237
238 <pre caption="Rebuilding the system">
239 # <i>emerge --oneshot --emptytree glibc binutils glibc</i>
240 # <i>emerge --emptytree world</i>
241 </pre>
242
243 <p>
244 You don't need to bootstrap here because your architecture still remains the
245 same, as is the target system.
246 </p>
247
248 </body>
249 </section>
250 <section>
251 <title>
252 Should I bootstrap when I want my entire system to use changed CHOST settings?
253 </title>
254 <body>
255
256 <p>
257 Not if the system itself supports the new CHOST setting too (for instance,
258 i386-pc-linux-gnu and i686-pc-linux-gnu on a Pentium IV system). Otherwise, yes,
259 but then we are really interested in hearing how you managed to install Gentoo
260 using the current - wrong - CHOST settings in the first place ;)
261 </p>
262
263 <p>
264 If your system supports both CHOST settings, you can follow the same
265 instructions as given in the previous FAQ.
266 </p>
267
268 </body>
269 </section>
270 </chapter>
271
272 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20