/[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 - (show annotations) (download) (as text)
Tue Dec 17 10:38:05 2013 UTC (4 years, 4 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 <?xml version='1.0' encoding='UTF-8'?>
2 <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6
7 <!-- $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
9 <sections>
10
11 <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 <version>20</version>
17 <date>2013-12-17</date>
18
19 <section>
20 <title>Installing a Stage Tarball</title>
21 <subsection>
22 <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 Fri Mar 29 16:21:18 UTC 2005
37 </pre>
38
39 <p>
40 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 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 </p>
46
47 <pre caption="Setting the UTC date/time">
48 # <i>date 032916212005</i>
49 </pre>
50
51 </body>
52 </subsection>
53 <subsection>
54 <title>Making your Choice</title>
55 <body>
56
57 <p>
58 The next step you need to perform is to install the <e>stage3</e> tarball onto
59 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 </p>
63
64 </body>
65 </subsection>
66 </section>
67 <section>
68 <title>Using a Stage from the Internet</title>
69 <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 download a stage. If you have <c>links</c> available, then you can immediately
85 surf to <uri link="/main/en/mirrors.xml">the Gentoo mirrorlist</uri> and
86 choose a mirror close to you: type <c>links http://www.gentoo.org/main/en/mirrors.xml</c>
87 and press enter.
88 </p>
89
90 <p>
91 If you don't have <c>links</c> available you should have <c>lynx</c> at your
92 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 We will now assume that you have <c>links</c> at your disposal.
103 </p>
104
105 <p>
106 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 </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 Via C3 and similar require the more generic <b>x86</b> stage3. Processors older
120 than <b>i486</b> are not supported.
121 </p>
122
123 <pre caption="Surfing to the mirror listing with links">
124 # <i>links http://www.gentoo.org/main/en/mirrors.xml</i>
125
126 <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 </pre>
129
130 <p>
131 Make sure you download a <b>stage3</b> tarball - installations using a stage1
132 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 </p>
135
136 <p>
137 If you want to check the integrity of the downloaded stage tarball, use
138 <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 </p>
142
143 <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 </pre>
152
153 <p>
154 Then compare the output of these commands with the value registered in the
155 <path>.DIGESTS(.asc)</path> files that can be found on the mirrors as well. The values need to
156 match, otherwise the downloaded file might be corrupt (or the digests file is).
157 </p>
158
159 <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 </body>
170 </subsection>
171 <subsection>
172 <title>Unpacking the Stage Tarball</title>
173 <body>
174
175 <p>
176 Now unpack your downloaded stage onto your system. We use <c>tar</c> to proceed
177 as it is the easiest method:
178 </p>
179
180 <pre caption="Unpacking the stage">
181 # <i>tar xvjpf stage3-*.tar.bz2</i>
182 </pre>
183
184 <p>
185 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
192 <!-- MIPS uses its own hb-install-stage.xml file, any other arch?
193 <note>
194 Some architectures (e.g. MIPS) Installation CDs and boot images rely upon the
195 <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 </note>
198 -->
199
200 <p>
201 Now that the stage is installed, continue with <uri
202 link="#compile_options">Configuring the Compile Options</uri>.
203 </p>
204
205 </body>
206 </subsection>
207 </section>
208
209 <section id="compile_options">
210 <title>Configuring the Compile Options</title>
211 <subsection>
212 <title>Introduction</title>
213 <body>
214
215 <p>
216 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 you with <path>/etc/portage/make.conf</path>, a configuration file for Portage.
220 It is this file we will edit now.
221 </p>
222
223 <note>
224 A commented listing of all possible variables can be found in
225 <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 </note>
229
230 <p>
231 Fire up your favorite editor (in this guide we use <c>nano</c>) so we can alter
232 the optimization variables we will discuss hereafter.
233 </p>
234
235 <pre caption="Opening /etc/portage/make.conf">
236 # <i>nano -w /mnt/gentoo/etc/portage/make.conf</i>
237 </pre>
238
239 <p>
240 As you probably noticed, the <path>make.conf.example</path> file is
241 structured in a generic way: commented lines start with "#", other lines define
242 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 </p>
245
246 </body>
247 </subsection>
248 <subsection>
249 <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 flags for each program separately. The reason for this is because every program
257 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 them all, read the <uri link="http://gcc.gnu.org/onlinedocs/">GNU
270 Online Manual(s)</uri> or the <c>gcc</c> info page (<c>info gcc</c> -- only
271 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 </p>
275
276 <p test="not(contains('AMD64 x86', func:keyval('arch')))">
277 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 <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 </p>
283
284 <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 <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 </p>
291
292 <p>
293 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 class flag. Possible classes are <c>s</c> (for size-optimized),
296 <c>0</c> (zero - for no optimizations), <c>1</c>, <c>2</c> or even <c>3</c> for more
297 speed-optimization flags (every class has the same flags as the one before, plus
298 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 </p>
302
303 <p>
304 Another popular optimization flag is <c>-pipe</c> (use pipes rather than
305 temporary files for communication between the various stages of compilation).
306 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 </p>
309
310 <p>
311 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 </p>
315
316 <p>
317 When you define the <c>CFLAGS</c> and <c>CXXFLAGS</c>, you should combine
318 several optimization flags. The default values contained in the stage3 archive
319 you unpacked should be good enough. The following one is just an example:
320 </p>
321
322 <pre test="not(contains('AMD64 arm', func:keyval('arch')))" caption="Defining the CFLAGS and CXXFLAGS variable">
323 CFLAGS="<keyval id="CFLAGS"/>"
324 <comment># Use the same settings for both variables</comment>
325 CXXFLAGS="${CFLAGS}"
326 </pre>
327
328 <pre test="func:keyval('arch')='AMD64'" caption="Defining the CFLAGS and CXXFLAGS variable">
329 CFLAGS="<keyval id="CFLAGS"/>" <comment># Intel EM64T users should use -march=core2</comment>
330 <comment># Use the same settings for both variables</comment>
331 CXXFLAGS="${CFLAGS}"
332 </pre>
333
334 <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 <note>
341 You may also want to view the <uri
342 link="https://wiki.gentoo.org/wiki/GCC_optimization">Compilation Optimization Guide</uri> for
343 more information on how the various compilation options can affect your system.
344 </note>
345
346 </body>
347 </subsection>
348 <subsection>
349 <title>MAKEOPTS</title>
350 <body>
351
352 <p>
353 With <c>MAKEOPTS</c> you define how many parallel compilations should occur when
354 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 </p>
357
358 <pre caption="MAKEOPTS for a regular, 1-CPU system">
359 MAKEOPTS="-j2"
360 </pre>
361
362 </body>
363 </subsection>
364 <subsection>
365 <title>Ready, Set, Go!</title>
366 <body>
367
368 <p>
369 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 with <uri link="?part=1&amp;chap=6">Installing the Gentoo Base System</uri>.
372 </p>
373
374 </body>
375 </subsection>
376 </section>
377 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20