/[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.117 - (show annotations) (download) (as text)
Sun Oct 4 18:37:42 2009 UTC (4 years, 6 months ago) by nightmorph
Branch: MAIN
Changes since 1.116: +11 -23 lines
File MIME type: application/xml
Quick fixes for autobuilds and all stuff (i think) found on the autobuilds tracker bug -- x86 and amd64 only at this time. should be good for Gentoo's 10th anniversary on these two arches

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

  ViewVC Help
Powered by ViewVC 1.1.20