/[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.22 - (hide annotations) (download) (as text)
Thu Dec 18 07:00:17 2003 UTC (14 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.21: +8 -32 lines
File MIME type: application/xml
Fix #35525: Users should not set the ACCEPT_KEYWORDS before Gentoo is installed

1 swift 1.10 <!-- 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 swift 1.22 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-stage.xml,v 1.21 2003/12/17 17:05:59 swift Exp $ -->
5 swift 1.15
6 swift 1.7 <sections>
7 swift 1.1 <section>
8     <title>Choosing the Right Stage</title>
9     <body>
10    
11     <p>
12 swift 1.2 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 swift 1.16 bootstrapping (<e>stage2</e>) or start from a precompiled state (<e>stage3</e>)?
16 swift 1.2 </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 swift 1.12 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 swift 1.17 <li><uri link="#doc_chap2">Default: Downloading from the Internet</uri></li>
39     <li><uri link="#doc_chap3">Alternative: Using a Stage from the LiveCD</uri></li>
40 swift 1.12 </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 swift 1.19 <c>links2</c> is more powerful than <c>lynx</c>, but has some drawbacks. One of
78 swift 1.12 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 swift 1.19 # <i>tar -xvjpf stage?-*.tar.bz2</i>
102 swift 1.12 </pre>
103    
104     <p>
105 swift 1.19 Make sure that you use the same options (<c>-xvjpf</c>). The <c>x</c> stands for
106 swift 1.12 <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 swift 1.19 GNU <c>tar</c> tool. Make sure you use the same options (<c>-xvjpf</c>)! In the
157 swift 1.12 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 swift 1.19 # <i>tar -xvjpf /mnt/cdrom/stages/stage3-20031011.tar.bz2</i>
163 swift 1.12 </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 swift 1.19 snapshot we have available:
176 swift 1.12 </p>
177    
178     <pre caption="Checking the /mnt/cdrom/snapshots content">
179     # <i>ls /mnt/cdrom/snapshots</i>
180     </pre>
181    
182     <p>
183 swift 1.19 Now extract the snapshot using the following construct. Again,
184 swift 1.12 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 swift 1.19 # <i>tar -xvjf /mnt/cdrom/snapshots/portage-20031011.tar.bz2 -C /mnt/gentoo/usr</i>
192 swift 1.12 </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 swift 1.1 </p>
206    
207     </body>
208 swift 1.12 </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 swift 1.7 </section>
229     <section>
230     <title>Configuring the Compile Options</title>
231 swift 1.1 <subsection>
232 swift 1.3 <title>Introduction</title>
233 swift 1.1 <body>
234    
235     <p>
236 swift 1.3 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 swift 1.1 </p>
242    
243 swift 1.3 <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 swift 1.12 # <i>nano -w /mnt/gentoo/etc/make.conf</i>
250 swift 1.3 </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 swift 1.7 </subsection>
261     <subsection>
262 swift 1.3 <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 swift 1.4 their system unusable. Again: only change this variable if you use a
269     <e>stage1</e> installation.
270 swift 1.3 </warn>
271 swift 1.4
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 swift 1.13 <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 swift 1.4 </tr>
333 swift 1.21 <tr>
334     <ti>mips</ti>
335     <ti></ti>
336     <ti>mips-unknown-linux-gnu</ti>
337     </tr>
338 swift 1.4 </table>
339    
340     </body>
341 swift 1.7 </subsection>
342     <subsection>
343 swift 1.4 <title>CFLAGS and CXXFLAGS</title>
344     <body>
345    
346     <p>
347     The <c>CFLAGS</c> and <c>CXXFLAGS</c> variables define the optimization flags
348     for the <c>gcc</c> C and C++ compiler respectively. Although we define those
349     generally here, you will only have maximum performance if you optimize these
350 swift 1.18 flags for each program separately. The reason for this is because every program
351 swift 1.4 is different.
352     </p>
353    
354     <p>
355     In <path>make.conf</path> you should define the optimization flags you think
356     will make your system the most responsive <e>generally</e>. Don't place
357     experimental settings in this variable; too much optimization can make
358     programs behave bad (crash, or even worse, malfunction).
359     </p>
360    
361     <p>
362     We will not explain all possible optimization options. If you want to know
363     them all, read the <uri link="http://www.gnu.org/software/gcc/onlinedocs/">GNU
364     Online Manual(s)</uri> or the <c>gcc</c> info page (<c>info gcc</c> -- only
365 swift 1.13 works on a working Linux system). The <path>make.conf</path> file itself also
366     contains lots of examples and information; don't forget to read it too.
367 swift 1.4 </p>
368    
369     <p>
370     A first setting is the <c>-march=</c> flag, which specifies the name of the
371     target architecture. Possible options are described in the
372     <path>make.conf</path> file (as comments). For instance, for the x86 Athlon XP
373     architecture:
374     </p>
375    
376     <pre caption="The GCC march setting">
377     -march=athlon-xp
378     </pre>
379    
380     <p>
381     A second one is the <c>-O</c> flag, which specifies the <c>gcc</c> optimization
382 swift 1.6 class flag. Possible classes are <c>s</c> (for size-optimized),
383 swift 1.4 <c>0</c> (for no optimizations), <c>1</c>, <c>2</c> or <c>3</c> for more
384     speed-optimization flags (every class has the same flags as the one before, plus
385 swift 1.6 some extras). For instance, for a class-2 optimization:
386 swift 1.4 </p>
387    
388     <pre caption="The GCC O setting">
389     -O2
390     </pre>
391    
392     <p>
393     Other popular optimization flags are <c>-pipe</c> (use pipes rather than
394     temporary files for communication between the various stages of compilation) and
395     <c>-fomit-frame-pointer</c> (which doesn't keep the frame pointer in a register
396     for functions that don't need one).
397     </p>
398    
399     <p>
400     When you define the <c>CFLAGS</c> and <c>CXXFLAGS</c>, you should combine
401     several optimization flags, like in the following example:
402     </p>
403    
404     <pre caption="Defining the CFLAGS and CXXFLAGS variable">
405 swift 1.11 CFLAGS="-march=athlon-xp -pipe -O2"
406 swift 1.4 CXXFLAGS="${CFLAGS}" <comment># Use the same settings for both variables</comment>
407     </pre>
408    
409     </body>
410 swift 1.7 </subsection>
411     <subsection>
412 swift 1.4 <title>USE</title>
413     <body>
414    
415 swift 1.5 <p>
416 swift 1.19 <c>USE</c> is one of the most powerful variables Gentoo provides to its users.
417 swift 1.5 Several programs can be compiled with or without optional support for certain
418     items. For instance, some programs can be compiled with gtk-support, or with
419     qt-support. Others can be compiled with or without SSL support. Some programs
420     can even be compiled with framebuffer support (svgalib) instead of X11 support
421     (X-server).
422     </p>
423    
424     <p>
425     Most distributions compile their packages with support for as much as possible,
426     increasing the size of the programs and startup time, not to mention an enormous
427     amount of dependencies. With Gentoo you can define with what options a package
428     should be compiled with. This is where <c>USE</c> comes into play.
429     </p>
430    
431     <p>
432     In the <c>USE</c> variable you define keywords which are mapped onto
433     compile-options. For instance, <e>ssl</e> will compile ssl-support in the
434     programs that support it. <e>-X</e> will remove X-server support (note the minus
435     sign in front). <e>gnome gtk -kde -qt</e> will compile your programs with gnome
436     (and gtk) support, and not with kde (and qt) support, making your system fully
437     tweaked for GNOME.
438     </p>
439    
440     <p>
441     The default <c>USE</c> settings are placed in
442     <path>/etc/make.profile/make.defaults</path>. What you place in
443     <path>/etc/make.conf</path> is calculated against these defaults settings. If
444     you add something to the <c>USE</c> setting, it is added to the default list. If
445     you remove something from the <c>USE</c> setting (by placing a minus sign in
446     front of it) it is removed from the default list (if it was in the default list
447     at all). <e>Never</e> alter anything inside the <path>/etc/make.profile</path>
448     directory; it gets overwritten when you update Portage!
449     </p>
450    
451 swift 1.21 <!-- TODO: Link "USE Howto" to part=2&amp;chap=1 when Part II is official -->
452    
453 swift 1.5 <p>
454     A full description on <c>USE</c> can be found in our <uri
455 swift 1.10 link="/doc/en/use-howto.xml">USE Howto</uri>. As an example
456 swift 1.5 we show a <c>USE</c> setting for a KDE-based system with DVD, ALSA and CD
457     Recording support:
458     </p>
459    
460     <pre caption="USE setting">
461     USE="-gtk -gnome qt kde dvd alsa cdr"
462     </pre>
463    
464 swift 1.4 </body>
465 swift 1.7 </subsection>
466     <subsection>
467 swift 1.4 <title>ACCEPT_KEYWORDS</title>
468     <body>
469    
470 swift 1.6 <p>
471 swift 1.14 Ebuilds (the package format Gentoo uses) are located in one out of three trees.
472 swift 1.6 The first one is called <e>ARCH</e>, meaning that the ebuild and its
473 swift 1.22 dependencies are thought to be stable and ready for general acceptance.
474     To use packages from <e>ARCH</e>, <c>ACCEPT_KEYWORDS</c> should contain your
475     architecture (being <c>x86</c>, <c>alpha</c>, <c>ppc</c>, <c>sparc</c> or
476     <c>hppa</c>):
477 swift 1.6 </p>
478    
479     <pre caption="Setting ACCEPT_KEYWORDS for the x86 architecture in ARCH">
480     ACCEPT_KEYWORDS="x86"
481     </pre>
482    
483     <p>
484 swift 1.22 The other two trees (<e>~ARCH</e> and hard-masked ebuilds) are not meant to be
485     used during the installation as they occasionally break the installation
486     process.
487 swift 1.6 </p>
488    
489 swift 1.4 </body>
490 swift 1.7 </subsection>
491     <subsection>
492 swift 1.4 <title>MAKEOPTS</title>
493     <body>
494    
495 swift 1.6 <p>
496     With <c>MAKEOPTS</c> you define how many parallel compilations should occur when
497     you install a package. The suggested number is the number of CPUs in your system
498     plus one.
499     </p>
500    
501     <pre caption="MAKEOPTS for a regular, 1-CPU system">
502     MAKEOPTS="-j2"
503     </pre>
504    
505 swift 1.4 </body>
506 swift 1.7 </subsection>
507     <subsection>
508 swift 1.6 <title>Ready, Set, Go!</title>
509 swift 1.4 <body>
510 swift 1.3
511 swift 1.6 <p>
512 swift 1.12 Update your <path>/mnt/gentoo/etc/make.conf</path> to your own will and save.
513     You are now ready to continue with <uri link="?part=1&amp;chap=6">Installing the
514     Gentoo Base System</uri>.
515 swift 1.8 </p>
516 swift 1.6
517     </body>
518 swift 1.1 </subsection>
519     </section>
520 swift 1.7 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20