/[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.125 - (hide annotations) (download) (as text)
Sat Oct 6 19:49:18 2012 UTC (5 years, 4 months ago) by swift
Branch: MAIN
Changes since 1.124: +20 -8 lines
File MIME type: application/xml
Fix bug #386475 - Use SHA512 and Whirlpool checksums for all arches except mips

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 swift 1.125 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-stage.xml,v 1.124 2012/07/24 12:12:52 swift 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 swift 1.125 <version>13</version>
17     <date>2012-10-06</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 jkt 1.123 choose a mirror close to you: type <c>links http://www.gentoo.org/main/en/mirrors.xml</c>
99     and press enter.
100 swift 1.77 </p>
101    
102     <p>
103 fox2mike 1.94 If you don't have <c>links</c> available you should have <c>lynx</c> at your
104 swift 1.77 disposal. If you need to go through a proxy, export the <c>http_proxy</c> and
105     <c>ftp_proxy</c> variables:
106     </p>
107    
108     <pre caption="Setting proxy information for lynx">
109     # <i>export http_proxy="http://proxy.server.com:port"</i>
110     # <i>export ftp_proxy="http://proxy.server.com:port"</i>
111     </pre>
112    
113     <p>
114 fox2mike 1.94 We will now assume that you have <c>links</c> at your disposal.
115 swift 1.64 </p>
116    
117     <p>
118 jkt 1.123 Select a mirror closeby. Usually HTTP mirrors suffice, but other protocols are
119     available as well. Move to the <path><keyval id="release-dir"/></path>
120     directory. There you should see all available stage files for your architecture
121     (they might be stored within subdirectories named after the individual
122     subarchitectures). Select one and press <c>D</c> to download. When you're
123     finished, press <c>Q</c> to quit the browser.
124 neysx 1.105 </p>
125    
126     <p test="'x86'=func:keyval('arch')">
127     Most PC users should use the <b><keyval id="stage3"/></b> stage3 archive. All
128     modern PCs are considered i686. If you use an old machine, you can check the
129     <uri link="http://en.wikipedia.org/wiki/I686">list of i686-compatible
130     processors</uri> on Wikipedia. Old processors such as the Pentium, K5, K6, or
131 nightmorph 1.111 Via C3 and similar require the more generic <b>x86</b> stage3. Processors older
132     than <b>i486</b> are not supported.
133 swift 1.12 </p>
134    
135 fox2mike 1.94 <pre caption="Surfing to the mirror listing with links">
136     # <i>links http://www.gentoo.org/main/en/mirrors.xml</i>
137 swift 1.77
138 fox2mike 1.94 <comment>(If you need proxy support with links:)</comment>
139     # <i>links -http-proxy proxy.server.com:8080 http://www.gentoo.org/main/en/mirrors.xml</i>
140 swift 1.12 </pre>
141    
142 swift 1.32 <p>
143 neysx 1.91 Make sure you download a <b>stage3</b> tarball - installations using a stage1
144     or stage2 tarball are not supported anymore.
145 swift 1.90 </p>
146    
147     <p>
148 swift 1.32 If you want to check the integrity of the downloaded stage tarball, use
149 swift 1.125 <c>openssl</c> and compare the output with the checksums provided on the
150     mirror. The digests files provide several checksums, each taken with a different
151     algorithm. The recommended ones are SHA512 and Whirlpool.
152 swift 1.32 </p>
153    
154 swift 1.125 <pre caption="Calculating the integrity checksum of a stage tarball">
155     <comment>## Calculating the SHA512 checksum</comment>
156     # <i>openssl dgst -r -sha512 <keyval id="stage3" /></i>
157     <comment>or</comment>
158     # <i>sha512sum <keyval id="stage3" /></i>
159    
160     <comment>## Calculating the Whirlpool checksum</comment>
161     # <i>openssl dgst -r -whirlpool <keyval id="stage3" /></i>
162 swift 1.32 </pre>
163    
164 swift 1.125 <p>
165     Then compare the output of these commands with the value registered in the
166     .DIGESTS files that can be found on the mirrors as well. The values need to
167     match, otherwise the downloaded file might be corrupt (or the digests file is).
168     </p>
169    
170 swift 1.12 </body>
171     </subsection>
172     <subsection>
173     <title>Unpacking the Stage Tarball</title>
174     <body>
175    
176     <p>
177 neysx 1.91 Now unpack your downloaded stage onto your system. We use <c>tar</c> to proceed
178     as it is the easiest method:
179 swift 1.12 </p>
180    
181     <pre caption="Unpacking the stage">
182 neysx 1.91 # <i>tar xvjpf stage3-*.tar.bz2</i>
183 swift 1.12 </pre>
184    
185     <p>
186 neysx 1.91 Make sure that you use the same options (<c>xvjpf</c>). The <c>x</c> stands for
187     <e>Extract</e>, the <c>v</c> for <e>Verbose</e> to see what happens during the
188     extraction process (optional), the <c>j</c> for <e>Decompress with bzip2</e>,
189     the <c>p</c> for <e>Preserve permissions</e> and the <c>f</c> to denote that we
190     want to extract a file, not standard input.
191     </p>
192 swift 1.86
193 neysx 1.105 <!-- MIPS uses its own hb-install-stage.xml file, any other arch?
194 swift 1.79 <note>
195 swift 1.84 Some architectures (e.g. MIPS) Installation CDs and boot images rely upon the
196 neysx 1.91 <c>tar</c> built into BusyBox which doesn't currently support the <c>v</c>
197     option. Use the <c>xjpf</c> options instead.
198 swift 1.79 </note>
199 neysx 1.105 -->
200 swift 1.79
201 swift 1.12 <p>
202 swift 1.34 Now that the stage is installed, continue with <uri
203     link="#installing_portage">Installing Portage</uri>.
204 swift 1.12 </p>
205    
206     </body>
207     </subsection>
208     </section>
209 neysx 1.105 <section test="not(contains('AMD64 x86', func:keyval('arch')))">
210     <title>Alternative: Using a Stage from the Universal CD</title>
211 swift 1.12 <subsection>
212     <title>Extracting the Stage Tarball</title>
213     <body>
214    
215     <p>
216     The stages on the CD reside in the <path>/mnt/cdrom/stages</path> directory. To
217     see a listing of available stages, use <c>ls</c>:
218     </p>
219    
220     <pre caption="List all available stages">
221     # <i>ls /mnt/cdrom/stages</i>
222     </pre>
223    
224     <p>
225     If the system replies with an error, you may need to mount the CD-ROM first:
226     </p>
227    
228     <pre caption="Mounting the CD-ROM">
229     # <i>ls /mnt/cdrom/stages</i>
230     ls: /mnt/cdrom/stages: No such file or directory
231     # <i>mount /dev/cdroms/cdrom0 /mnt/cdrom</i>
232     # <i>ls /mnt/cdrom/stages</i>
233     </pre>
234    
235     <p>
236     Now go into your Gentoo mountpoint (usually <path>/mnt/gentoo</path>):
237     </p>
238    
239     <pre caption="Changing directory to /mnt/gentoo">
240     # <i>cd /mnt/gentoo</i>
241     </pre>
242    
243     <p>
244 neysx 1.91 We will now extract the stage tarball of your choice. We will do this with
245 vanquirius 1.92 <c>tar</c>. Make sure you use the same options (<c>xvjpf</c>). The <c>v</c>
246 nightmorph 1.117 argument is optional and not supported in some <c>tar</c> versions. In the next
247     example, we extract the stage tarball
248     <path>stage3-&lt;subarch&gt;-&lt;release&gt;.tar.bz2</path>. Be sure to
249     substitute the tarball filename with your stage.
250 swift 1.12 </p>
251    
252     <pre caption="Extracting the stage tarball">
253 nightmorph 1.117 # <i>tar xvjpf /mnt/cdrom/stages/stage3-&lt;subarch&gt;-&lt;release&gt;.tar.bz2</i>
254 swift 1.12 </pre>
255    
256 swift 1.34 <p>
257     Now that the stage is installed, continue with <uri
258     link="#installing_portage">Installing Portage</uri>.
259     </p>
260    
261 swift 1.12 </body>
262     </subsection>
263 swift 1.34 </section>
264     <section id="installing_portage">
265     <title>Installing Portage</title>
266 swift 1.12 <subsection>
267 swift 1.71 <title>Unpacking a Portage Snapshot</title>
268 swift 1.34 <body>
269    
270     <p>
271 neysx 1.72 You now have to install a Portage snapshot, a collection of files that inform
272 swift 1.71 Portage what software titles you can install, which profiles are available, etc.
273     </p>
274    
275     </body>
276     </subsection>
277     <subsection id="installing_from_Internet">
278 swift 1.77 <title>Download and Install a Portage Snapshot</title>
279 swift 1.71 <body>
280    
281     <p>
282 neysx 1.72 Go to the mountpoint where you mounted your filesystem (most likely
283 swift 1.71 <path>/mnt/gentoo</path>):
284     </p>
285    
286     <pre caption="Going to the Gentoo mountpoint">
287     # <i>cd /mnt/gentoo</i>
288     </pre>
289    
290     <p>
291 fox2mike 1.94 Fire up <c>links</c> (or <c>lynx</c>) and go to our <uri
292 neysx 1.72 link="/main/en/mirrors.xml">Gentoo mirror list</uri>. Pick a mirror close to
293     you and open the <path>snapshots/</path> directory. There, download the latest
294 rane 1.100 Portage snapshot (<path>portage-latest.tar.bz2</path>) by selecting it and
295     pressing <c>D</c>.
296 swift 1.71 </p>
297    
298 neysx 1.72 <pre caption="Browsing the Gentoo mirrorlist">
299 fox2mike 1.94 # <i>links http://www.gentoo.org/main/en/mirrors.xml</i>
300 swift 1.71 </pre>
301    
302     <p>
303     Now exit your browser by pressing <c>Q</c>. You will now have a Portage snapshot
304 nightmorph 1.96 stored in <path>/mnt/gentoo</path>.
305     </p>
306    
307     <p>
308     If you want to check the integrity of the downloaded snapshot, use
309     <c>md5sum</c> and compare the output with the MD5 checksum provided on the
310     mirror.
311     </p>
312    
313     <pre caption="Checking integrity of a Portage snapshot">
314     # <i>md5sum -c portage-latest.tar.bz2.md5sum</i>
315     portage-latest.tar.bz2: OK
316     </pre>
317    
318     <p>
319     In the next step, we extract the Portage snapshot onto your filesystem. Make
320     sure that you use the exact command; the last option is a capital <c>C</c>, not
321     <c>c</c>.
322 swift 1.71 </p>
323    
324     <pre caption="Extracting the Portage snapshot">
325 rane 1.100 # <i>tar xvjf /mnt/gentoo/portage-latest.tar.bz2 -C /mnt/gentoo/usr</i>
326 swift 1.71 </pre>
327    
328     </body>
329     </subsection>
330 swift 1.7 </section>
331 swift 1.34
332     <section id="compile_options">
333 swift 1.7 <title>Configuring the Compile Options</title>
334 swift 1.1 <subsection>
335 swift 1.3 <title>Introduction</title>
336 swift 1.1 <body>
337    
338     <p>
339 swift 1.3 To optimize Gentoo, you can set a couple of variables which impact Portage
340     behaviour. All those variables can be set as environment variables (using
341     <c>export</c>) but that isn't permanent. To keep your settings, Portage provides
342 swift 1.124 you with <path>/etc/portage/make.conf</path>, a configuration file for Portage.
343     It is this file we will edit now.
344 swift 1.1 </p>
345    
346 dertobi123 1.27 <note>
347     A commented listing of all possible variables can be found in
348 nightmorph 1.117 <path>/mnt/gentoo/usr/share/portage/config/make.conf.example</path>. For a
349     successful Gentoo installation you'll only need to set the variables which are
350     mentioned beneath.
351 dertobi123 1.27 </note>
352    
353 swift 1.3 <p>
354     Fire up your favorite editor (in this guide we use <c>nano</c>) so we can alter
355 swift 1.57 the optimization variables we will discuss hereafter.
356 swift 1.3 </p>
357    
358 swift 1.124 <pre caption="Opening /etc/portage/make.conf">
359     # <i>nano -w /mnt/gentoo/etc/portage/make.conf</i>
360 swift 1.3 </pre>
361    
362     <p>
363 swift 1.57 As you probably noticed, the <path>make.conf.example</path> file is
364 dertobi123 1.27 structured in a generic way: commented lines start with "#", other lines define
365 swift 1.57 variables using the <c>VARIABLE="content"</c> syntax. The <path>make.conf</path>
366     file uses the same syntax. Several of those variables are discussed next.
367 swift 1.3 </p>
368    
369     </body>
370 swift 1.7 </subsection>
371     <subsection>
372 swift 1.4 <title>CFLAGS and CXXFLAGS</title>
373     <body>
374    
375     <p>
376     The <c>CFLAGS</c> and <c>CXXFLAGS</c> variables define the optimization flags
377     for the <c>gcc</c> C and C++ compiler respectively. Although we define those
378     generally here, you will only have maximum performance if you optimize these
379 swift 1.18 flags for each program separately. The reason for this is because every program
380 swift 1.4 is different.
381     </p>
382    
383     <p>
384     In <path>make.conf</path> you should define the optimization flags you think
385     will make your system the most responsive <e>generally</e>. Don't place
386     experimental settings in this variable; too much optimization can make
387     programs behave bad (crash, or even worse, malfunction).
388     </p>
389    
390     <p>
391     We will not explain all possible optimization options. If you want to know
392 swift 1.43 them all, read the <uri link="http://gcc.gnu.org/onlinedocs/">GNU
393 swift 1.4 Online Manual(s)</uri> or the <c>gcc</c> info page (<c>info gcc</c> -- only
394 swift 1.34 works on a working Linux system). The <path>make.conf.example</path> file
395     itself also contains lots of examples and information; don't forget to read it
396     too.
397 swift 1.4 </p>
398    
399 nightmorph 1.112 <p test="not(contains('AMD64 x86', func:keyval('arch')))">
400 neysx 1.105 A first setting is the <c>-march=</c> or <c>-mcpu=</c> flag, which specifies
401     the name of the target architecture. Possible options are described in the
402     <path>make.conf.example</path> file (as comments).
403 swift 1.4 </p>
404    
405 nightmorph 1.112 <p test="contains('AMD64 x86',func:keyval('arch'))">
406     A first setting is the <c>-march=</c> or <c>-mtune=</c> flag, which specifies
407     the name of the target architecture. Possible options are described in the
408     <path>make.conf.example</path> file (as comments).
409     </p>
410    
411 swift 1.4 <p>
412 neysx 1.48 A second one is the <c>-O</c> flag (that is a capital O, not a zero),
413     which specifies the <c>gcc</c> optimization
414 swift 1.6 class flag. Possible classes are <c>s</c> (for size-optimized),
415 nightmorph 1.116 <c>0</c> (zero - for no optimizations), <c>1</c>, <c>2</c> or even <c>3</c> for more
416 swift 1.4 speed-optimization flags (every class has the same flags as the one before, plus
417 nightmorph 1.116 some extras). <c>-O2</c> is the recommended default. <c>-O3</c> is known to
418     cause problems when used system-wide, so we recommend that you stick to
419     <c>-O2</c>.
420 swift 1.4 </p>
421    
422     <p>
423 swift 1.67 Another popular optimization flag is <c>-pipe</c> (use pipes rather than
424     temporary files for communication between the various stages of compilation).
425 neysx 1.118 It has no impact on the generated code, but uses more memory. On systems with
426     low memory, gcc might get killed. In that case, do not use this flag.
427 swift 1.67 </p>
428    
429     <p>
430 neysx 1.106 Using <c>-fomit-frame-pointer</c> (which doesn't keep the frame pointer in a
431     register for functions that don't need one) might have serious repercussions on
432     the debugging of applications.
433 swift 1.4 </p>
434    
435     <p>
436     When you define the <c>CFLAGS</c> and <c>CXXFLAGS</c>, you should combine
437 nightmorph 1.109 several optimization flags. The default values contained in the stage3 archive
438 neysx 1.105 you unpacked should be good enough. The following example is just an example:
439 swift 1.4 </p>
440    
441 nightmorph 1.121 <pre test="not(contains('AMD64 arm', func:keyval('arch')))" caption="Defining the CFLAGS and CXXFLAGS variable">
442 neysx 1.105 CFLAGS="<keyval id="CFLAGS"/>"
443     <comment># Use the same settings for both variables</comment>
444     CXXFLAGS="${CFLAGS}"
445 swift 1.4 </pre>
446    
447 nightmorph 1.103 <pre test="func:keyval('arch')='AMD64'" caption="Defining the CFLAGS and CXXFLAGS variable">
448 nightmorph 1.120 CFLAGS="<keyval id="CFLAGS"/>" <comment># Intel EM64T users should use -march=core2</comment>
449 neysx 1.105 <comment># Use the same settings for both variables</comment>
450     CXXFLAGS="${CFLAGS}"
451 nightmorph 1.102 </pre>
452    
453 nightmorph 1.121 <pre test="func:keyval('arch')='arm'" caption="Defining the CFLAGS and CXXFLAGS variable">
454     CFLAGS="<keyval id="CFLAGS"/> <comment># Be sure to change -march to match your CPU type</comment>
455     <comment># Use the same settings for both variables</comment>
456     CXXFLAGS="${CFLAGS}"
457     </pre>
458    
459 nightmorph 1.116 <note>
460     You may also want to view the <uri
461     link="/doc/en/gcc-optimization.xml">Compilation Optimization Guide</uri> for
462     more information on how the various compilation options can affect your system.
463     </note>
464    
465 swift 1.4 </body>
466 swift 1.7 </subsection>
467     <subsection>
468 swift 1.4 <title>MAKEOPTS</title>
469     <body>
470    
471 swift 1.6 <p>
472     With <c>MAKEOPTS</c> you define how many parallel compilations should occur when
473 nightmorph 1.122 you install a package. A good choice is the number of CPUs (or CPU cores) in
474     your system plus one, but this guideline isn't always perfect.
475 swift 1.6 </p>
476    
477     <pre caption="MAKEOPTS for a regular, 1-CPU system">
478     MAKEOPTS="-j2"
479     </pre>
480    
481 swift 1.4 </body>
482 swift 1.7 </subsection>
483     <subsection>
484 swift 1.6 <title>Ready, Set, Go!</title>
485 swift 1.4 <body>
486 swift 1.3
487 swift 1.6 <p>
488 swift 1.124 Update your <path>/mnt/gentoo/etc/portage/make.conf</path> to your own preference
489     and save (<c>nano</c> users would hit <c>Ctrl-X</c>). You are now ready to continue
490 swift 1.57 with <uri link="?part=1&amp;chap=6">Installing the Gentoo Base System</uri>.
491 swift 1.8 </p>
492 swift 1.6
493     </body>
494 swift 1.1 </subsection>
495     </section>
496 swift 1.7 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20