/[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.104 - (hide annotations) (download) (as text)
Wed Nov 1 21:40:28 2006 UTC (11 years, 2 months ago) by nightmorph
Branch: MAIN
Changes since 1.103: +3 -3 lines
File MIME type: application/xml
further capitalization of arch keys, bug 153735

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

  ViewVC Help
Powered by ViewVC 1.1.20