/[gentoo]/xml/htdocs/doc/en/handbook/hb-install-stage.xml
Gentoo

Contents of /xml/htdocs/doc/en/handbook/hb-install-stage.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.11 - (show annotations) (download) (as text)
Mon Nov 3 16:06:07 2003 UTC (15 years, 1 month ago) by swift
Branch: MAIN
Changes since 1.10: +1 -1 lines
File MIME type: application/xml
Use O2 instead of O3

1 <!-- The content of this document is licensed under the CC-BY-SA license -->
2 <!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
3
4 <sections>
5 <section>
6 <title>Choosing the Right Stage</title>
7 <body>
8
9 <p>
10 When we asked you to choose for an installation medium (LiveCDs, existing
11 distribution etc.) we explained you what the pros and cons are. One of those was
12 choosing your stage: do you go for a full compilation (<e>stage1</e>), skip the
13 bootstrapping (<e>stage2</e>) or start from a precompiled stade (<e>stage3</e>)?
14 </p>
15
16 <p>
17 Depending on your installation medium, you can still make your choice. Others
18 will already have made the choice at the beginning of the installation. It is
19 now time to install your choice of stage. But first we'll configure Portage with
20 the compiler optimizations you want and feature support you need.
21 </p>
22
23 </body>
24 </section>
25 <section>
26 <title>Configuring the Compile Options</title>
27 <subsection>
28 <title>Introduction</title>
29 <body>
30
31 <p>
32 To optimize Gentoo, you can set a couple of variables which impact Portage
33 behaviour. All those variables can be set as environment variables (using
34 <c>export</c>) but that isn't permanent. To keep your settings, Portage provides
35 you with <path>/etc/make.conf</path>, a configuration file for Portage. It is
36 this file we will edit now.
37 </p>
38
39 <p>
40 Fire up your favorite editor (in this guide we use <c>nano</c>) so we can alter
41 the optimization variables we will discuss hereafter.
42 </p>
43
44 <pre caption="Opening /etc/make.conf">
45 # <i>nano -w /etc/make.conf</i>
46 </pre>
47
48 <p>
49 As you probably notice now, the <path>make.conf</path> file is structured in a
50 generic way: commented lines start with "#", other lines define variables using
51 the <c>VARIABLE="content"</c> syntax. Several of those variables are discussed
52 next.
53 </p>
54
55 </body>
56 </subsection>
57 <subsection>
58 <title>CHOST</title>
59 <body>
60
61 <warn>
62 Although it might be interesting for non-stage1 users, they should <e>not</e>
63 change the <c>CHOST</c> setting in <path>make.conf</path>. Doing so might render
64 their system unusable. Again: only change this variable if you use a
65 <e>stage1</e> installation.
66 </warn>
67
68 <p>
69 The <c>CHOST</c> variable defines what architecture <c>gcc</c> has to
70 compile programs for. The possibilities are:
71 </p>
72
73 <table>
74 <tr>
75 <th>Architecture</th>
76 <th>Subarchitecture</th>
77 <th>CHOST Setting</th>
78 </tr>
79 <tr>
80 <ti>x86</ti>
81 <ti>i386</ti>
82 <ti>i386-pc-linux-gnu</ti>
83 </tr>
84 <tr>
85 <ti>x86</ti>
86 <ti>i486</ti>
87 <ti>i486-pc-linux-gnu</ti>
88 </tr>
89 <tr>
90 <ti>x86</ti>
91 <ti>i586</ti>
92 <ti>i586-pc-linux-gnu</ti>
93 </tr>
94 <tr>
95 <ti>x86</ti>
96 <ti>i686 and above (incl. athlon)</ti>
97 <ti>i686-pc-linux-gnu</ti>
98 </tr>
99 <tr>
100 <ti>alpha</ti>
101 <ti></ti>
102 <ti>alpha-unknown-linux-gnu</ti>
103 </tr>
104 <tr>
105 <ti>ppc</ti>
106 <ti></ti>
107 <ti>powerpc-unknown-linux-gnu</ti>
108 </tr>
109 <tr>
110 <ti>sparc</ti>
111 <ti></ti>
112 <ti>sparc-unknown-linux-gnu</ti>
113 </tr>
114 <tr>
115 <ti>hppa</ti>
116 <ti></ti>
117 <ti></ti>
118 </tr>
119 </table>
120
121 </body>
122 </subsection>
123 <subsection>
124 <title>CFLAGS and CXXFLAGS</title>
125 <body>
126
127 <p>
128 The <c>CFLAGS</c> and <c>CXXFLAGS</c> variables define the optimization flags
129 for the <c>gcc</c> C and C++ compiler respectively. Although we define those
130 generally here, you will only have maximum performance if you optimize these
131 flags for each program seperately. The reason for this is because every program
132 is different.
133 </p>
134
135 <p>
136 In <path>make.conf</path> you should define the optimization flags you think
137 will make your system the most responsive <e>generally</e>. Don't place
138 experimental settings in this variable; too much optimization can make
139 programs behave bad (crash, or even worse, malfunction).
140 </p>
141
142 <p>
143 We will not explain all possible optimization options. If you want to know
144 them all, read the <uri link="http://www.gnu.org/software/gcc/onlinedocs/">GNU
145 Online Manual(s)</uri> or the <c>gcc</c> info page (<c>info gcc</c> -- only
146 works on a working Linux system).
147 </p>
148
149 <p>
150 A first setting is the <c>-march=</c> flag, which specifies the name of the
151 target architecture. Possible options are described in the
152 <path>make.conf</path> file (as comments). For instance, for the x86 Athlon XP
153 architecture:
154 </p>
155
156 <pre caption="The GCC march setting">
157 -march=athlon-xp
158 </pre>
159
160 <p>
161 A second one is the <c>-O</c> flag, which specifies the <c>gcc</c> optimization
162 class flag. Possible classes are <c>s</c> (for size-optimized),
163 <c>0</c> (for no optimizations), <c>1</c>, <c>2</c> or <c>3</c> for more
164 speed-optimization flags (every class has the same flags as the one before, plus
165 some extras). For instance, for a class-2 optimization:
166 </p>
167
168 <pre caption="The GCC O setting">
169 -O2
170 </pre>
171
172 <p>
173 Other popular optimization flags are <c>-pipe</c> (use pipes rather than
174 temporary files for communication between the various stages of compilation) and
175 <c>-fomit-frame-pointer</c> (which doesn't keep the frame pointer in a register
176 for functions that don't need one).
177 </p>
178
179 <p>
180 When you define the <c>CFLAGS</c> and <c>CXXFLAGS</c>, you should combine
181 several optimization flags, like in the following example:
182 </p>
183
184 <pre caption="Defining the CFLAGS and CXXFLAGS variable">
185 CFLAGS="-march=athlon-xp -pipe -O2"
186 CXXFLAGS="${CFLAGS}" <comment># Use the same settings for both variables</comment>
187 </pre>
188
189 </body>
190 </subsection>
191 <subsection>
192 <title>USE</title>
193 <body>
194
195 <p>
196 <c>USE</c> is one of the most powerfull variables Gentoo provides to its users.
197 Several programs can be compiled with or without optional support for certain
198 items. For instance, some programs can be compiled with gtk-support, or with
199 qt-support. Others can be compiled with or without SSL support. Some programs
200 can even be compiled with framebuffer support (svgalib) instead of X11 support
201 (X-server).
202 </p>
203
204 <p>
205 Most distributions compile their packages with support for as much as possible,
206 increasing the size of the programs and startup time, not to mention an enormous
207 amount of dependencies. With Gentoo you can define with what options a package
208 should be compiled with. This is where <c>USE</c> comes into play.
209 </p>
210
211 <p>
212 In the <c>USE</c> variable you define keywords which are mapped onto
213 compile-options. For instance, <e>ssl</e> will compile ssl-support in the
214 programs that support it. <e>-X</e> will remove X-server support (note the minus
215 sign in front). <e>gnome gtk -kde -qt</e> will compile your programs with gnome
216 (and gtk) support, and not with kde (and qt) support, making your system fully
217 tweaked for GNOME.
218 </p>
219
220 <p>
221 The default <c>USE</c> settings are placed in
222 <path>/etc/make.profile/make.defaults</path>. What you place in
223 <path>/etc/make.conf</path> is calculated against these defaults settings. If
224 you add something to the <c>USE</c> setting, it is added to the default list. If
225 you remove something from the <c>USE</c> setting (by placing a minus sign in
226 front of it) it is removed from the default list (if it was in the default list
227 at all). <e>Never</e> alter anything inside the <path>/etc/make.profile</path>
228 directory; it gets overwritten when you update Portage!
229 </p>
230
231 <p>
232 A full description on <c>USE</c> can be found in our <uri
233 link="/doc/en/use-howto.xml">USE Howto</uri>. As an example
234 we show a <c>USE</c> setting for a KDE-based system with DVD, ALSA and CD
235 Recording support:
236 </p>
237
238 <pre caption="USE setting">
239 USE="-gtk -gnome qt kde dvd alsa cdr"
240 </pre>
241
242 </body>
243 </subsection>
244 <subsection>
245 <title>ACCEPT_KEYWORDS</title>
246 <body>
247
248 <p>
249 Ebuilds (the package format Gentoo uses) are located in one out of three stadia.
250 The first one is called <e>ARCH</e>, meaning that the ebuild and its
251 dependencies are thought to be stable and ready for general acceptance. Most
252 people want this. If you want your system to use packages from <e>ARCH</e>, then
253 <c>ACCEPT_KEYWORDS</c> should contain your architecture (being <c>x86</c>,
254 <c>alpha</c>, <c>ppc</c>, <c>sparc</c> or <c>hppa</c>):
255 </p>
256
257 <pre caption="Setting ACCEPT_KEYWORDS for the x86 architecture in ARCH">
258 ACCEPT_KEYWORDS="x86"
259 </pre>
260
261 <p>
262 When an ebuild enters Portage, is first goes to <e>~ARCH</e>, meaning that the
263 developer who committed the ebuild sais it works on his box(es), but that the
264 package needs more testing before it is moved to <e>ARCH</e>. If you want your
265 system to use packages from <e>~ARCH</e>, then <c>ACCEPT_KEYWORDS</c> should
266 contain your architecture, prefixed by a tilde (<e>~</e>). <e>Don't</e> think
267 this is the equivalent of "testing" or "unstable" in other distributions.
268 Packages inside <e>~ARCH</e> <e>do</e> occasionally break stuff! Some
269 architectures don't even bootstrap succesfully if you use <e>~ARCH</e> (notably
270 SPARC).
271 </p>
272
273 <pre caption="Setting ACCEPT_KEYWORDS for the x86 architecture in ~ARCH">
274 ACCEPT_KEYWORDS="~x86"
275 </pre>
276
277 <p>
278 If you want to use packages that are known to break your system, then you have
279 dance with the devil and uncomment the packages in
280 <path>/usr/portage/profiles/package.mask</path>. However, and this is a big fat
281 warning:
282 </p>
283
284 <warn>
285 Fiddling with <path>package.mask</path> is bad for your system, health and sense
286 of humor. Do <e>not</e> touch it unless you drive a tank, wear a teflon vest
287 24h/7 and love to sit and wait until Gentoo is reinstalled again... and again...
288 and again...
289 </warn>
290
291 </body>
292 </subsection>
293 <subsection>
294 <title>MAKEOPTS</title>
295 <body>
296
297 <p>
298 With <c>MAKEOPTS</c> you define how many parallel compilations should occur when
299 you install a package. The suggested number is the number of CPUs in your system
300 plus one.
301 </p>
302
303 <pre caption="MAKEOPTS for a regular, 1-CPU system">
304 MAKEOPTS="-j2"
305 </pre>
306
307 </body>
308 </subsection>
309 <subsection>
310 <title>Ready, Set, Go!</title>
311 <body>
312
313 <p>
314 Update your <path>/etc/make.conf</path> to your own will and save. You are now
315 ready to install the stage you prefer onto your system.
316 </p>
317
318 <p>
319 The following two parts explain how to install your preferred stage. The default
320 option here is to download your stage of choice from the internet. However, some
321 LiveCDs have these stages available on the CD.
322 </p>
323
324 <p>
325 If you have a working Internet connection, you are advised to use the default
326 option. If however you do not have a working Internet connection, or you want to
327 install Gentoo using GRP (precompiled packages), then you have to choose for the
328 alternative option.
329 </p>
330
331 <ul>
332 <li><uri link="#doc_chap3">Default: Downloading from the Internet</uri></li>
333 <li><uri link="#doc_chap4">Alternative: Using a Stage from the LiveCD</uri></li>
334 </ul>
335
336 </body>
337 </subsection>
338 </section>
339 <section>
340 <title>Default: Downloading from the Internet</title>
341 <subsection>
342 <title>Downloading the Stage Tarball</title>
343 <body>
344
345 <p>
346 Go to the Gentoo mountpoint at which you mounted your filesystems
347 (most likely <path>/mnt/gentoo</path>):
348 </p>
349
350 <pre caption="Going to the Gentoo mountpoint">
351 # <i>cd /mnt/gentoo</i>
352 </pre>
353
354 <p>
355 Depending on your installation medium, you have a couple of tools available to
356 download a stage. If you have <c>lynx</c> available, then you can immediately
357 surf to <uri link="/main/en/mirrors.xml">the Gentoo
358 mirrorlist</uri> and choose a mirror close to you. Then pick the
359 <path>releases/</path> directory, followed by your architecture (for instance
360 <path>x86/</path> and the Gentoo version (<path>1.4/</path>) to finish up with
361 the <path>stages/</path> directory. For there on you should see all available
362 stage files for your architecture. Select one and press <c>D</c> to download.
363 When you're finished, press <c>Q</c> to quit the browser.
364 </p>
365
366 <pre caption="Surfing to the mirror listing with lynx">
367 # <i>lynx http://www.gentoo.org/main/en/mirrors.xml</i>
368 </pre>
369
370 <p>
371 If you do not have <c>lynx</c>, you should have <c>links2</c> at your disposal.
372 <c>links2</c> is more powerfull than <c>lynx</c>, but has some drawbacks. One of
373 them is that it doesn't listen to the proxy variables we have declared
374 previously. If you need to setup a proxy, use <c>links2 -http-proxy
375 proxy.server.com:8080</c>. From there on, you should follow the same steps as
376 with <c>lynx</c> as they are equivalent.
377 </p>
378
379 <pre caption="Surfing to the mirror listing with links2">
380 <comment>(Without proxy:)</comment> # <i>links2 http://www.gentoo.org/main/en/mirrors.xml</i>
381 <comment>(With proxy:)</comment> # <i>links2 -http-proxy proxy.server.com:8080 http://www.gentoo.org/main/en/mirrors.xml</i>
382 </pre>
383
384 </body>
385 </subsection>
386 <subsection>
387 <title>Unpacking the Stage Tarball</title>
388 <body>
389
390 <p>
391 Now unpack your downloaded stage onto your system. We use GNU's <c>tar</c> to
392 proceed as it is the easiest method:
393 </p>
394
395 <pre caption="Unpacking the stage">
396 # <i>tar xvjpf stage?-*.tar.bz2</i>
397 </pre>
398
399 <p>
400 Make sure that you use the same options (<c>xvjpf</c>). The <c>x</c> stands for
401 <e>Extract</e>, the <c>v</c> for <e>Verbose</e> (okay, yes, this is optional),
402 the <c>j</c> for <e>Decompress with bzip2</e>, the <c>p</c> for <e>Preserve
403 permissions</e> and the <c>f</c> to denote that we want to extract a file, not
404 standard input.
405 </p>
406
407 <p>
408 Done? Okay, you are now ready to proceed with the next section on <uri
409 link="?part=1&amp;chap=6">Installing the Gentoo Base System</uri>.
410 </p>
411
412 </body>
413 </subsection>
414 </section>
415 <section>
416 <title>Alternative: Using a Stage from the LiveCD</title>
417 <subsection>
418 <title>Extracting the Stage Tarball</title>
419 <body>
420
421 <p>
422 The stages on the CD reside in the <path>/mnt/cdrom/stages</path> directory. To
423 see a listing of available stages, use <c>ls</c>:
424 </p>
425
426 <pre caption="List all available stages">
427 # <i>ls /mnt/cdrom/stages</i>
428 </pre>
429
430 <p>
431 If the system replies with an error, you may need to mount the CD-ROM first:
432 </p>
433
434 <pre caption="Mounting the CD-ROM">
435 # <i>ls /mnt/cdrom/stages</i>
436 ls: /mnt/cdrom/stages: No such file or directory
437 # <i>mount /dev/cdroms/cdrom0 /mnt/cdrom</i>
438 # <i>ls /mnt/cdrom/stages</i>
439 </pre>
440
441 <p>
442 Now go into your Gentoo mountpoint (usually <path>/mnt/gentoo</path>):
443 </p>
444
445 <pre caption="Changing directory to /mnt/gentoo">
446 # <i>cd /mnt/gentoo</i>
447 </pre>
448
449 <p>
450 We will now extract the stage tarball of your choice. We will do this with the
451 GNU <c>tar</c> tool. Make sure you use the same options (<c>xvjpf</c>)! In the
452 next example, we extract the stage tarball <path>stage3-20031011.tar.bz2</path>.
453 Be sure to substitute the tarball filename with your stage.
454 </p>
455
456 <pre caption="Extracting the stage tarball">
457 # <i>tar xvjpf /mnt/cdrom/stages/stage3-20031011.tar.bz2</i>
458 </pre>
459
460 </body>
461 </subsection>
462 <subsection>
463 <title>Installing a Portage Snapshot and Source Code</title>
464 <body>
465
466 <p>
467 There is a Portage snapshot available on some LiveCDs. Since you are reading
468 this, we can safely assume you are using such a LiveCD. To install this
469 snapshot, take a look inside <path>/mnt/cdrom/snapshots/</path> to see what
470 snapshots we have available:
471 </p>
472
473 <pre caption="Checking the /mnt/cdrom/snapshots content">
474 # <i>ls /mnt/cdrom/snapshots</i>
475 </pre>
476
477 <p>
478 Now extract the snapshot of your choice using the following construct. Again,
479 make sure you use the correct options to <c>tar</c>. Also, the <c>-C</c> is with
480 a capital <c>C</c>, not <c>c</c>. In the next example we use
481 <path>portage-20031011.tar.bz2</path> as the snapshot filename. Be sure to
482 substitute with your snapshot.
483 </p>
484
485 <pre caption="Extracting a Portage snapshot">
486 # <i>tar xvjf /mnt/cdrom/snapshots/portage-20031011.tar.bz2 -C /mnt/gentoo/usr</i>
487 </pre>
488
489 <p>
490 You also need to copy over all source code from the CD.
491 </p>
492
493 <pre caption="Copy over source code">
494 # <i>cp -R /mnt/cdrom/distfiles /mnt/gentoo/usr/portage/distfiles</i>
495 </pre>
496
497 <p>
498 If you want to use GRP (precompiled binaries), read on. Otherwise continue with
499 <uri link="?part=1&amp;chap=6">Installing the Gentoo Base System</uri>.
500 </p>
501
502 </body>
503 </subsection>
504 <subsection>
505 <title>Optional: Preparing GRP</title>
506 <body>
507
508 <p>
509 If you want to install Gentoo using GRP (precompiled packages), you need to copy
510 over all packages onto your filesystem so that Portage can use them.
511 </p>
512
513 <pre caption="Copy over precompiled packages">
514 # <i>cp -a /mnt/cdrom/packages /mnt/gentoo/usr/portage/packages</i>
515 </pre>
516
517 <p>
518 Now continue with <uri link="?part=1&amp;chap=6">Installing the Gentoo Base
519 System</uri>.
520 </p>
521
522 </body>
523 </subsection>
524 </section>
525 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20