/[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.13 - (show annotations) (download) (as text)
Tue Nov 11 15:00:49 2003 UTC (14 years, 9 months ago) by swift
Branch: MAIN
Changes since 1.12: +14 -3 lines
File MIME type: application/xml
Update for HPPA plus some small updates

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

  ViewVC Help
Powered by ViewVC 1.1.20