/[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.79 - (hide annotations) (download) (as text)
Wed Jun 8 10:19:57 2005 UTC (9 years, 4 months ago) by neysx
Branch: MAIN
Changes since 1.78: +31 -20 lines
File MIME type: application/xml
#94952 "2.4 means 2.6" confuses users. Tried to make things clearer.

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 neysx 1.79 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-system.xml,v 1.78 2005/05/17 16:42:30 neysx Exp $ -->
8 swift 1.11
9 swift 1.3 <sections>
10 swift 1.56
11 neysx 1.79 <version>2.6</version>
12     <date>2005-06-08</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 neysx 1.78 <comment>(If you're using a slow terminal like some framebuffers or a serial
139     console, you can add the --quiet option to speed up this process:)</comment>
140     # <i>emerge --sync --quiet</i>
141 swift 1.13 </pre>
142    
143     <p>
144 swift 1.75 If you are behind a firewall that blocks rsync traffic, you can use
145     <c>emerge-webrsync</c> which will download and install a portage snapshot for
146     you.
147     </p>
148    
149     <p>
150 swift 1.13 If you are warned that a new Portage version is available and that you should
151 swift 1.34 update Portage, you should ignore it. Portage will be updated for you later
152 bennyc 1.16 on during the installation.
153 swift 1.13 </p>
154 swift 1.8
155     </body>
156     </subsection>
157 swift 1.72 <subsection>
158     <title>Choosing the Right Profile</title>
159     <body>
160    
161     <p>
162     First, a small definition is in place.
163     </p>
164    
165     <p>
166     A profile is a building block for any Gentoo system. Not only does it specify
167     default values for CHOST, CFLAGS and other important variables, it also locks
168     the system to a certain range of package versions. This is all maintained by the
169     Gentoo developers.
170     </p>
171    
172     <p>
173 neysx 1.79 Previously, such a profile was barely touched by the user. However, x86, hppa
174     and alpha users can choose between two profiles, one for a 2.4 kernel and one
175     for a 2.6 kernel. This requirement has been imposed to improve the integration
176     of the 2.6 kernels.
177 swift 1.72 </p>
178    
179     <p>
180 neysx 1.79 You can see what profile you are currently using with the following command:
181 swift 1.72 </p>
182    
183     <pre caption="Verifying system profile">
184 neysx 1.79 # <i>ls -FGg /etc/make.profile</i>
185     lrwxrwxrwx 1 48 Apr 8 18:51 /etc/make.profile -> ../usr/portage/profiles/default-linux/x86/2005.0/
186 swift 1.72 </pre>
187    
188     <p>
189 neysx 1.79 If you are using one of the aforementioned three architectures, you will see a
190     <path>2.4</path> subdirectory that identifies an additional profile below the
191     one that the <path>make.profile</path> symlink points to:
192 swift 1.72 </p>
193    
194     <pre caption="Finding out if an additional profile exists">
195 neysx 1.79 # <i>ls -FGg /etc/make.profile/</i>
196     total 8
197     drwxr-xr-x 2 120 Jan 21 23:08 2.4/
198     -rw-r--r-- 1 679 Mar 29 00:35 packages
199     -rw-r--r-- 1 343 Dec 3 2004 parent
200 swift 1.72 </pre>
201    
202     <p>
203 neysx 1.79 As you can see in the above example, the current profile contains a
204     <path>2.4</path> subdirectory. This means that the current profile uses the
205     2.6 kernel and that you can change your profile to a 2.4-based system. For
206     that, you need to link the <path>make.profile</path> symlink to the
207     <path>2.4</path> subdirectory:
208 swift 1.72 </p>
209    
210 neysx 1.79 <pre caption="Switching to a 2.4 profile">
211     <comment>(Make sure you use the right architecture, the example below is for x86)</comment>
212 swift 1.72 # <i>ln -snf /usr/portage/profiles/default-linux/x86/2005.0/2.4 /etc/make.profile</i>
213 neysx 1.79 <comment>(List the files in the 2.4 profile)</comment>
214     # <i>ls -FGg /etc/make.profile/</i>
215     total 12
216     -rw-r--r-- 1 939 Dec 10 14:06 packages
217     -rw-r--r-- 1 347 Dec 3 2004 parent
218     -rw-r--r-- 1 573 Dec 3 2004 virtuals
219 swift 1.72 </pre>
220    
221     </body>
222     </subsection>
223 swift 1.28 <subsection id="configure_USE">
224 swift 1.21 <title>Configuring the USE variable</title>
225     <body>
226    
227     <p>
228     <c>USE</c> is one of the most powerful variables Gentoo provides to its users.
229     Several programs can be compiled with or without optional support for certain
230     items. For instance, some programs can be compiled with gtk-support, or with
231     qt-support. Others can be compiled with or without SSL support. Some programs
232     can even be compiled with framebuffer support (svgalib) instead of X11 support
233     (X-server).
234     </p>
235    
236     <p>
237     Most distributions compile their packages with support for as much as possible,
238     increasing the size of the programs and startup time, not to mention an enormous
239 swift 1.24 amount of dependencies. With Gentoo you can define what options a package
240 swift 1.21 should be compiled with. This is where <c>USE</c> comes into play.
241     </p>
242    
243     <p>
244     In the <c>USE</c> variable you define keywords which are mapped onto
245     compile-options. For instance, <e>ssl</e> will compile ssl-support in the
246     programs that support it. <e>-X</e> will remove X-server support (note the minus
247     sign in front). <e>gnome gtk -kde -qt</e> will compile your programs with gnome
248     (and gtk) support, and not with kde (and qt) support, making your system fully
249     tweaked for GNOME.
250     </p>
251    
252     <p>
253 swift 1.68 The default <c>USE</c> settings are placed in the <path>make.defaults</path>
254     files of your profile. You will find <path>make.defaults</path> files in the
255     directory which <path>/etc/make.profile</path> points to and all parent
256     directories as well. The default <c>USE</c> setting is the sum of all <c>USE</c>
257     settings in all <path>make.defaults</path> files. What you place in
258 swift 1.21 <path>/etc/make.conf</path> is calculated against these defaults settings. If
259     you add something to the <c>USE</c> setting, it is added to the default list. If
260     you remove something from the <c>USE</c> setting (by placing a minus sign in
261     front of it) it is removed from the default list (if it was in the default list
262     at all). <e>Never</e> alter anything inside the <path>/etc/make.profile</path>
263     directory; it gets overwritten when you update Portage!
264     </p>
265    
266     <p>
267     A full description on <c>USE</c> can be found in the second part of the Gentoo
268 neysx 1.52 Handbook, <uri link="?part=2&amp;chap=2">USE flags</uri>. A full description on
269     the available USE flags can be found on your system in
270 swift 1.23 <path>/usr/portage/profiles/use.desc</path>.
271     </p>
272    
273     <pre caption="Viewing available USE flags">
274     # <i>less /usr/portage/profiles/use.desc</i>
275 swift 1.45 <comment>(You can scroll using your arrow keys, exit by pressing 'q')</comment>
276 swift 1.23 </pre>
277    
278     <p>
279     As an example we show a <c>USE</c> setting for a KDE-based system with DVD, ALSA
280     and CD Recording support:
281 swift 1.21 </p>
282    
283     <pre caption="Opening /etc/make.conf">
284     # <i>nano -w /etc/make.conf</i>
285     </pre>
286    
287     <pre caption="USE setting">
288     USE="-gtk -gnome qt kde dvd alsa cdr"
289     </pre>
290    
291 swift 1.69 </body>
292     </subsection>
293     <subsection>
294     <title>Optional: GLIBC Locales</title>
295     <body>
296    
297 dertobi123 1.53 <p>
298     You will probably only use one or maybe two locales on your system. Up until now
299 swift 1.55 after compiling <c>glibc</c> a full set of all available locales will be
300     created. As of now you can activate the <c>userlocales</c> USE flag and specify
301 swift 1.67 only the locales you will need in <path>/etc/locales.build</path>. Only do this
302 swift 1.74 if you know what locales to choose. This will not work for the bootstrapping,
303     but when you recompile glibc afterwards it will.
304 dertobi123 1.53 </p>
305    
306     <pre caption="Activate the userlocales USE flag especially for glibc">
307 swift 1.54 # <i>mkdir /etc/portage</i>
308     # <i>echo "sys-libs/glibc userlocales" >> /etc/portage/package.use</i>
309 dertobi123 1.53 </pre>
310    
311     <p>
312     Now specify the locales you want to be able to use:
313     </p>
314    
315 bennyc 1.60 <pre caption="Opening /etc/locales.build">
316 neysx 1.61 # <i>nano -w /etc/locales.build</i>
317 bennyc 1.60 </pre>
318    
319 swift 1.67 <p>
320     The following locales are an example to get both English (United States) and
321     German (Germany) with the accompanying character formats (like UTF-8).
322     </p>
323    
324 bennyc 1.60 <pre caption="Specify your locales">
325 dertobi123 1.53 en_US/ISO-8859-1
326     en_US.UTF-8/UTF-8
327     de_DE/ISO-8859-1
328     de_DE@euro/ISO-8859-15
329     </pre>
330    
331 swift 1.21 </body>
332     </subsection>
333 swift 1.3 </section>
334     <section>
335 swift 1.1 <title>Differences between Stage1, Stage2 and Stage3</title>
336     <body>
337    
338     <p>
339     Now take a seat and think of your previous steps. We asked you to
340     select a <e>stage1</e>, <e>stage2</e> or <e>stage3</e> and warned you
341     that your choice is important for further installation steps. Well, this
342 neysx 1.48 is the first place where your choice defines the subsequent steps.
343 swift 1.1 </p>
344    
345     <ul>
346     <li>
347 swift 1.4 If you chose <e>stage1</e>, then you have to follow <e>both</e> steps in
348     this chapter (starting with <uri link="#doc_chap3">Progressing from Stage1
349     to Stage2</uri>)
350 swift 1.1 </li>
351     <li>
352 swift 1.4 If you chose <e>stage2</e> you only can skip the first step
353     and immediately start with the second one (<uri link="#doc_chap4">Progressing
354     from Stage2 to Stage3</uri>)
355 swift 1.1 </li>
356     <li>
357 swift 1.69 If you chose <e>stage3</e> then you can skip both
358 swift 1.31 steps and continue with <uri link="?part=1&amp;chap=7">Configuring the
359     Kernel</uri>
360 swift 1.1 </li>
361     </ul>
362    
363     </body>
364 swift 1.3 </section>
365     <section>
366     <title>Progressing from Stage1 to Stage2</title>
367 swift 1.1 <subsection>
368     <title>Introduction to Bootstrapping</title>
369     <body>
370    
371     <p>
372     So, you want to compile everything from scratch? Okay then :-)
373     </p>
374    
375     <p>
376     In this step, we will <e>bootstrap</e> your Gentoo system. This takes a
377     long time, but the result is a system that has been optimized from the
378     ground up for your specific machine and needs.
379     </p>
380    
381     <p>
382     <e>Bootstrapping</e> means building the GNU C Library, GNU Compiler
383 swift 1.32 Collection and several other key system programs.
384 swift 1.1 </p>
385    
386     <p>
387 swift 1.62 Before starting the bootstrap, you might want to download all necessary
388     sourcecode first. If you do not want to do this, continue
389     with <uri link="#bootstrap">Bootstrapping the System</uri>.
390 swift 1.1 </p>
391    
392     </body>
393 swift 1.3 </subsection>
394     <subsection>
395 swift 1.1 <title>Optional: Downloading the Sources First</title>
396     <body>
397    
398     <p>
399 swift 1.25 If you haven't copied over all source code before, then the bootstrap
400 swift 1.69 script will download all necessary files. If you want to
401 swift 1.25 download the source code first and later bootstrap the system (for instance
402 swift 1.1 because you don't want to have your internet connection open during the
403     compilation) use the <e>-f</e> option of the bootstrap script, which will
404 swift 1.25 fetch (hence the letter <e>f</e>) all source code for you.
405 swift 1.1 </p>
406    
407     <pre caption = "Downloading the necessary sources">
408     # <i>cd /usr/portage</i>
409 swift 1.47 # <i>scripts/bootstrap.sh -f</i>
410 swift 1.1 </pre>
411    
412     </body>
413 swift 1.3 </subsection>
414 swift 1.41 <subsection id="bootstrap">
415 swift 1.1 <title>Bootstrapping the System</title>
416     <body>
417    
418     <p>
419     Okay then, take your keyboard and punch in the next commands to start
420 swift 1.36 the bootstrap. Then go amuse yourself with something else because this step
421     takes quite some time to finish.
422 swift 1.1 </p>
423    
424     <pre caption = "Bootstrapping the system">
425     # <i>cd /usr/portage</i>
426 swift 1.47 # <i>scripts/bootstrap.sh</i>
427 swift 1.12 </pre>
428    
429     <p>
430 swift 1.4 Now continue with the next step, <uri link="#doc_chap4">Progressing from Stage2
431     to Stage3</uri>.
432     </p>
433    
434 swift 1.1 </body>
435     </subsection>
436 swift 1.3 </section>
437     <section>
438     <title>Progressing from Stage2 to Stage3</title>
439 swift 1.1 <subsection>
440     <title>Introduction</title>
441     <body>
442    
443     <p>
444     If you are reading this section, then you have a bootstrapped system
445     (either because you bootstrapped it previously, or you are using a
446     <e>stage2</e>). Then it is now time to build all system packages.
447     </p>
448    
449     <p>
450     <e>All</e> system packages? No, not really. In this step, you will build
451 swift 1.19 the system packages of which there are no alternatives to use.
452     Some system packages have several alternatives (such as system loggers)
453 swift 1.1 and as Gentoo is all about choices, we don't want to force one upon you.
454     </p>
455    
456     </body>
457 swift 1.3 </subsection>
458     <subsection>
459 swift 1.1 <title>Optional: Viewing what will be done</title>
460     <body>
461    
462     <p>
463     If you want to know what packages will be installed, execute <c>emerge
464 swift 1.72 --pretend --emptytree system</c>. This will list all packages that will be
465     built. As this list is pretty big, you should also use a pager like
466     <c>less</c> or <c>more</c> to go up and down the list.
467 swift 1.1 </p>
468    
469     <pre caption = "View what 'emerge system' will do">
470 swift 1.72 # <i>emerge --pretend --emptytree system | less</i>
471 swift 1.1 </pre>
472    
473 swift 1.72 <p>
474     Note that, if you haven't touched the default CFLAGS/CXXFLAGS setting, using
475 swift 1.76 <c>emerge --pretend --newuse system</c> is sufficient: it will rebuild the
476     applications that are affected by a change in USE flags (compared to the USE
477     flag we used while building the stage2). If you didn't touch
478     the USE flag either, why are you running a stage2 installation then?
479 swift 1.72 </p>
480    
481 swift 1.1 </body>
482 swift 1.3 </subsection>
483     <subsection>
484 swift 1.4 <title>Optional: Downloading the Sources</title>
485 swift 1.1 <body>
486    
487     <p>
488     If you want <c>emerge</c> to download the sources before you continue
489     (for instance because you don't want the internet connection to be left
490 swift 1.20 open while you are building all packages) you can use the <e>--fetchonly</e>
491 swift 1.1 option of <c>emerge</c> which will fetch all sources for you.
492     </p>
493    
494     <pre caption = "Fetching the sources">
495 swift 1.72 # <i>emerge --fetchonly --emptytree system</i>
496 swift 1.1 </pre>
497    
498     </body>
499 swift 1.3 </subsection>
500     <subsection>
501 swift 1.1 <title>Building the System</title>
502     <body>
503    
504     <p>
505 swift 1.72 To start building the system, execute <c>emerge --emptytree system</c>. Then
506     go do something to keep your mind busy, because this step takes a long time to
507 swift 1.4 complete.
508 swift 1.1 </p>
509    
510     <pre caption = "Building the System">
511 swift 1.72 # <i>emerge --emptytree system</i>
512 swift 1.1 </pre>
513    
514     <p>
515 swift 1.72 Again, if you haven't touched the default CFLAGS and CXXFLAGS setting, using
516     <c>--newuse</c> is sufficient.
517     </p>
518    
519     <p>
520 swift 1.30 You can for now safely ignore any warnings about updated configuration files
521     (and running <c>etc-update</c>). When your Gentoo system is fully installed and
522     booted, do read our documentation on <uri
523 neysx 1.52 link="?part=3&amp;chap=2#doc_chap3">Configuration File Protection</uri>.
524 swift 1.28 </p>
525    
526     <p>
527 swift 1.31 When the build process has completed, continue with <uri
528     link="?part=1&amp;chap=7">Configuring the Kernel</uri>.
529 swift 1.28 </p>
530    
531     </body>
532     </subsection>
533     </section>
534    
535 swift 1.3 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20