/[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.119 - (hide annotations) (download) (as text)
Tue Mar 23 21:45:20 2010 UTC (8 years, 9 months ago) by nightmorph
Branch: MAIN
Changes since 1.118: +7 -10 lines
File MIME type: application/xml
livedvds don't have stages included, unfortunately. bug 310983.

1 swift 1.31 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3    
4 swift 1.10 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 jkt 1.89 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6 swift 1.10
7 nightmorph 1.119 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-stage.xml,v 1.118 2009/10/19 16:16:35 neysx Exp $ -->
8 swift 1.15
9 swift 1.7 <sections>
10 swift 1.68
11 neysx 1.101 <abstract>
12     Gentoo installs work through a stage3 archive. In this chapter we
13     describe how you extract the stage3 archive and configure Portage.
14     </abstract>
15    
16 nightmorph 1.119 <version>10.2</version>
17     <date>2010-03-23</date>
18 swift 1.68
19 swift 1.1 <section>
20 swift 1.34 <title>Installing a Stage Tarball</title>
21     <subsection>
22 swift 1.38 <title>Setting the Date/Time Right</title>
23     <body>
24    
25     <p>
26     Before you continue you need to check your date/time and update it. A
27     misconfigured clock may lead to strange results in the future!
28     </p>
29    
30     <p>
31     To verify the current date/time, run <c>date</c>:
32     </p>
33    
34     <pre caption="Verifying the date/time">
35     # <i>date</i>
36 neysx 1.97 Fri Mar 29 16:21:18 UTC 2005
37 swift 1.38 </pre>
38    
39     <p>
40 neysx 1.48 If the date/time displayed is wrong, update it using the <c>date
41     MMDDhhmmYYYY</c> syntax (<b>M</b>onth, <b>D</b>ay, <b>h</b>our, <b>m</b>inute
42 neysx 1.97 and <b>Y</b>ear). At this stage, you should use UTC time. You will be able to
43     define your timezone later on. For instance, to set the date to March 29th,
44     16:21 in the year 2005:
45 swift 1.38 </p>
46    
47 neysx 1.97 <pre caption="Setting the UTC date/time">
48 swift 1.84 # <i>date 032916212005</i>
49 swift 1.38 </pre>
50    
51     </body>
52     </subsection>
53     <subsection>
54 swift 1.34 <title>Making your Choice</title>
55 swift 1.1 <body>
56    
57     <p>
58 neysx 1.105 The next step you need to perform is to install the <e>stage3</e> tarball onto
59     your system. You have the option of downloading the required tarball from the
60 nightmorph 1.119 Internet or, if you booted one of the Gentoo Universal CDs, copy it over from
61     the disc itself. In most cases, the command <c>uname -m</c> can be used to help
62     you decide which stage file to download.
63 swift 1.12 </p>
64    
65 neysx 1.105 <p>
66 nightmorph 1.119 Minimal CDs and LiveDVDs do not contain any stage3 archive.
67 neysx 1.105 </p>
68    
69     <ul test="not(contains('AMD64 x86', func:keyval('arch')))">
70 swift 1.34 <li><uri link="#doc_chap2">Default: Using a Stage from the Internet</uri></li>
71 swift 1.84 <li>
72 neysx 1.105 <uri link="#doc_chap3">Alternative: Using a Stage from the Universal CD</uri>
73 swift 1.84 </li>
74 swift 1.12 </ul>
75    
76     </body>
77 swift 1.34 </subsection>
78 swift 1.12 </section>
79     <section>
80 swift 1.34 <title>Default: Using a Stage from the Internet</title>
81 swift 1.12 <subsection>
82     <title>Downloading the Stage Tarball</title>
83     <body>
84    
85     <p>
86     Go to the Gentoo mountpoint at which you mounted your filesystems
87     (most likely <path>/mnt/gentoo</path>):
88     </p>
89    
90     <pre caption="Going to the Gentoo mountpoint">
91     # <i>cd /mnt/gentoo</i>
92     </pre>
93    
94     <p>
95     Depending on your installation medium, you have a couple of tools available to
96 fox2mike 1.94 download a stage. If you have <c>links</c> available, then you can immediately
97 swift 1.64 surf to <uri link="/main/en/mirrors.xml">the Gentoo mirrorlist</uri> and
98 swift 1.77 choose a mirror close to you.
99     </p>
100    
101     <p>
102 fox2mike 1.94 If you don't have <c>links</c> available you should have <c>lynx</c> at your
103 swift 1.77 disposal. If you need to go through a proxy, export the <c>http_proxy</c> and
104     <c>ftp_proxy</c> variables:
105     </p>
106    
107     <pre caption="Setting proxy information for lynx">
108     # <i>export http_proxy="http://proxy.server.com:port"</i>
109     # <i>export ftp_proxy="http://proxy.server.com:port"</i>
110     </pre>
111    
112     <p>
113 fox2mike 1.94 We will now assume that you have <c>links</c> at your disposal.
114 swift 1.64 </p>
115    
116     <p>
117 nightmorph 1.115 Move to the <path><keyval id="release-dir"/></path> directory. There you
118 neysx 1.105 should see all available stage files for your architecture (they might be
119     stored within subdirectories named after the individual subarchitectures).
120     Select one and press <c>D</c> to download. When you're finished, press <c>Q</c>
121     to quit the browser.
122     </p>
123    
124     <p test="'x86'=func:keyval('arch')">
125     Most PC users should use the <b><keyval id="stage3"/></b> stage3 archive. All
126     modern PCs are considered i686. If you use an old machine, you can check the
127     <uri link="http://en.wikipedia.org/wiki/I686">list of i686-compatible
128     processors</uri> on Wikipedia. Old processors such as the Pentium, K5, K6, or
129 nightmorph 1.111 Via C3 and similar require the more generic <b>x86</b> stage3. Processors older
130     than <b>i486</b> are not supported.
131 swift 1.12 </p>
132    
133 fox2mike 1.94 <pre caption="Surfing to the mirror listing with links">
134     # <i>links http://www.gentoo.org/main/en/mirrors.xml</i>
135 swift 1.77
136 fox2mike 1.94 <comment>(If you need proxy support with links:)</comment>
137     # <i>links -http-proxy proxy.server.com:8080 http://www.gentoo.org/main/en/mirrors.xml</i>
138 swift 1.12 </pre>
139    
140 swift 1.32 <p>
141 neysx 1.91 Make sure you download a <b>stage3</b> tarball - installations using a stage1
142     or stage2 tarball are not supported anymore.
143 swift 1.90 </p>
144    
145     <p>
146 swift 1.32 If you want to check the integrity of the downloaded stage tarball, use
147     <c>md5sum</c> and compare the output with the MD5 checksum provided on the
148 neysx 1.113 mirror.
149 swift 1.32 </p>
150    
151 neysx 1.113 <pre caption="Checking integrity of a stage tarball">
152 neysx 1.105 # <i>md5sum -c <keyval id="stage3"/>.DIGESTS</i>
153     <keyval id="stage3"/>: OK
154 swift 1.32 </pre>
155    
156 swift 1.12 </body>
157     </subsection>
158     <subsection>
159     <title>Unpacking the Stage Tarball</title>
160     <body>
161    
162     <p>
163 neysx 1.91 Now unpack your downloaded stage onto your system. We use <c>tar</c> to proceed
164     as it is the easiest method:
165 swift 1.12 </p>
166    
167     <pre caption="Unpacking the stage">
168 neysx 1.91 # <i>tar xvjpf stage3-*.tar.bz2</i>
169 swift 1.12 </pre>
170    
171     <p>
172 neysx 1.91 Make sure that you use the same options (<c>xvjpf</c>). The <c>x</c> stands for
173     <e>Extract</e>, the <c>v</c> for <e>Verbose</e> to see what happens during the
174     extraction process (optional), the <c>j</c> for <e>Decompress with bzip2</e>,
175     the <c>p</c> for <e>Preserve permissions</e> and the <c>f</c> to denote that we
176     want to extract a file, not standard input.
177     </p>
178 swift 1.86
179 neysx 1.105 <!-- MIPS uses its own hb-install-stage.xml file, any other arch?
180 swift 1.79 <note>
181 swift 1.84 Some architectures (e.g. MIPS) Installation CDs and boot images rely upon the
182 neysx 1.91 <c>tar</c> built into BusyBox which doesn't currently support the <c>v</c>
183     option. Use the <c>xjpf</c> options instead.
184 swift 1.79 </note>
185 neysx 1.105 -->
186 swift 1.79
187 swift 1.12 <p>
188 swift 1.34 Now that the stage is installed, continue with <uri
189     link="#installing_portage">Installing Portage</uri>.
190 swift 1.12 </p>
191    
192     </body>
193     </subsection>
194     </section>
195 neysx 1.105 <section test="not(contains('AMD64 x86', func:keyval('arch')))">
196     <title>Alternative: Using a Stage from the Universal CD</title>
197 swift 1.12 <subsection>
198     <title>Extracting the Stage Tarball</title>
199     <body>
200    
201     <p>
202     The stages on the CD reside in the <path>/mnt/cdrom/stages</path> directory. To
203     see a listing of available stages, use <c>ls</c>:
204     </p>
205    
206     <pre caption="List all available stages">
207     # <i>ls /mnt/cdrom/stages</i>
208     </pre>
209    
210     <p>
211     If the system replies with an error, you may need to mount the CD-ROM first:
212     </p>
213    
214     <pre caption="Mounting the CD-ROM">
215     # <i>ls /mnt/cdrom/stages</i>
216     ls: /mnt/cdrom/stages: No such file or directory
217     # <i>mount /dev/cdroms/cdrom0 /mnt/cdrom</i>
218     # <i>ls /mnt/cdrom/stages</i>
219     </pre>
220    
221     <p>
222     Now go into your Gentoo mountpoint (usually <path>/mnt/gentoo</path>):
223     </p>
224    
225     <pre caption="Changing directory to /mnt/gentoo">
226     # <i>cd /mnt/gentoo</i>
227     </pre>
228    
229     <p>
230 neysx 1.91 We will now extract the stage tarball of your choice. We will do this with
231 vanquirius 1.92 <c>tar</c>. Make sure you use the same options (<c>xvjpf</c>). The <c>v</c>
232 nightmorph 1.117 argument is optional and not supported in some <c>tar</c> versions. In the next
233     example, we extract the stage tarball
234     <path>stage3-&lt;subarch&gt;-&lt;release&gt;.tar.bz2</path>. Be sure to
235     substitute the tarball filename with your stage.
236 swift 1.12 </p>
237    
238     <pre caption="Extracting the stage tarball">
239 nightmorph 1.117 # <i>tar xvjpf /mnt/cdrom/stages/stage3-&lt;subarch&gt;-&lt;release&gt;.tar.bz2</i>
240 swift 1.12 </pre>
241    
242 swift 1.34 <p>
243     Now that the stage is installed, continue with <uri
244     link="#installing_portage">Installing Portage</uri>.
245     </p>
246    
247 swift 1.12 </body>
248     </subsection>
249 swift 1.34 </section>
250     <section id="installing_portage">
251     <title>Installing Portage</title>
252 swift 1.12 <subsection>
253 swift 1.71 <title>Unpacking a Portage Snapshot</title>
254 swift 1.34 <body>
255    
256     <p>
257 neysx 1.72 You now have to install a Portage snapshot, a collection of files that inform
258 swift 1.71 Portage what software titles you can install, which profiles are available, etc.
259     </p>
260    
261     </body>
262     </subsection>
263     <subsection id="installing_from_Internet">
264 swift 1.77 <title>Download and Install a Portage Snapshot</title>
265 swift 1.71 <body>
266    
267     <p>
268 neysx 1.72 Go to the mountpoint where you mounted your filesystem (most likely
269 swift 1.71 <path>/mnt/gentoo</path>):
270     </p>
271    
272     <pre caption="Going to the Gentoo mountpoint">
273     # <i>cd /mnt/gentoo</i>
274     </pre>
275    
276     <p>
277 fox2mike 1.94 Fire up <c>links</c> (or <c>lynx</c>) and go to our <uri
278 neysx 1.72 link="/main/en/mirrors.xml">Gentoo mirror list</uri>. Pick a mirror close to
279     you and open the <path>snapshots/</path> directory. There, download the latest
280 rane 1.100 Portage snapshot (<path>portage-latest.tar.bz2</path>) by selecting it and
281     pressing <c>D</c>.
282 swift 1.71 </p>
283    
284 neysx 1.72 <pre caption="Browsing the Gentoo mirrorlist">
285 fox2mike 1.94 # <i>links http://www.gentoo.org/main/en/mirrors.xml</i>
286 swift 1.71 </pre>
287    
288     <p>
289     Now exit your browser by pressing <c>Q</c>. You will now have a Portage snapshot
290 nightmorph 1.96 stored in <path>/mnt/gentoo</path>.
291     </p>
292    
293     <p>
294     If you want to check the integrity of the downloaded snapshot, use
295     <c>md5sum</c> and compare the output with the MD5 checksum provided on the
296     mirror.
297     </p>
298    
299     <pre caption="Checking integrity of a Portage snapshot">
300     # <i>md5sum -c portage-latest.tar.bz2.md5sum</i>
301     portage-latest.tar.bz2: OK
302     </pre>
303    
304     <p>
305     In the next step, we extract the Portage snapshot onto your filesystem. Make
306     sure that you use the exact command; the last option is a capital <c>C</c>, not
307     <c>c</c>.
308 swift 1.71 </p>
309    
310     <pre caption="Extracting the Portage snapshot">
311 rane 1.100 # <i>tar xvjf /mnt/gentoo/portage-latest.tar.bz2 -C /mnt/gentoo/usr</i>
312 swift 1.71 </pre>
313    
314     </body>
315     </subsection>
316 swift 1.7 </section>
317 swift 1.34
318     <section id="compile_options">
319 swift 1.7 <title>Configuring the Compile Options</title>
320 swift 1.1 <subsection>
321 swift 1.3 <title>Introduction</title>
322 swift 1.1 <body>
323    
324     <p>
325 swift 1.3 To optimize Gentoo, you can set a couple of variables which impact Portage
326     behaviour. All those variables can be set as environment variables (using
327     <c>export</c>) but that isn't permanent. To keep your settings, Portage provides
328     you with <path>/etc/make.conf</path>, a configuration file for Portage. It is
329     this file we will edit now.
330 swift 1.1 </p>
331    
332 dertobi123 1.27 <note>
333     A commented listing of all possible variables can be found in
334 nightmorph 1.117 <path>/mnt/gentoo/usr/share/portage/config/make.conf.example</path>. For a
335     successful Gentoo installation you'll only need to set the variables which are
336     mentioned beneath.
337 dertobi123 1.27 </note>
338    
339 swift 1.3 <p>
340     Fire up your favorite editor (in this guide we use <c>nano</c>) so we can alter
341 swift 1.57 the optimization variables we will discuss hereafter.
342 swift 1.3 </p>
343    
344     <pre caption="Opening /etc/make.conf">
345 swift 1.12 # <i>nano -w /mnt/gentoo/etc/make.conf</i>
346 swift 1.3 </pre>
347    
348     <p>
349 swift 1.57 As you probably noticed, the <path>make.conf.example</path> file is
350 dertobi123 1.27 structured in a generic way: commented lines start with "#", other lines define
351 swift 1.57 variables using the <c>VARIABLE="content"</c> syntax. The <path>make.conf</path>
352     file uses the same syntax. Several of those variables are discussed next.
353 swift 1.3 </p>
354    
355     </body>
356 swift 1.7 </subsection>
357     <subsection>
358 swift 1.4 <title>CFLAGS and CXXFLAGS</title>
359     <body>
360    
361     <p>
362     The <c>CFLAGS</c> and <c>CXXFLAGS</c> variables define the optimization flags
363     for the <c>gcc</c> C and C++ compiler respectively. Although we define those
364     generally here, you will only have maximum performance if you optimize these
365 swift 1.18 flags for each program separately. The reason for this is because every program
366 swift 1.4 is different.
367     </p>
368    
369     <p>
370     In <path>make.conf</path> you should define the optimization flags you think
371     will make your system the most responsive <e>generally</e>. Don't place
372     experimental settings in this variable; too much optimization can make
373     programs behave bad (crash, or even worse, malfunction).
374     </p>
375    
376     <p>
377     We will not explain all possible optimization options. If you want to know
378 swift 1.43 them all, read the <uri link="http://gcc.gnu.org/onlinedocs/">GNU
379 swift 1.4 Online Manual(s)</uri> or the <c>gcc</c> info page (<c>info gcc</c> -- only
380 swift 1.34 works on a working Linux system). The <path>make.conf.example</path> file
381     itself also contains lots of examples and information; don't forget to read it
382     too.
383 swift 1.4 </p>
384    
385 nightmorph 1.112 <p test="not(contains('AMD64 x86', func:keyval('arch')))">
386 neysx 1.105 A first setting is the <c>-march=</c> or <c>-mcpu=</c> flag, which specifies
387     the name of the target architecture. Possible options are described in the
388     <path>make.conf.example</path> file (as comments).
389 swift 1.4 </p>
390    
391 nightmorph 1.112 <p test="contains('AMD64 x86',func:keyval('arch'))">
392     A first setting is the <c>-march=</c> or <c>-mtune=</c> flag, which specifies
393     the name of the target architecture. Possible options are described in the
394     <path>make.conf.example</path> file (as comments).
395     </p>
396    
397 swift 1.4 <p>
398 neysx 1.48 A second one is the <c>-O</c> flag (that is a capital O, not a zero),
399     which specifies the <c>gcc</c> optimization
400 swift 1.6 class flag. Possible classes are <c>s</c> (for size-optimized),
401 nightmorph 1.116 <c>0</c> (zero - for no optimizations), <c>1</c>, <c>2</c> or even <c>3</c> for more
402 swift 1.4 speed-optimization flags (every class has the same flags as the one before, plus
403 nightmorph 1.116 some extras). <c>-O2</c> is the recommended default. <c>-O3</c> is known to
404     cause problems when used system-wide, so we recommend that you stick to
405     <c>-O2</c>.
406 swift 1.4 </p>
407    
408     <p>
409 swift 1.67 Another popular optimization flag is <c>-pipe</c> (use pipes rather than
410     temporary files for communication between the various stages of compilation).
411 neysx 1.118 It has no impact on the generated code, but uses more memory. On systems with
412     low memory, gcc might get killed. In that case, do not use this flag.
413 swift 1.67 </p>
414    
415     <p>
416 neysx 1.106 Using <c>-fomit-frame-pointer</c> (which doesn't keep the frame pointer in a
417     register for functions that don't need one) might have serious repercussions on
418     the debugging of applications.
419 swift 1.4 </p>
420    
421     <p>
422     When you define the <c>CFLAGS</c> and <c>CXXFLAGS</c>, you should combine
423 nightmorph 1.109 several optimization flags. The default values contained in the stage3 archive
424 neysx 1.105 you unpacked should be good enough. The following example is just an example:
425 swift 1.4 </p>
426    
427 neysx 1.105 <pre test="not(func:keyval('arch')='AMD64')" caption="Defining the CFLAGS and CXXFLAGS variable">
428     CFLAGS="<keyval id="CFLAGS"/>"
429     <comment># Use the same settings for both variables</comment>
430     CXXFLAGS="${CFLAGS}"
431 swift 1.4 </pre>
432    
433 nightmorph 1.103 <pre test="func:keyval('arch')='AMD64'" caption="Defining the CFLAGS and CXXFLAGS variable">
434 neysx 1.105 CFLAGS="<keyval id="CFLAGS"/>" <comment># EM64T users should use -march=nocona</comment>
435     <comment># Use the same settings for both variables</comment>
436     CXXFLAGS="${CFLAGS}"
437 nightmorph 1.102 </pre>
438    
439 nightmorph 1.116 <note>
440     You may also want to view the <uri
441     link="/doc/en/gcc-optimization.xml">Compilation Optimization Guide</uri> for
442     more information on how the various compilation options can affect your system.
443     </note>
444    
445 swift 1.4 </body>
446 swift 1.7 </subsection>
447     <subsection>
448 swift 1.4 <title>MAKEOPTS</title>
449     <body>
450    
451 swift 1.6 <p>
452     With <c>MAKEOPTS</c> you define how many parallel compilations should occur when
453 swift 1.62 you install a package. A good choice is the number of CPUs in your system plus
454     one, but this guideline isn't always perfect.
455 swift 1.6 </p>
456    
457     <pre caption="MAKEOPTS for a regular, 1-CPU system">
458     MAKEOPTS="-j2"
459     </pre>
460    
461 swift 1.4 </body>
462 swift 1.7 </subsection>
463     <subsection>
464 swift 1.6 <title>Ready, Set, Go!</title>
465 swift 1.4 <body>
466 swift 1.3
467 swift 1.6 <p>
468 neysx 1.61 Update your <path>/mnt/gentoo/etc/make.conf</path> to your own preference and
469     save (<c>nano</c> users would hit <c>Ctrl-X</c>). You are now ready to continue
470 swift 1.57 with <uri link="?part=1&amp;chap=6">Installing the Gentoo Base System</uri>.
471 swift 1.8 </p>
472 swift 1.6
473     </body>
474 swift 1.1 </subsection>
475     </section>
476 swift 1.7 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20