/[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.12 - (show annotations) (download) (as text)
Tue Nov 4 17:50:28 2003 UTC (15 years ago) by swift
Branch: MAIN
Changes since 1.11: +208 -209 lines
File MIME type: application/xml
Fix some minor twitches, plus a wrong sequence

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></ti>
319 <ti></ti>
320 </tr>
321 </table>
322
323 </body>
324 </subsection>
325 <subsection>
326 <title>CFLAGS and CXXFLAGS</title>
327 <body>
328
329 <p>
330 The <c>CFLAGS</c> and <c>CXXFLAGS</c> variables define the optimization flags
331 for the <c>gcc</c> C and C++ compiler respectively. Although we define those
332 generally here, you will only have maximum performance if you optimize these
333 flags for each program seperately. The reason for this is because every program
334 is different.
335 </p>
336
337 <p>
338 In <path>make.conf</path> you should define the optimization flags you think
339 will make your system the most responsive <e>generally</e>. Don't place
340 experimental settings in this variable; too much optimization can make
341 programs behave bad (crash, or even worse, malfunction).
342 </p>
343
344 <p>
345 We will not explain all possible optimization options. If you want to know
346 them all, read the <uri link="http://www.gnu.org/software/gcc/onlinedocs/">GNU
347 Online Manual(s)</uri> or the <c>gcc</c> info page (<c>info gcc</c> -- only
348 works on a working Linux system).
349 </p>
350
351 <p>
352 A first setting is the <c>-march=</c> flag, which specifies the name of the
353 target architecture. Possible options are described in the
354 <path>make.conf</path> file (as comments). For instance, for the x86 Athlon XP
355 architecture:
356 </p>
357
358 <pre caption="The GCC march setting">
359 -march=athlon-xp
360 </pre>
361
362 <p>
363 A second one is the <c>-O</c> flag, which specifies the <c>gcc</c> optimization
364 class flag. Possible classes are <c>s</c> (for size-optimized),
365 <c>0</c> (for no optimizations), <c>1</c>, <c>2</c> or <c>3</c> for more
366 speed-optimization flags (every class has the same flags as the one before, plus
367 some extras). For instance, for a class-2 optimization:
368 </p>
369
370 <pre caption="The GCC O setting">
371 -O2
372 </pre>
373
374 <p>
375 Other popular optimization flags are <c>-pipe</c> (use pipes rather than
376 temporary files for communication between the various stages of compilation) and
377 <c>-fomit-frame-pointer</c> (which doesn't keep the frame pointer in a register
378 for functions that don't need one).
379 </p>
380
381 <p>
382 When you define the <c>CFLAGS</c> and <c>CXXFLAGS</c>, you should combine
383 several optimization flags, like in the following example:
384 </p>
385
386 <pre caption="Defining the CFLAGS and CXXFLAGS variable">
387 CFLAGS="-march=athlon-xp -pipe -O2"
388 CXXFLAGS="${CFLAGS}" <comment># Use the same settings for both variables</comment>
389 </pre>
390
391 </body>
392 </subsection>
393 <subsection>
394 <title>USE</title>
395 <body>
396
397 <p>
398 <c>USE</c> is one of the most powerfull variables Gentoo provides to its users.
399 Several programs can be compiled with or without optional support for certain
400 items. For instance, some programs can be compiled with gtk-support, or with
401 qt-support. Others can be compiled with or without SSL support. Some programs
402 can even be compiled with framebuffer support (svgalib) instead of X11 support
403 (X-server).
404 </p>
405
406 <p>
407 Most distributions compile their packages with support for as much as possible,
408 increasing the size of the programs and startup time, not to mention an enormous
409 amount of dependencies. With Gentoo you can define with what options a package
410 should be compiled with. This is where <c>USE</c> comes into play.
411 </p>
412
413 <p>
414 In the <c>USE</c> variable you define keywords which are mapped onto
415 compile-options. For instance, <e>ssl</e> will compile ssl-support in the
416 programs that support it. <e>-X</e> will remove X-server support (note the minus
417 sign in front). <e>gnome gtk -kde -qt</e> will compile your programs with gnome
418 (and gtk) support, and not with kde (and qt) support, making your system fully
419 tweaked for GNOME.
420 </p>
421
422 <p>
423 The default <c>USE</c> settings are placed in
424 <path>/etc/make.profile/make.defaults</path>. What you place in
425 <path>/etc/make.conf</path> is calculated against these defaults settings. If
426 you add something to the <c>USE</c> setting, it is added to the default list. If
427 you remove something from the <c>USE</c> setting (by placing a minus sign in
428 front of it) it is removed from the default list (if it was in the default list
429 at all). <e>Never</e> alter anything inside the <path>/etc/make.profile</path>
430 directory; it gets overwritten when you update Portage!
431 </p>
432
433 <p>
434 A full description on <c>USE</c> can be found in our <uri
435 link="/doc/en/use-howto.xml">USE Howto</uri>. As an example
436 we show a <c>USE</c> setting for a KDE-based system with DVD, ALSA and CD
437 Recording support:
438 </p>
439
440 <pre caption="USE setting">
441 USE="-gtk -gnome qt kde dvd alsa cdr"
442 </pre>
443
444 </body>
445 </subsection>
446 <subsection>
447 <title>ACCEPT_KEYWORDS</title>
448 <body>
449
450 <p>
451 Ebuilds (the package format Gentoo uses) are located in one out of three stadia.
452 The first one is called <e>ARCH</e>, meaning that the ebuild and its
453 dependencies are thought to be stable and ready for general acceptance. Most
454 people want this. If you want your system to use packages from <e>ARCH</e>, then
455 <c>ACCEPT_KEYWORDS</c> should contain your architecture (being <c>x86</c>,
456 <c>alpha</c>, <c>ppc</c>, <c>sparc</c> or <c>hppa</c>):
457 </p>
458
459 <pre caption="Setting ACCEPT_KEYWORDS for the x86 architecture in ARCH">
460 ACCEPT_KEYWORDS="x86"
461 </pre>
462
463 <p>
464 When an ebuild enters Portage, is first goes to <e>~ARCH</e>, meaning that the
465 developer who committed the ebuild sais it works on his box(es), but that the
466 package needs more testing before it is moved to <e>ARCH</e>. If you want your
467 system to use packages from <e>~ARCH</e>, then <c>ACCEPT_KEYWORDS</c> should
468 contain your architecture, prefixed by a tilde (<e>~</e>). <e>Don't</e> think
469 this is the equivalent of "testing" or "unstable" in other distributions.
470 Packages inside <e>~ARCH</e> <e>do</e> occasionally break stuff! Some
471 architectures don't even bootstrap succesfully if you use <e>~ARCH</e> (notably
472 SPARC).
473 </p>
474
475 <pre caption="Setting ACCEPT_KEYWORDS for the x86 architecture in ~ARCH">
476 ACCEPT_KEYWORDS="~x86"
477 </pre>
478
479 <p>
480 If you want to use packages that are known to break your system, then you have
481 dance with the devil and uncomment the packages in
482 <path>/usr/portage/profiles/package.mask</path>. However, and this is a big fat
483 warning:
484 </p>
485
486 <warn>
487 Fiddling with <path>package.mask</path> is bad for your system, health and sense
488 of humor. Do <e>not</e> touch it unless you drive a tank, wear a teflon vest
489 24h/7 and love to sit and wait until Gentoo is reinstalled again... and again...
490 and again...
491 </warn>
492
493 </body>
494 </subsection>
495 <subsection>
496 <title>MAKEOPTS</title>
497 <body>
498
499 <p>
500 With <c>MAKEOPTS</c> you define how many parallel compilations should occur when
501 you install a package. The suggested number is the number of CPUs in your system
502 plus one.
503 </p>
504
505 <pre caption="MAKEOPTS for a regular, 1-CPU system">
506 MAKEOPTS="-j2"
507 </pre>
508
509 </body>
510 </subsection>
511 <subsection>
512 <title>Ready, Set, Go!</title>
513 <body>
514
515 <p>
516 Update your <path>/mnt/gentoo/etc/make.conf</path> to your own will and save.
517 You are now ready to continue with <uri link="?part=1&amp;chap=6">Installing the
518 Gentoo Base System</uri>.
519 </p>
520
521 </body>
522 </subsection>
523 </section>
524 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20