/[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 - (hide annotations) (download) (as text)
Wed Nov 30 05:14:15 2005 UTC (8 years, 7 months ago) by swift
Branch: MAIN
Changes since 1.1: +76 -1 lines
File MIME type: application/xml
The simple part...

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2    
3 swift 1.2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bootstrapping-guide.xml,v 1.1 2005/11/26 16:23:25 swift Exp $ -->
4 swift 1.1
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 swift 1.2 <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 swift 1.1 </body>
172     </section>
173     <section>
174     <title>Using the Bootstrap Script</title>
175     <body>
176    
177 swift 1.2 <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 swift 1.1 </body>
187     </section>
188     <section>
189     <title>Building the Core System</title>
190     <body>
191    
192 swift 1.2 <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 swift 1.1 </body>
202     </section>
203     <section>
204     <title>Finishing the Installation</title>
205     <body>
206    
207 swift 1.2 <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 swift 1.1 </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 swift 1.2 <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 swift 1.1 </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 swift 1.2 <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 swift 1.1 </body>
269     </section>
270     </chapter>
271    
272     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20