/[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.55 - (show annotations) (download) (as text)
Sun Aug 1 10:04:30 2004 UTC (13 years, 11 months ago) by swift
Branch: MAIN
Changes since 1.54: +6 -4 lines
File MIME type: application/xml
#50773 - Add a few phrazes to make it easier for the users to make a choice

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/1.0 -->
6
7 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-stage.xml,v 1.54 2004/07/31 12:42:35 swift Exp $ -->
8
9 <sections>
10 <section>
11 <title>Installing a Stage Tarball</title>
12 <subsection>
13 <title>Setting the Date/Time Right</title>
14 <body>
15
16 <p>
17 Before you continue you need to check your date/time and update it. A
18 misconfigured clock may lead to strange results in the future!
19 </p>
20
21 <p>
22 To verify the current date/time, run <c>date</c>:
23 </p>
24
25 <pre caption="Verifying the date/time">
26 # <i>date</i>
27 Sun Apr 25 16:21:18 CEST 2004
28 </pre>
29
30 <p>
31 If the date/time displayed is wrong, update it using the <c>date
32 MMDDhhmmYYYY</c> syntax (<b>M</b>onth, <b>D</b>ay, <b>h</b>our, <b>m</b>inute
33 and <b>Y</b>ear). For instance, to set the date to April 25th, 16:21 in the
34 year 2004:
35 </p>
36
37 <pre caption="Setting the date/time">
38 # <i>date 042516212004</i>
39 </pre>
40
41 </body>
42 </subsection>
43 <subsection>
44 <title>Making your Choice</title>
45 <body>
46
47 <p>
48 The next step you need to perform is to install the <e>stage</e> tarball of your
49 choice onto your system. You have the option of downloading the required tarball
50 from the Internet or, if you are booted from one of the Gentoo Universal
51 LiveCDs, copy it over from the CD itself. If you have a Universal CD and the
52 stage you want to use is on the CD, downloading it from the Internet is just a
53 waste of bandwidth as the stage files are the same.
54 </p>
55
56 <ul>
57 <li><uri link="#doc_chap2">Default: Using a Stage from the Internet</uri></li>
58 <li><uri link="#doc_chap3">Alternative: Using a Stage from the LiveCD</uri></li>
59 </ul>
60
61 </body>
62 </subsection>
63 </section>
64 <section>
65 <title>Default: Using a Stage from the Internet</title>
66 <subsection>
67 <title>Downloading the Stage Tarball</title>
68 <body>
69
70 <p>
71 Go to the Gentoo mountpoint at which you mounted your filesystems
72 (most likely <path>/mnt/gentoo</path>):
73 </p>
74
75 <pre caption="Going to the Gentoo mountpoint">
76 # <i>cd /mnt/gentoo</i>
77 </pre>
78
79 <p>
80 Depending on your installation medium, you have a couple of tools available to
81 download a stage. If you have <c>lynx</c> available, then you can immediately
82 surf to <uri link="/main/en/mirrors.xml">the Gentoo
83 mirrorlist</uri> and choose a mirror close to you. Then pick the
84 <path>releases/</path> directory, followed by your architecture (for instance
85 <path>x86/</path>) and the Gentoo version (<path>2004.2/</path>)
86 to finish up with the <path>stages/</path> directory. There you should see all
87 available stage files for your architecture. Select one and press <c>D</c> to
88 download. When you're finished, press <c>Q</c> to quit the browser.
89 </p>
90
91 <pre caption="Surfing to the mirror listing with lynx">
92 # <i>lynx http://www.gentoo.org/main/en/mirrors.xml</i>
93 </pre>
94
95 <p>
96 If you do not have <c>lynx</c>, you should have <c>links2</c> at your disposal.
97 <c>links2</c> is more powerful than <c>lynx</c>, but has some drawbacks. One of
98 them is that it doesn't listen to the proxy variables we have declared
99 previously. If you need to setup a proxy, use <c>links2 -http-proxy
100 proxy.server.com:8080</c>. From there on, you should follow the same steps as
101 with <c>lynx</c> as they are equivalent.
102 </p>
103
104 <pre caption="Surfing to the mirror listing with links2">
105 <comment>(Without proxy)</comment> # <i>links2 http://www.gentoo.org/main/en/mirrors.xml</i>
106 <comment>(With proxy)</comment> # <i>links2 -http-proxy proxy.server.com:8080 http://www.gentoo.org/main/en/mirrors.xml</i>
107 </pre>
108
109 <p>
110 If you want to check the integrity of the downloaded stage tarball, use
111 <c>md5sum</c> and compare the output with the MD5 checksum provided on the
112 mirror. For instance, to check the validity of the x86 stage tarball:
113 </p>
114
115 <pre caption="Example checking integrity of a stage tarball">
116 # <i>md5sum -c stage1-x86-2004.2.tar.bz2.md5</i>
117 stage1-x86-2004.2.tar.bz2: OK
118 </pre>
119
120 </body>
121 </subsection>
122 <subsection>
123 <title>Unpacking the Stage Tarball</title>
124 <body>
125
126 <p>
127 Now unpack your downloaded stage onto your system. We use GNU's <c>tar</c> to
128 proceed as it is the easiest method:
129 </p>
130
131 <pre caption="Unpacking the stage">
132 # <i>tar -xvjpf stage?-*.tar.bz2</i>
133 </pre>
134
135 <note>
136 You can ignore any "No such file or directory" warnings regarding ./proc. Also,
137 the message "Error exit delayed from previous errors" can be ignored as well.
138 </note>
139
140 <p>
141 Make sure that you use the same options (<c>-xvjpf</c>). The <c>x</c> stands for
142 <e>Extract</e>, the <c>v</c> for <e>Verbose</e> (okay, yes, this is optional),
143 the <c>j</c> for <e>Decompress with bzip2</e>, the <c>p</c> for <e>Preserve
144 permissions</e> and the <c>f</c> to denote that we want to extract a file, not
145 standard input.
146 </p>
147
148 <p>
149 Now that the stage is installed, continue with <uri
150 link="#installing_portage">Installing Portage</uri>.
151 </p>
152
153 </body>
154 </subsection>
155 </section>
156 <section>
157 <title>Alternative: Using a Stage from the LiveCD</title>
158 <subsection>
159 <title>Extracting the Stage Tarball</title>
160 <body>
161
162 <p>
163 The stages on the CD reside in the <path>/mnt/cdrom/stages</path> directory. To
164 see a listing of available stages, use <c>ls</c>:
165 </p>
166
167 <pre caption="List all available stages">
168 # <i>ls /mnt/cdrom/stages</i>
169 </pre>
170
171 <p>
172 If the system replies with an error, you may need to mount the CD-ROM first:
173 </p>
174
175 <pre caption="Mounting the CD-ROM">
176 # <i>ls /mnt/cdrom/stages</i>
177 ls: /mnt/cdrom/stages: No such file or directory
178 # <i>mount /dev/cdroms/cdrom0 /mnt/cdrom</i>
179 # <i>ls /mnt/cdrom/stages</i>
180 </pre>
181
182 <p>
183 Now go into your Gentoo mountpoint (usually <path>/mnt/gentoo</path>):
184 </p>
185
186 <pre caption="Changing directory to /mnt/gentoo">
187 # <i>cd /mnt/gentoo</i>
188 </pre>
189
190 <p>
191 We will now extract the stage tarball of your choice. We will do this with the
192 GNU <c>tar</c> tool. Make sure you use the same options (<c>-xvjpf</c>)! In the
193 next example, we extract the stage tarball
194 <path>stage3-&lt;subarch&gt;-2004.2.tar.bz2</path>.
195 Be sure to substitute the tarball filename with your stage.
196 </p>
197
198 <pre caption="Extracting the stage tarball">
199 # <i>tar -xvjpf /mnt/cdrom/stages/stage3-&lt;subarch&gt;-2004.2.tar.bz2</i>
200 </pre>
201
202 <note>
203 You can ignore any "No such file or directory" warnings regarding ./proc. Also,
204 the message "Error exit delayed from previous errors" can be ignored as well.
205 </note>
206
207 <p>
208 Now that the stage is installed, continue with <uri
209 link="#installing_portage">Installing Portage</uri>.
210 </p>
211
212 </body>
213 </subsection>
214 </section>
215 <section id="installing_portage">
216 <title>Installing Portage</title>
217 <subsection>
218 <title>Network or No Network?</title>
219 <body>
220
221 <p>
222 If you don't have a working network connection, you have to install a portage
223 snapshot provided by one of our LiveCDs. This automatically assumes that you are
224 installing from a <e>stage3</e> tarball (as it is the only tarball supported for
225 networkless installations). If you want to use prebuilt packages
226 later on to speed up the installation, you <e>must</e> use a portage snapshot
227 from the LiveCD. Other users will download a fully updated Portage tree using
228 <c>emerge</c> in the next chapter.
229 </p>
230
231 <p>
232 Continue with the appropriate part:
233 </p>
234
235 <ul>
236 <li>
237 <uri link="#installing_from_LiveCD">Installing a Portage Snapshot and
238 Source Code from LiveCD</uri> (for networkless installations or GRP
239 installations)
240 </li>
241 <li>
242 <uri link="#compile_options">Configuring the Compile Options</uri> (all
243 other installation methods)
244 </li>
245 </ul>
246
247 </body>
248 </subsection>
249 <subsection id="installing_from_LiveCD">
250 <title>Installing a Portage Snapshot and Source Code from LiveCD</title>
251 <body>
252
253 <p>
254 There is a Portage snapshot available on the Universal LiveCDs. Since you are
255 reading this, we can safely assume you are using such a LiveCD. To install this
256 snapshot, take a look inside <path>/mnt/cdrom/snapshots/</path> to see what
257 snapshot we have available:
258 </p>
259
260 <pre caption="Checking the /mnt/cdrom/snapshots content">
261 # <i>ls /mnt/cdrom/snapshots</i>
262 </pre>
263
264 <p>
265 Now extract the snapshot using the following construct. Again,
266 make sure you use the correct options to <c>tar</c>. Also, the <c>-C</c> is with
267 a capital <c>C</c>, not <c>c</c>. In the next example we use
268 <path>portage-20040710.tar.bz2</path> as the snapshot filename. Be sure to
269 substitute with your snapshot.
270 </p>
271
272 <pre caption="Extracting a Portage snapshot">
273 # <i>tar -xvjf /mnt/cdrom/snapshots/portage-20040710.tar.bz2 -C /mnt/gentoo/usr</i>
274 </pre>
275
276 <p>
277 You also need to copy over all source code from the CD:
278 </p>
279
280 <pre caption="Copy over source code">
281 # <i>mkdir /mnt/gentoo/usr/portage/distfiles</i>
282 # <i>cp /mnt/cdrom/distfiles/* /mnt/gentoo/usr/portage/distfiles/</i>
283 </pre>
284
285 <p>
286 Now that your Portage snapshot is installed, continue with <uri
287 link="#compile_options">Configuring the Compile Options</uri>.
288 </p>
289
290 </body>
291 </subsection>
292 </section>
293
294 <section id="compile_options">
295 <title>Configuring the Compile Options</title>
296 <subsection>
297 <title>Introduction</title>
298 <body>
299
300 <p>
301 To optimize Gentoo, you can set a couple of variables which impact Portage
302 behaviour. All those variables can be set as environment variables (using
303 <c>export</c>) but that isn't permanent. To keep your settings, Portage provides
304 you with <path>/etc/make.conf</path>, a configuration file for Portage. It is
305 this file we will edit now.
306 </p>
307
308 <note>
309 A commented listing of all possible variables can be found in
310 <path>/mnt/gentoo/etc/make.conf.example</path>. For a successful Gentoo
311 installation you'll only need to set the variables which are mentioned beneath.
312 </note>
313
314 <p>
315 Fire up your favorite editor (in this guide we use <c>nano</c>) so we can alter
316 the optimization variables we will discuss hereafter.
317 </p>
318
319 <pre caption="Opening /etc/make.conf">
320 # <i>nano -w /mnt/gentoo/etc/make.conf</i>
321 </pre>
322
323 <p>
324 As you probably notice now, the <path>make.conf.example</path> file is
325 structured in a generic way: commented lines start with "#", other lines define
326 variables using the <c>VARIABLE="content"</c> syntax. Several of those
327 variables are discussed next.
328 </p>
329
330 </body>
331 </subsection>
332 <subsection>
333 <title>CHOST</title>
334 <body>
335
336 <warn>
337 Although it might be tempting for non-stage1 users, they should <e>not</e>
338 change the <c>CHOST</c> setting in <path>make.conf</path>. Doing so might render
339 their system unusable. Again: only change this variable if you use a
340 <e>stage1</e> installation.
341 </warn>
342
343 <p>
344 The <c>CHOST</c> variable defines what architecture <c>gcc</c> has to
345 compile programs for. The possibilities are:
346 </p>
347
348 <table>
349 <tr>
350 <th>Architecture</th>
351 <th>Subarchitecture</th>
352 <th>CHOST Setting</th>
353 </tr>
354 <tr>
355 <ti>x86</ti>
356 <ti>i386</ti>
357 <ti>i386-pc-linux-gnu</ti>
358 </tr>
359 <tr>
360 <ti>x86</ti>
361 <ti>i486</ti>
362 <ti>i486-pc-linux-gnu</ti>
363 </tr>
364 <tr>
365 <ti>x86</ti>
366 <ti>i586</ti>
367 <ti>i586-pc-linux-gnu</ti>
368 </tr>
369 <tr>
370 <ti>x86</ti>
371 <ti>i686 and above (incl. athlon)</ti>
372 <ti>i686-pc-linux-gnu</ti>
373 </tr>
374 <tr>
375 <ti>alpha</ti>
376 <ti></ti>
377 <ti>alpha-unknown-linux-gnu</ti>
378 </tr>
379 <tr>
380 <ti>ppc</ti>
381 <ti></ti>
382 <ti>powerpc-unknown-linux-gnu</ti>
383 </tr>
384 <tr>
385 <ti>sparc</ti>
386 <ti></ti>
387 <ti>sparc-unknown-linux-gnu</ti>
388 </tr>
389 <tr>
390 <ti>hppa</ti>
391 <ti>(generic)</ti>
392 <ti>hppa-unknown-linux-gnu</ti>
393 </tr>
394 <tr>
395 <ti>hppa</ti>
396 <ti>pa7000</ti>
397 <ti>hppa1.1-unknown-linux-gnu</ti>
398 </tr>
399 <tr>
400 <ti>hppa</ti>
401 <ti>pa8000 and above</ti>
402 <ti>hppa2.0-unknown-linux-gnu</ti>
403 </tr>
404 <tr>
405 <ti>mips</ti>
406 <ti></ti>
407 <ti>mips-unknown-linux-gnu</ti>
408 </tr>
409 <tr>
410 <ti>amd64</ti>
411 <ti></ti>
412 <ti>x86_64-pc-linux-gnu</ti>
413 </tr>
414 </table>
415
416 <p>
417 If you have altered the CHOST variable you will need to reload the environment
418 variables:
419 </p>
420
421 <pre caption="Reloading the environment variables">
422 # <i>env-update</i>
423 # <i>source /etc/profile</i>
424 </pre>
425
426 </body>
427 </subsection>
428 <subsection>
429 <title>CFLAGS and CXXFLAGS</title>
430 <body>
431
432 <p>
433 The <c>CFLAGS</c> and <c>CXXFLAGS</c> variables define the optimization flags
434 for the <c>gcc</c> C and C++ compiler respectively. Although we define those
435 generally here, you will only have maximum performance if you optimize these
436 flags for each program separately. The reason for this is because every program
437 is different.
438 </p>
439
440 <p>
441 In <path>make.conf</path> you should define the optimization flags you think
442 will make your system the most responsive <e>generally</e>. Don't place
443 experimental settings in this variable; too much optimization can make
444 programs behave bad (crash, or even worse, malfunction).
445 </p>
446
447 <p>
448 We will not explain all possible optimization options. If you want to know
449 them all, read the <uri link="http://gcc.gnu.org/onlinedocs/">GNU
450 Online Manual(s)</uri> or the <c>gcc</c> info page (<c>info gcc</c> -- only
451 works on a working Linux system). The <path>make.conf.example</path> file
452 itself also contains lots of examples and information; don't forget to read it
453 too.
454 </p>
455
456 <p>
457 A first setting is the <c>-march=</c> flag, which specifies the name of the
458 target architecture. Possible options are described in the
459 <path>make.conf.example</path> file (as comments). For instance, for the x86
460 Athlon XP architecture:
461 </p>
462
463 <pre caption="The GCC march setting">
464 <comment># AMD64 users who want to use a native 64 bit system should not use athlon-xp</comment>
465 -march=athlon-xp
466 </pre>
467
468 <p>
469 A second one is the <c>-O</c> flag (that is a capital O, not a zero),
470 which specifies the <c>gcc</c> optimization
471 class flag. Possible classes are <c>s</c> (for size-optimized),
472 <c>0</c> (zero - for no optimizations), <c>1</c>, <c>2</c> or <c>3</c> for more
473 speed-optimization flags (every class has the same flags as the one before, plus
474 some extras). For instance, for a class-2 optimization:
475 </p>
476
477 <pre caption="The GCC O setting">
478 -O2
479 </pre>
480
481 <p>
482 Other popular optimization flags are <c>-pipe</c> (use pipes rather than
483 temporary files for communication between the various stages of compilation) and
484 <c>-fomit-frame-pointer</c> (which doesn't keep the frame pointer in a register
485 for functions that don't need one).
486 </p>
487
488 <p>
489 When you define the <c>CFLAGS</c> and <c>CXXFLAGS</c>, you should combine
490 several optimization flags, like in the following example:
491 </p>
492
493 <pre caption="Defining the CFLAGS and CXXFLAGS variable">
494 CFLAGS="-march=athlon-xp -pipe -O2" <comment># AMD64 users should not use athlon-xp</comment>
495 CXXFLAGS="${CFLAGS}" <comment># Use the same settings for both variables</comment>
496 </pre>
497
498 </body>
499 </subsection>
500 <subsection>
501 <title>MAKEOPTS</title>
502 <body>
503
504 <p>
505 With <c>MAKEOPTS</c> you define how many parallel compilations should occur when
506 you install a package. The suggested number is the number of CPUs in your system
507 plus one.
508 </p>
509
510 <pre caption="MAKEOPTS for a regular, 1-CPU system">
511 MAKEOPTS="-j2"
512 </pre>
513
514 </body>
515 </subsection>
516 <subsection>
517 <title>Ready, Set, Go!</title>
518 <body>
519
520 <p>
521 Update your <path>/mnt/gentoo/etc/make.conf</path> to your own will and save.
522 You are now ready to continue with <uri link="?part=1&amp;chap=6">Installing the
523 Gentoo Base System</uri>.
524 </p>
525
526 </body>
527 </subsection>
528 </section>
529 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20