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, 1 month ago) by swift
Branch: MAIN
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">
4 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
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 $ -->
9 <sections>
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>
16 <version>20</version>
17 <date>2013-12-17</date>
19 <section>
20 <title>Installing a Stage Tarball</title>
21 <subsection>
22 <title>Setting the Date/Time Right</title>
23 <body>
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>
30 <p>
31 To verify the current date/time, run <c>date</c>:
32 </p>
34 <pre caption="Verifying the date/time">
35 # <i>date</i>
36 Fri Mar 29 16:21:18 UTC 2005
37 </pre>
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>
47 <pre caption="Setting the UTC date/time">
48 # <i>date 032916212005</i>
49 </pre>
51 </body>
52 </subsection>
53 <subsection>
54 <title>Making your Choice</title>
55 <body>
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>
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>
73 <p>
74 Go to the Gentoo mountpoint at which you mounted your filesystems
75 (most likely <path>/mnt/gentoo</path>):
76 </p>
78 <pre caption="Going to the Gentoo mountpoint">
79 # <i>cd /mnt/gentoo</i>
80 </pre>
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>
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>
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>
101 <p>
102 We will now assume that you have <c>links</c> at your disposal.
103 </p>
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>
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>
123 <pre caption="Surfing to the mirror listing with links">
124 # <i>links http://www.gentoo.org/main/en/mirrors.xml</i>
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>
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>
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>
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>
149 <comment>## Calculating the Whirlpool checksum</comment>
150 # <i>openssl dgst -r -whirlpool <keyval id="stage3" /></i>
151 </pre>
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>
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>
165 <pre caption="Validating the checksums using gpg">
166 # <i>gpg --verify <keyval id="stage3" />.DIGESTS.asc</i>
167 </pre>
169 </body>
170 </subsection>
171 <subsection>
172 <title>Unpacking the Stage Tarball</title>
173 <body>
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>
180 <pre caption="Unpacking the stage">
181 # <i>tar xvjpf stage3-*.tar.bz2</i>
182 </pre>
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>
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 -->
200 <p>
201 Now that the stage is installed, continue with <uri
202 link="#compile_options">Configuring the Compile Options</uri>.
203 </p>
205 </body>
206 </subsection>
207 </section>
209 <section id="compile_options">
210 <title>Configuring the Compile Options</title>
211 <subsection>
212 <title>Introduction</title>
213 <body>
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>
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>
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>
235 <pre caption="Opening /etc/portage/make.conf">
236 # <i>nano -w /mnt/gentoo/etc/portage/make.conf</i>
237 </pre>
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>
246 </body>
247 </subsection>
248 <subsection>
249 <title>CFLAGS and CXXFLAGS</title>
250 <body>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
326 </pre>
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>
332 </pre>
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>
338 </pre>
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>
346 </body>
347 </subsection>
348 <subsection>
349 <title>MAKEOPTS</title>
350 <body>
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>
358 <pre caption="MAKEOPTS for a regular, 1-CPU system">
359 MAKEOPTS="-j2"
360 </pre>
362 </body>
363 </subsection>
364 <subsection>
365 <title>Ready, Set, Go!</title>
366 <body>
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>
374 </body>
375 </subsection>
376 </section>
377 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20