/[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.135 - (hide annotations) (download) (as text)
Tue Dec 17 10:38:05 2013 UTC (4 years, 5 months ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.134: +4 -4 lines
File MIME type: application/xml
Bug 489782 - Switch links to wiki documents

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.135 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-stage.xml,v 1.134 2013/12/17 10:16:39 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.135 <version>20</version>
17     <date>2013-12-17</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 swift 1.127 your system. The command <c>uname -m</c> can be used to help you decide which
60     stage file to download as it provides information on the architecture of your
61     system.
62 swift 1.12 </p>
63    
64     </body>
65 swift 1.34 </subsection>
66 swift 1.12 </section>
67     <section>
68 swift 1.127 <title>Using a Stage from the Internet</title>
69 swift 1.12 <subsection>
70     <title>Downloading the Stage Tarball</title>
71     <body>
72    
73     <p>
74     Go to the Gentoo mountpoint at which you mounted your filesystems
75     (most likely <path>/mnt/gentoo</path>):
76     </p>
77    
78     <pre caption="Going to the Gentoo mountpoint">
79     # <i>cd /mnt/gentoo</i>
80     </pre>
81    
82     <p>
83     Depending on your installation medium, you have a couple of tools available to
84 fox2mike 1.94 download a stage. If you have <c>links</c> available, then you can immediately
85 swift 1.64 surf to <uri link="/main/en/mirrors.xml">the Gentoo mirrorlist</uri> and
86 jkt 1.123 choose a mirror close to you: type <c>links http://www.gentoo.org/main/en/mirrors.xml</c>
87     and press enter.
88 swift 1.77 </p>
89    
90     <p>
91 fox2mike 1.94 If you don't have <c>links</c> available you should have <c>lynx</c> at your
92 swift 1.77 disposal. If you need to go through a proxy, export the <c>http_proxy</c> and
93     <c>ftp_proxy</c> variables:
94     </p>
95    
96     <pre caption="Setting proxy information for lynx">
97     # <i>export http_proxy="http://proxy.server.com:port"</i>
98     # <i>export ftp_proxy="http://proxy.server.com:port"</i>
99     </pre>
100    
101     <p>
102 fox2mike 1.94 We will now assume that you have <c>links</c> at your disposal.
103 swift 1.64 </p>
104    
105     <p>
106 jkt 1.123 Select a mirror closeby. Usually HTTP mirrors suffice, but other protocols are
107     available as well. Move to the <path><keyval id="release-dir"/></path>
108     directory. There you should see all available stage files for your architecture
109     (they might be stored within subdirectories named after the individual
110     subarchitectures). Select one and press <c>D</c> to download. When you're
111     finished, press <c>Q</c> to quit the browser.
112 neysx 1.105 </p>
113    
114     <p test="'x86'=func:keyval('arch')">
115     Most PC users should use the <b><keyval id="stage3"/></b> stage3 archive. All
116     modern PCs are considered i686. If you use an old machine, you can check the
117     <uri link="http://en.wikipedia.org/wiki/I686">list of i686-compatible
118     processors</uri> on Wikipedia. Old processors such as the Pentium, K5, K6, or
119 nightmorph 1.111 Via C3 and similar require the more generic <b>x86</b> stage3. Processors older
120     than <b>i486</b> are not supported.
121 swift 1.12 </p>
122    
123 fox2mike 1.94 <pre caption="Surfing to the mirror listing with links">
124     # <i>links http://www.gentoo.org/main/en/mirrors.xml</i>
125 swift 1.77
126 fox2mike 1.94 <comment>(If you need proxy support with links:)</comment>
127     # <i>links -http-proxy proxy.server.com:8080 http://www.gentoo.org/main/en/mirrors.xml</i>
128 swift 1.12 </pre>
129    
130 swift 1.32 <p>
131 neysx 1.91 Make sure you download a <b>stage3</b> tarball - installations using a stage1
132 swift 1.127 or stage2 tarball are not supported anymore (and in most cases, you will not
133     find stage1 or stage2 tarballs on our regular download mirrors anyway).
134 swift 1.90 </p>
135    
136     <p>
137 swift 1.32 If you want to check the integrity of the downloaded stage tarball, use
138 swift 1.125 <c>openssl</c> and compare the output with the checksums provided on the
139     mirror. The digests files provide several checksums, each taken with a different
140     algorithm. The recommended ones are SHA512 and Whirlpool.
141 swift 1.32 </p>
142    
143 swift 1.125 <pre caption="Calculating the integrity checksum of a stage tarball">
144     <comment>## Calculating the SHA512 checksum</comment>
145     # <i>openssl dgst -r -sha512 <keyval id="stage3" /></i>
146     <comment>or</comment>
147     # <i>sha512sum <keyval id="stage3" /></i>
148    
149     <comment>## Calculating the Whirlpool checksum</comment>
150     # <i>openssl dgst -r -whirlpool <keyval id="stage3" /></i>
151 swift 1.32 </pre>
152    
153 swift 1.125 <p>
154     Then compare the output of these commands with the value registered in the
155 swift 1.133 <path>.DIGESTS(.asc)</path> files that can be found on the mirrors as well. The values need to
156 swift 1.125 match, otherwise the downloaded file might be corrupt (or the digests file is).
157     </p>
158    
159 swift 1.133 <p>
160     Just like with the ISO file, you can also verify the cryptographic signature of
161     the <path>.DIGESTS.asc</path> file using <c>gpg</c> to make sure the checksums
162     have not been tampered with:
163     </p>
164    
165     <pre caption="Validating the checksums using gpg">
166     # <i>gpg --verify <keyval id="stage3" />.DIGESTS.asc</i>
167     </pre>
168    
169 swift 1.12 </body>
170     </subsection>
171     <subsection>
172     <title>Unpacking the Stage Tarball</title>
173     <body>
174    
175     <p>
176 neysx 1.91 Now unpack your downloaded stage onto your system. We use <c>tar</c> to proceed
177     as it is the easiest method:
178 swift 1.12 </p>
179    
180     <pre caption="Unpacking the stage">
181 neysx 1.91 # <i>tar xvjpf stage3-*.tar.bz2</i>
182 swift 1.12 </pre>
183    
184     <p>
185 neysx 1.91 Make sure that you use the same options (<c>xvjpf</c>). The <c>x</c> stands for
186     <e>Extract</e>, the <c>v</c> for <e>Verbose</e> to see what happens during the
187     extraction process (optional), the <c>j</c> for <e>Decompress with bzip2</e>,
188     the <c>p</c> for <e>Preserve permissions</e> and the <c>f</c> to denote that we
189     want to extract a file, not standard input.
190     </p>
191 swift 1.86
192 neysx 1.105 <!-- MIPS uses its own hb-install-stage.xml file, any other arch?
193 swift 1.79 <note>
194 swift 1.84 Some architectures (e.g. MIPS) Installation CDs and boot images rely upon the
195 neysx 1.91 <c>tar</c> built into BusyBox which doesn't currently support the <c>v</c>
196     option. Use the <c>xjpf</c> options instead.
197 swift 1.79 </note>
198 neysx 1.105 -->
199 swift 1.79
200 swift 1.12 <p>
201 swift 1.34 Now that the stage is installed, continue with <uri
202 swift 1.131 link="#compile_options">Configuring the Compile Options</uri>.
203 swift 1.12 </p>
204    
205     </body>
206     </subsection>
207     </section>
208 swift 1.34
209     <section id="compile_options">
210 swift 1.7 <title>Configuring the Compile Options</title>
211 swift 1.1 <subsection>
212 swift 1.3 <title>Introduction</title>
213 swift 1.1 <body>
214    
215     <p>
216 swift 1.3 To optimize Gentoo, you can set a couple of variables which impact Portage
217     behaviour. All those variables can be set as environment variables (using
218     <c>export</c>) but that isn't permanent. To keep your settings, Portage provides
219 swift 1.124 you with <path>/etc/portage/make.conf</path>, a configuration file for Portage.
220     It is this file we will edit now.
221 swift 1.1 </p>
222    
223 dertobi123 1.27 <note>
224     A commented listing of all possible variables can be found in
225 nightmorph 1.117 <path>/mnt/gentoo/usr/share/portage/config/make.conf.example</path>. For a
226     successful Gentoo installation you'll only need to set the variables which are
227     mentioned beneath.
228 dertobi123 1.27 </note>
229    
230 swift 1.3 <p>
231     Fire up your favorite editor (in this guide we use <c>nano</c>) so we can alter
232 swift 1.57 the optimization variables we will discuss hereafter.
233 swift 1.3 </p>
234    
235 swift 1.124 <pre caption="Opening /etc/portage/make.conf">
236     # <i>nano -w /mnt/gentoo/etc/portage/make.conf</i>
237 swift 1.3 </pre>
238    
239     <p>
240 swift 1.57 As you probably noticed, the <path>make.conf.example</path> file is
241 dertobi123 1.27 structured in a generic way: commented lines start with "#", other lines define
242 swift 1.57 variables using the <c>VARIABLE="content"</c> syntax. The <path>make.conf</path>
243     file uses the same syntax. Several of those variables are discussed next.
244 swift 1.3 </p>
245    
246     </body>
247 swift 1.7 </subsection>
248     <subsection>
249 swift 1.4 <title>CFLAGS and CXXFLAGS</title>
250     <body>
251    
252     <p>
253     The <c>CFLAGS</c> and <c>CXXFLAGS</c> variables define the optimization flags
254     for the <c>gcc</c> C and C++ compiler respectively. Although we define those
255     generally here, you will only have maximum performance if you optimize these
256 swift 1.18 flags for each program separately. The reason for this is because every program
257 swift 1.4 is different.
258     </p>
259    
260     <p>
261     In <path>make.conf</path> you should define the optimization flags you think
262     will make your system the most responsive <e>generally</e>. Don't place
263     experimental settings in this variable; too much optimization can make
264     programs behave bad (crash, or even worse, malfunction).
265     </p>
266    
267     <p>
268     We will not explain all possible optimization options. If you want to know
269 swift 1.43 them all, read the <uri link="http://gcc.gnu.org/onlinedocs/">GNU
270 swift 1.4 Online Manual(s)</uri> or the <c>gcc</c> info page (<c>info gcc</c> -- only
271 swift 1.34 works on a working Linux system). The <path>make.conf.example</path> file
272     itself also contains lots of examples and information; don't forget to read it
273     too.
274 swift 1.4 </p>
275    
276 nightmorph 1.112 <p test="not(contains('AMD64 x86', func:keyval('arch')))">
277 neysx 1.105 A first setting is the <c>-march=</c> or <c>-mcpu=</c> flag, which specifies
278     the name of the target architecture. Possible options are described in the
279 swift 1.126 <path>make.conf.example</path> file (as comments). A commonly used value is
280     <e>native</e> as that tells the compiler to select the target architecture of
281     the current system (the one you are installing on).
282 swift 1.4 </p>
283    
284 nightmorph 1.112 <p test="contains('AMD64 x86',func:keyval('arch'))">
285     A first setting is the <c>-march=</c> or <c>-mtune=</c> flag, which specifies
286     the name of the target architecture. Possible options are described in the
287 swift 1.126 <path>make.conf.example</path> file (as comments). A commonly used value is
288     <e>native</e> as that tells the compiler to select the target architecture of
289     the current system (the one you are installing on).
290 nightmorph 1.112 </p>
291    
292 swift 1.4 <p>
293 neysx 1.48 A second one is the <c>-O</c> flag (that is a capital O, not a zero),
294     which specifies the <c>gcc</c> optimization
295 swift 1.6 class flag. Possible classes are <c>s</c> (for size-optimized),
296 nightmorph 1.116 <c>0</c> (zero - for no optimizations), <c>1</c>, <c>2</c> or even <c>3</c> for more
297 swift 1.4 speed-optimization flags (every class has the same flags as the one before, plus
298 nightmorph 1.116 some extras). <c>-O2</c> is the recommended default. <c>-O3</c> is known to
299     cause problems when used system-wide, so we recommend that you stick to
300     <c>-O2</c>.
301 swift 1.4 </p>
302    
303     <p>
304 swift 1.67 Another popular optimization flag is <c>-pipe</c> (use pipes rather than
305     temporary files for communication between the various stages of compilation).
306 neysx 1.118 It has no impact on the generated code, but uses more memory. On systems with
307     low memory, gcc might get killed. In that case, do not use this flag.
308 swift 1.67 </p>
309    
310     <p>
311 neysx 1.106 Using <c>-fomit-frame-pointer</c> (which doesn't keep the frame pointer in a
312     register for functions that don't need one) might have serious repercussions on
313     the debugging of applications.
314 swift 1.4 </p>
315    
316     <p>
317     When you define the <c>CFLAGS</c> and <c>CXXFLAGS</c>, you should combine
318 nightmorph 1.109 several optimization flags. The default values contained in the stage3 archive
319 swift 1.134 you unpacked should be good enough. The following one is just an example:
320 swift 1.4 </p>
321    
322 nightmorph 1.121 <pre test="not(contains('AMD64 arm', func:keyval('arch')))" caption="Defining the CFLAGS and CXXFLAGS variable">
323 neysx 1.105 CFLAGS="<keyval id="CFLAGS"/>"
324     <comment># Use the same settings for both variables</comment>
325     CXXFLAGS="${CFLAGS}"
326 swift 1.4 </pre>
327    
328 nightmorph 1.103 <pre test="func:keyval('arch')='AMD64'" caption="Defining the CFLAGS and CXXFLAGS variable">
329 nightmorph 1.120 CFLAGS="<keyval id="CFLAGS"/>" <comment># Intel EM64T users should use -march=core2</comment>
330 neysx 1.105 <comment># Use the same settings for both variables</comment>
331     CXXFLAGS="${CFLAGS}"
332 nightmorph 1.102 </pre>
333    
334 nightmorph 1.121 <pre test="func:keyval('arch')='arm'" caption="Defining the CFLAGS and CXXFLAGS variable">
335     CFLAGS="<keyval id="CFLAGS"/> <comment># Be sure to change -march to match your CPU type</comment>
336     <comment># Use the same settings for both variables</comment>
337     CXXFLAGS="${CFLAGS}"
338     </pre>
339    
340 nightmorph 1.116 <note>
341     You may also want to view the <uri
342 swift 1.135 link="https://wiki.gentoo.org/wiki/GCC_optimization">Compilation Optimization Guide</uri> for
343 nightmorph 1.116 more information on how the various compilation options can affect your system.
344     </note>
345    
346 swift 1.4 </body>
347 swift 1.7 </subsection>
348     <subsection>
349 swift 1.4 <title>MAKEOPTS</title>
350     <body>
351    
352 swift 1.6 <p>
353     With <c>MAKEOPTS</c> you define how many parallel compilations should occur when
354 nightmorph 1.122 you install a package. A good choice is the number of CPUs (or CPU cores) in
355     your system plus one, but this guideline isn't always perfect.
356 swift 1.6 </p>
357    
358     <pre caption="MAKEOPTS for a regular, 1-CPU system">
359     MAKEOPTS="-j2"
360     </pre>
361    
362 swift 1.4 </body>
363 swift 1.7 </subsection>
364     <subsection>
365 swift 1.6 <title>Ready, Set, Go!</title>
366 swift 1.4 <body>
367 swift 1.3
368 swift 1.6 <p>
369 swift 1.124 Update your <path>/mnt/gentoo/etc/portage/make.conf</path> to your own preference
370     and save (<c>nano</c> users would hit <c>Ctrl-X</c>). You are now ready to continue
371 swift 1.57 with <uri link="?part=1&amp;chap=6">Installing the Gentoo Base System</uri>.
372 swift 1.8 </p>
373 swift 1.6
374     </body>
375 swift 1.1 </subsection>
376     </section>
377 swift 1.7 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20