/[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.16 - (show annotations) (download) (as text)
Mon Nov 17 17:32:42 2003 UTC (14 years, 6 months ago) by swift
Branch: MAIN
Changes since 1.15: +2 -2 lines
File MIME type: application/xml
Fix typo

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

  ViewVC Help
Powered by ViewVC 1.1.20