/[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.99 - (show annotations) (download) (as text)
Wed Aug 30 22:52:28 2006 UTC (11 years, 8 months ago) by nightmorph
Branch: MAIN
Changes since 1.98: +8 -8 lines
File MIME type: application/xml
2006.1 networked docs are in. portage handbook still untouched per separate bugs. thanks to all the hard work, guys. blame me if something is wrong (and please fix quickly) :)

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

  ViewVC Help
Powered by ViewVC 1.1.20