/[gentoo]/xml/htdocs/doc/en/handbook/hb-install-system.xml
Gentoo

Contents of /xml/htdocs/doc/en/handbook/hb-install-system.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.76 - (hide annotations) (download) (as text)
Sat Apr 9 10:05:13 2005 UTC (9 years ago) by swift
Branch: MAIN
Changes since 1.75: +7 -5 lines
File MIME type: application/xml
#88397 - Added explanation that the change in USE flag is wrt to the USE flag used while building stage2 by releng

1 swift 1.26 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3    
4 swift 1.6 <!-- 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 swift 1.76 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-system.xml,v 1.75 2005/04/07 11:46:12 swift Exp $ -->
8 swift 1.11
9 swift 1.3 <sections>
10 swift 1.56
11 swift 1.76 <version>2.4</version>
12     <date>2005-04-09</date>
13 swift 1.56
14 swift 1.1 <section>
15 swift 1.3 <title>Chrooting</title>
16 swift 1.1 <subsection>
17 swift 1.2 <title>Optional: Selecting Mirrors</title>
18     <body>
19    
20     <p>
21 swift 1.70 In order to download source code quickly it is recommended to select a fast
22     mirror. Portage will look in your <path>make.conf</path> file for the
23     GENTOO_MIRRORS variable and use the mirrors listed therein. You can surf to
24     our <uri link="/main/en/mirrors.xml">mirror list</uri> and search
25     for a mirror (or mirrors) close to you (as those are most frequently the
26     fastest ones), but we provide a nice tool called <c>mirrorselect</c> which
27     provides you with a nice interface to select the mirrors you want.
28     </p>
29    
30     <pre caption="Using mirrorselect for the GENTOO_MIRRORS variable">
31     # <i>mirrorselect -i -o &gt;&gt; /mnt/gentoo/etc/make.conf</i>
32     </pre>
33    
34 swift 1.71 <warn>
35     Do not select any IPv6 mirrors. Our stages currently do not support IPv6.
36     </warn>
37    
38 swift 1.70 <p>
39     A second important setting is the SYNC setting in <path>make.conf</path>. This
40     variable contains the rsync server you want to use when updating your Portage
41     tree (the collection of ebuilds, scripts containing all the information Portage
42     needs to download and install software). Although you can manually enter a SYNC
43     server for yourself, <c>mirrorselect</c> can ease that operation for you:
44 swift 1.2 </p>
45    
46 swift 1.70 <pre caption="Selecting an rsync mirror using mirrorselect">
47     # <i>mirrorselect -i -r -o &gt;&gt; /mnt/gentoo/etc/make.conf</i>
48 swift 1.2 </pre>
49    
50     <p>
51 swift 1.70 After running <c>mirrorselect</c> it is adviseable to double-check the settings
52     in <path>/mnt/gentoo/etc/make.conf</path> !
53 swift 1.2 </p>
54    
55     </body>
56 swift 1.3 </subsection>
57     <subsection>
58 swift 1.5 <title>Copy DNS Info</title>
59     <body>
60    
61     <p>
62 swift 1.24 One thing still remains to be done before we enter the new environment and that
63     is copying over the DNS information in <path>/etc/resolv.conf</path>. You need
64 swift 1.5 to do this to ensure that networking still works even after entering the new
65     environment. <path>/etc/resolv.conf</path> contains the nameservers for your
66     network.
67     </p>
68    
69     <pre caption="Copy over DNS information">
70 swift 1.35 <comment>(The "-L" option is needed to make sure we don't copy a symbolic link)</comment>
71     # <i>cp -L /etc/resolv.conf /mnt/gentoo/etc/resolv.conf</i>
72 swift 1.18 </pre>
73    
74     </body>
75     </subsection>
76     <subsection>
77 swift 1.43 <title>Mounting the proc Filesystem</title>
78     <body>
79    
80     <p>
81     Mount the <path>/proc</path> filesystem on <path>/mnt/gentoo/proc</path> to
82     allow the installation to use the kernel-provided information even within the
83     chrooted environment.
84     </p>
85    
86     <pre caption="Mounting /proc">
87     # <i>mount -t proc none /mnt/gentoo/proc</i>
88     </pre>
89    
90     </body>
91     </subsection>
92     <subsection>
93 swift 1.2 <title>Entering the new Environment</title>
94 swift 1.1 <body>
95    
96     <p>
97 swift 1.19 Now that all partitions are initialized and the base environment
98 swift 1.1 installed, it is time to enter our new installation environment by
99 swift 1.9 <e>chrooting</e> into it. This means that we change from the current
100 swift 1.72 installation environment (Installation CD or other installation medium) to your
101 swift 1.19 installation system (namely the initialized partitions).
102 swift 1.1 </p>
103    
104     <p>
105     This chrooting is done in three steps. First we will change the root
106 swift 1.2 from <path>/</path> (on the installation medium) to <path>/mnt/gentoo</path>
107     (on your partitions) using <c>chroot</c>. Then we will create a new environment
108     using <c>env-update</c>, which essentially creates environment variables.
109 swift 1.1 Finally, we load those variables into memory using <c>source</c>.
110     </p>
111    
112     <pre caption = "Chrooting into the new environment">
113     # <i>chroot /mnt/gentoo /bin/bash</i>
114     # <i>env-update</i>
115 neysx 1.39 * Caching service dependencies...
116 swift 1.1 # <i>source /etc/profile</i>
117     </pre>
118    
119     <p>
120     Congratulations! You are now inside your own Gentoo Linux environment.
121 swift 1.10 Of course it is far from finished, which is why the installation still
122 swift 1.1 has some sections left :-)
123     </p>
124    
125     </body>
126 swift 1.3 </subsection>
127     <subsection>
128 swift 1.64 <title>Updating the Portage tree</title>
129 swift 1.2 <body>
130    
131     <p>
132 swift 1.69 You should now update your Portage tree to the latest version. <c>emerge
133     --sync</c> does this for you.
134 swift 1.2 </p>
135    
136 dertobi123 1.40 <pre caption="Updating the Portage tree">
137 cam 1.50 # <i>emerge --sync</i>
138 swift 1.13 </pre>
139    
140     <p>
141 swift 1.75 If you are behind a firewall that blocks rsync traffic, you can use
142     <c>emerge-webrsync</c> which will download and install a portage snapshot for
143     you.
144     </p>
145    
146     <p>
147 swift 1.13 If you are warned that a new Portage version is available and that you should
148 swift 1.34 update Portage, you should ignore it. Portage will be updated for you later
149 bennyc 1.16 on during the installation.
150 swift 1.13 </p>
151 swift 1.8
152     </body>
153     </subsection>
154 swift 1.72 <subsection>
155     <title>Choosing the Right Profile</title>
156     <body>
157    
158     <p>
159     First, a small definition is in place.
160     </p>
161    
162     <p>
163     A profile is a building block for any Gentoo system. Not only does it specify
164     default values for CHOST, CFLAGS and other important variables, it also locks
165     the system to a certain range of package versions. This is all maintained by the
166     Gentoo developers.
167     </p>
168    
169     <p>
170     Previously, such a profile was barely touched by the user. However, recently,
171     x86, hppa and alpha users can choose between two profiles, one for a 2.4 kernel
172     and one for a 2.6 kernel. This requirement has been imposed to improve the
173     integration of the 2.6 kernels.
174     </p>
175    
176     <p>
177     You can see what profile you are currently using by issuing the following
178     command:
179     </p>
180    
181     <pre caption="Verifying system profile">
182     # <i>ls -l /etc/make.profile</i>
183     lrwxrwxrwx 1 root root 48 Mar 7 11:55 /etc/make.profile ->
184     ../usr/portage/profiles/default-linux/x86/2005.0
185     </pre>
186    
187     <p>
188     If you are using one of the abovementioned three architectures, you will see an
189     additional profile in the one listed by the <path>make.profile</path> symlink:
190     </p>
191    
192     <pre caption="Finding out if an additional profile exists">
193     # <i>ls -F /etc/make.profile/</i>
194     2.4/ packages parent virtuals
195     </pre>
196    
197     <p>
198     As you can see, in the above example there is a 2.4 subdirectory. This means
199     that the current profile uses the 2.6 kernel; if you want a 2.4-based system,
200     you need to relink your <path>make.profile</path> symlink:
201     </p>
202    
203     <pre caption="Relinking the profile">
204     # <i>ln -snf /usr/portage/profiles/default-linux/x86/2005.0/2.4 /etc/make.profile</i>
205     </pre>
206    
207     </body>
208     </subsection>
209 swift 1.28 <subsection id="configure_USE">
210 swift 1.21 <title>Configuring the USE variable</title>
211     <body>
212    
213     <p>
214     <c>USE</c> is one of the most powerful variables Gentoo provides to its users.
215     Several programs can be compiled with or without optional support for certain
216     items. For instance, some programs can be compiled with gtk-support, or with
217     qt-support. Others can be compiled with or without SSL support. Some programs
218     can even be compiled with framebuffer support (svgalib) instead of X11 support
219     (X-server).
220     </p>
221    
222     <p>
223     Most distributions compile their packages with support for as much as possible,
224     increasing the size of the programs and startup time, not to mention an enormous
225 swift 1.24 amount of dependencies. With Gentoo you can define what options a package
226 swift 1.21 should be compiled with. This is where <c>USE</c> comes into play.
227     </p>
228    
229     <p>
230     In the <c>USE</c> variable you define keywords which are mapped onto
231     compile-options. For instance, <e>ssl</e> will compile ssl-support in the
232     programs that support it. <e>-X</e> will remove X-server support (note the minus
233     sign in front). <e>gnome gtk -kde -qt</e> will compile your programs with gnome
234     (and gtk) support, and not with kde (and qt) support, making your system fully
235     tweaked for GNOME.
236     </p>
237    
238     <p>
239 swift 1.68 The default <c>USE</c> settings are placed in the <path>make.defaults</path>
240     files of your profile. You will find <path>make.defaults</path> files in the
241     directory which <path>/etc/make.profile</path> points to and all parent
242     directories as well. The default <c>USE</c> setting is the sum of all <c>USE</c>
243     settings in all <path>make.defaults</path> files. What you place in
244 swift 1.21 <path>/etc/make.conf</path> is calculated against these defaults settings. If
245     you add something to the <c>USE</c> setting, it is added to the default list. If
246     you remove something from the <c>USE</c> setting (by placing a minus sign in
247     front of it) it is removed from the default list (if it was in the default list
248     at all). <e>Never</e> alter anything inside the <path>/etc/make.profile</path>
249     directory; it gets overwritten when you update Portage!
250     </p>
251    
252     <p>
253     A full description on <c>USE</c> can be found in the second part of the Gentoo
254 neysx 1.52 Handbook, <uri link="?part=2&amp;chap=2">USE flags</uri>. A full description on
255     the available USE flags can be found on your system in
256 swift 1.23 <path>/usr/portage/profiles/use.desc</path>.
257     </p>
258    
259     <pre caption="Viewing available USE flags">
260     # <i>less /usr/portage/profiles/use.desc</i>
261 swift 1.45 <comment>(You can scroll using your arrow keys, exit by pressing 'q')</comment>
262 swift 1.23 </pre>
263    
264     <p>
265     As an example we show a <c>USE</c> setting for a KDE-based system with DVD, ALSA
266     and CD Recording support:
267 swift 1.21 </p>
268    
269     <pre caption="Opening /etc/make.conf">
270     # <i>nano -w /etc/make.conf</i>
271     </pre>
272    
273     <pre caption="USE setting">
274     USE="-gtk -gnome qt kde dvd alsa cdr"
275     </pre>
276    
277 swift 1.69 </body>
278     </subsection>
279     <subsection>
280     <title>Optional: GLIBC Locales</title>
281     <body>
282    
283 dertobi123 1.53 <p>
284     You will probably only use one or maybe two locales on your system. Up until now
285 swift 1.55 after compiling <c>glibc</c> a full set of all available locales will be
286     created. As of now you can activate the <c>userlocales</c> USE flag and specify
287 swift 1.67 only the locales you will need in <path>/etc/locales.build</path>. Only do this
288 swift 1.74 if you know what locales to choose. This will not work for the bootstrapping,
289     but when you recompile glibc afterwards it will.
290 dertobi123 1.53 </p>
291    
292     <pre caption="Activate the userlocales USE flag especially for glibc">
293 swift 1.54 # <i>mkdir /etc/portage</i>
294     # <i>echo "sys-libs/glibc userlocales" >> /etc/portage/package.use</i>
295 dertobi123 1.53 </pre>
296    
297     <p>
298     Now specify the locales you want to be able to use:
299     </p>
300    
301 bennyc 1.60 <pre caption="Opening /etc/locales.build">
302 neysx 1.61 # <i>nano -w /etc/locales.build</i>
303 bennyc 1.60 </pre>
304    
305 swift 1.67 <p>
306     The following locales are an example to get both English (United States) and
307     German (Germany) with the accompanying character formats (like UTF-8).
308     </p>
309    
310 bennyc 1.60 <pre caption="Specify your locales">
311 dertobi123 1.53 en_US/ISO-8859-1
312     en_US.UTF-8/UTF-8
313     de_DE/ISO-8859-1
314     de_DE@euro/ISO-8859-15
315     </pre>
316    
317 swift 1.21 </body>
318     </subsection>
319 swift 1.3 </section>
320     <section>
321 swift 1.1 <title>Differences between Stage1, Stage2 and Stage3</title>
322     <body>
323    
324     <p>
325     Now take a seat and think of your previous steps. We asked you to
326     select a <e>stage1</e>, <e>stage2</e> or <e>stage3</e> and warned you
327     that your choice is important for further installation steps. Well, this
328 neysx 1.48 is the first place where your choice defines the subsequent steps.
329 swift 1.1 </p>
330    
331     <ul>
332     <li>
333 swift 1.4 If you chose <e>stage1</e>, then you have to follow <e>both</e> steps in
334     this chapter (starting with <uri link="#doc_chap3">Progressing from Stage1
335     to Stage2</uri>)
336 swift 1.1 </li>
337     <li>
338 swift 1.4 If you chose <e>stage2</e> you only can skip the first step
339     and immediately start with the second one (<uri link="#doc_chap4">Progressing
340     from Stage2 to Stage3</uri>)
341 swift 1.1 </li>
342     <li>
343 swift 1.69 If you chose <e>stage3</e> then you can skip both
344 swift 1.31 steps and continue with <uri link="?part=1&amp;chap=7">Configuring the
345     Kernel</uri>
346 swift 1.1 </li>
347     </ul>
348    
349     </body>
350 swift 1.3 </section>
351     <section>
352     <title>Progressing from Stage1 to Stage2</title>
353 swift 1.1 <subsection>
354     <title>Introduction to Bootstrapping</title>
355     <body>
356    
357     <p>
358     So, you want to compile everything from scratch? Okay then :-)
359     </p>
360    
361     <p>
362     In this step, we will <e>bootstrap</e> your Gentoo system. This takes a
363     long time, but the result is a system that has been optimized from the
364     ground up for your specific machine and needs.
365     </p>
366    
367     <p>
368     <e>Bootstrapping</e> means building the GNU C Library, GNU Compiler
369 swift 1.32 Collection and several other key system programs.
370 swift 1.1 </p>
371    
372     <p>
373 swift 1.62 Before starting the bootstrap, you might want to download all necessary
374     sourcecode first. If you do not want to do this, continue
375     with <uri link="#bootstrap">Bootstrapping the System</uri>.
376 swift 1.1 </p>
377    
378     </body>
379 swift 1.3 </subsection>
380     <subsection>
381 swift 1.1 <title>Optional: Downloading the Sources First</title>
382     <body>
383    
384     <p>
385 swift 1.25 If you haven't copied over all source code before, then the bootstrap
386 swift 1.69 script will download all necessary files. If you want to
387 swift 1.25 download the source code first and later bootstrap the system (for instance
388 swift 1.1 because you don't want to have your internet connection open during the
389     compilation) use the <e>-f</e> option of the bootstrap script, which will
390 swift 1.25 fetch (hence the letter <e>f</e>) all source code for you.
391 swift 1.1 </p>
392    
393     <pre caption = "Downloading the necessary sources">
394     # <i>cd /usr/portage</i>
395 swift 1.47 # <i>scripts/bootstrap.sh -f</i>
396 swift 1.1 </pre>
397    
398     </body>
399 swift 1.3 </subsection>
400 swift 1.41 <subsection id="bootstrap">
401 swift 1.1 <title>Bootstrapping the System</title>
402     <body>
403    
404     <p>
405     Okay then, take your keyboard and punch in the next commands to start
406 swift 1.36 the bootstrap. Then go amuse yourself with something else because this step
407     takes quite some time to finish.
408 swift 1.1 </p>
409    
410     <pre caption = "Bootstrapping the system">
411     # <i>cd /usr/portage</i>
412 swift 1.47 # <i>scripts/bootstrap.sh</i>
413 swift 1.12 </pre>
414    
415     <p>
416 swift 1.4 Now continue with the next step, <uri link="#doc_chap4">Progressing from Stage2
417     to Stage3</uri>.
418     </p>
419    
420 swift 1.1 </body>
421     </subsection>
422 swift 1.3 </section>
423     <section>
424     <title>Progressing from Stage2 to Stage3</title>
425 swift 1.1 <subsection>
426     <title>Introduction</title>
427     <body>
428    
429     <p>
430     If you are reading this section, then you have a bootstrapped system
431     (either because you bootstrapped it previously, or you are using a
432     <e>stage2</e>). Then it is now time to build all system packages.
433     </p>
434    
435     <p>
436     <e>All</e> system packages? No, not really. In this step, you will build
437 swift 1.19 the system packages of which there are no alternatives to use.
438     Some system packages have several alternatives (such as system loggers)
439 swift 1.1 and as Gentoo is all about choices, we don't want to force one upon you.
440     </p>
441    
442     </body>
443 swift 1.3 </subsection>
444     <subsection>
445 swift 1.1 <title>Optional: Viewing what will be done</title>
446     <body>
447    
448     <p>
449     If you want to know what packages will be installed, execute <c>emerge
450 swift 1.72 --pretend --emptytree system</c>. This will list all packages that will be
451     built. As this list is pretty big, you should also use a pager like
452     <c>less</c> or <c>more</c> to go up and down the list.
453 swift 1.1 </p>
454    
455     <pre caption = "View what 'emerge system' will do">
456 swift 1.72 # <i>emerge --pretend --emptytree system | less</i>
457 swift 1.1 </pre>
458    
459 swift 1.72 <p>
460     Note that, if you haven't touched the default CFLAGS/CXXFLAGS setting, using
461 swift 1.76 <c>emerge --pretend --newuse system</c> is sufficient: it will rebuild the
462     applications that are affected by a change in USE flags (compared to the USE
463     flag we used while building the stage2). If you didn't touch
464     the USE flag either, why are you running a stage2 installation then?
465 swift 1.72 </p>
466    
467 swift 1.1 </body>
468 swift 1.3 </subsection>
469     <subsection>
470 swift 1.4 <title>Optional: Downloading the Sources</title>
471 swift 1.1 <body>
472    
473     <p>
474     If you want <c>emerge</c> to download the sources before you continue
475     (for instance because you don't want the internet connection to be left
476 swift 1.20 open while you are building all packages) you can use the <e>--fetchonly</e>
477 swift 1.1 option of <c>emerge</c> which will fetch all sources for you.
478     </p>
479    
480     <pre caption = "Fetching the sources">
481 swift 1.72 # <i>emerge --fetchonly --emptytree system</i>
482 swift 1.1 </pre>
483    
484     </body>
485 swift 1.3 </subsection>
486     <subsection>
487 swift 1.1 <title>Building the System</title>
488     <body>
489    
490     <p>
491 swift 1.72 To start building the system, execute <c>emerge --emptytree system</c>. Then
492     go do something to keep your mind busy, because this step takes a long time to
493 swift 1.4 complete.
494 swift 1.1 </p>
495    
496     <pre caption = "Building the System">
497 swift 1.72 # <i>emerge --emptytree system</i>
498 swift 1.1 </pre>
499    
500     <p>
501 swift 1.72 Again, if you haven't touched the default CFLAGS and CXXFLAGS setting, using
502     <c>--newuse</c> is sufficient.
503     </p>
504    
505     <p>
506 swift 1.30 You can for now safely ignore any warnings about updated configuration files
507     (and running <c>etc-update</c>). When your Gentoo system is fully installed and
508     booted, do read our documentation on <uri
509 neysx 1.52 link="?part=3&amp;chap=2#doc_chap3">Configuration File Protection</uri>.
510 swift 1.28 </p>
511    
512     <p>
513 swift 1.31 When the build process has completed, continue with <uri
514     link="?part=1&amp;chap=7">Configuring the Kernel</uri>.
515 swift 1.28 </p>
516    
517     </body>
518     </subsection>
519     </section>
520    
521 swift 1.3 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20