/[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.145 - (show annotations) (download) (as text)
Sun Apr 13 11:58:00 2014 UTC (3 days, 6 hours ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.144: +9 -3 lines
File MIME type: application/xml
emerge-webrsync complains about missing /usr/portage but that is to be expected

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-system.xml,v 1.144 2013/12/29 15:39:28 swift Exp $ -->
8
9 <sections>
10
11 <abstract>
12 After installing and configuring a stage3, the eventual result is that you
13 have a Gentoo base system at your disposal. This chapter describes how
14 to progress to that state.
15 </abstract>
16
17 <version>37</version>
18 <date>2014-04-13</date>
19
20 <section>
21 <title>Chrooting</title>
22 <subsection>
23 <title>Optional: Selecting Mirrors</title>
24 <body>
25
26 <p>
27 In order to download source code quickly it is recommended to select a fast
28 mirror. Portage will look in your <path>make.conf</path> file for the
29 GENTOO_MIRRORS variable and use the mirrors listed therein. You can surf to
30 our <uri link="/main/en/mirrors.xml">mirror list</uri> and search
31 for a mirror (or mirrors) close to you (as those are most frequently the
32 fastest ones), but we provide a nice tool called <c>mirrorselect</c> which
33 provides you with a nice interface to select the mirrors you want. Just
34 navigate to the mirrors of choice and press spacebar to select one or more
35 mirrors.
36 </p>
37
38 <pre caption="Using mirrorselect for the GENTOO_MIRRORS variable">
39 # <i>mirrorselect -i -o &gt;&gt; /mnt/gentoo/etc/portage/make.conf</i>
40 </pre>
41
42 <p>
43 A second important setting is the SYNC setting in <path>make.conf</path>. This
44 variable contains the rsync server you want to use when updating your Portage
45 tree (the collection of ebuilds, scripts containing all the information Portage
46 needs to download and install software). Although you can manually enter a SYNC
47 server for yourself, <c>mirrorselect</c> can ease that operation for you:
48 </p>
49
50 <pre caption="Selecting an rsync mirror using mirrorselect">
51 # <i>mirrorselect -i -r -o &gt;&gt; /mnt/gentoo/etc/portage/make.conf</i>
52 </pre>
53
54 <p>
55 After running <c>mirrorselect</c> it is adviseable to double-check the settings
56 in <path>/mnt/gentoo/etc/portage/make.conf</path> !
57 </p>
58
59 <note>
60 If you want to manually set a SYNC server in <path>make.conf</path>, you should
61 check out the <uri link="/main/en/mirrors-rsync.xml">community mirrors
62 list</uri> for the mirrors closest to you. We recommend choosing a
63 <e>rotation</e>, such as <c>rsync.us.gentoo.org</c>, rather than choosing a
64 single mirror. This helps spread out the load and provides a failsafe in case a
65 specific mirror is offline.
66 </note>
67
68 </body>
69 </subsection>
70 <subsection>
71 <title>Copy DNS Info</title>
72 <body>
73
74 <p>
75 One thing still remains to be done before we enter the new environment and that
76 is copying over the DNS information in <path>/etc/resolv.conf</path>. You need
77 to do this to ensure that networking still works even after entering the new
78 environment. <path>/etc/resolv.conf</path> contains the nameservers for your
79 network.
80 </p>
81
82 <pre caption="Copy over DNS information">
83 <comment>(The "-L" option is needed to make sure we don't copy a symbolic link)</comment>
84 # <i>cp -L /etc/resolv.conf /mnt/gentoo/etc/</i>
85 </pre>
86
87 </body>
88 </subsection>
89 <subsection>
90 <title>Mounting the necessary Filesystems</title>
91 <body>
92
93 <p>
94 In a few moments, we will change the Linux root towards the new location. To
95 make sure that the new environment works properly, we need to make certain file
96 systems available there as well.
97 </p>
98
99 <p>
100 Mount the <path>/proc</path> filesystem on <path>/mnt/gentoo/proc</path> to
101 allow the installation to use the kernel-provided information within the
102 chrooted environment, and then mount-bind the <path>/dev</path> and
103 <path>/sys</path> filesystems.
104 </p>
105
106 <pre caption="Mounting /proc and /dev">
107 # <i>mount -t proc proc /mnt/gentoo/proc</i>
108 # <i>mount --rbind /sys /mnt/gentoo/sys</i>
109 # <i>mount --rbind /dev /mnt/gentoo/dev</i>
110 </pre>
111
112 </body>
113 </subsection>
114 <subsection>
115 <title>Entering the new Environment</title>
116 <body>
117
118 <p>
119 Now that all partitions are initialized and the base environment
120 installed, it is time to enter our new installation environment by
121 <e>chrooting</e> into it. This means that we change from the current
122 installation environment (Installation CD or other installation medium) to your
123 installation system (namely the initialized partitions).
124 </p>
125
126 <p>
127 This chrooting is done in three steps. First we will change the root
128 from <path>/</path> (on the installation medium) to <path>/mnt/gentoo</path>
129 (on your partitions) using <c>chroot</c>. Then we will reload some settings, as
130 provided by <path>/etc/profile</path>, in memory using <c>source</c>.
131 The last step is to redefine the primary prompt to help us remember that we are
132 inside a chroot environment.
133 </p>
134
135 <pre caption = "Chrooting into the new environment">
136 # <i>chroot /mnt/gentoo /bin/bash</i>
137 # <i>source /etc/profile</i>
138 # <i>export PS1="(chroot) $PS1"</i>
139 </pre>
140
141 <p>
142 Congratulations! You are now inside your own Gentoo Linux environment.
143 Of course it is far from finished, which is why the installation still
144 has some sections left :-)
145 </p>
146
147 <p>
148 If you at any time would need another terminal or console to access the chroot
149 environment, all you need to do is to execute the above steps again.
150 </p>
151
152 </body>
153 </subsection>
154 </section>
155
156 <section id="installing_portage">
157 <title>Configuring Portage</title>
158 <subsection>
159 <title>Installing a Portage Snapshot</title>
160 <body>
161
162 <p>
163 You now have to install a Portage snapshot, a collection of files that inform
164 Portage what software titles you can install, which profiles are available, etc.
165 </p>
166
167 <p>
168 We recommend the use of <c>emerge-webrsync</c>. This will fetch the latest
169 portage snapshot (which Gentoo releases on a daily basis) from one of our mirrors
170 and install it onto your system.
171 </p>
172
173 <pre caption="Running emerge-webrsync to install a Portage snapshot">
174 # <i>emerge-webrsync</i>
175 </pre>
176
177 <note>
178 During this operation, <c>emerge-webrsync</c> might complain about a missing
179 <path>/usr/portage</path> location. This is to be expected and nothing to
180 worry about - the tool will create the location for us.
181 </note>
182
183 <p>
184 From this point onward, Portage might mention that certain updates are
185 recommended to be executed. This is because certain system packages
186 installed through the stage3 file might have newer versions available,
187 and Portage is now aware of this because a new Portage snapshot is installed.
188 You can safely ignore this for now and update after the Gentoo installation
189 has finished.
190 </p>
191
192 </body>
193 </subsection>
194 <subsection>
195 <title>Optional: Updating the Portage tree</title>
196 <body>
197
198 <p>
199 You can now update your Portage tree to the latest version. <c>emerge
200 --sync</c> will use the rsync protocol to update the Portage tree (which
201 you fetched earlier on through <c>emerge-webrsync</c>) to the latest state.
202 </p>
203
204 <pre caption="Updating the Portage tree">
205 # <i>emerge --sync</i>
206 <comment>(If you're using a slow terminal like some framebuffers or a serial
207 console, you can add the --quiet option to speed up this process:)</comment>
208 # <i>emerge --sync --quiet</i>
209 </pre>
210
211 <p>
212 If you are behind a firewall that blocks rsync traffic, you safely ignore this
213 step as you already have a quite up-to-date Portage tree.
214 </p>
215
216 <p>
217 If you are warned that a new Portage version is available and that you should
218 update Portage, you should do it now using <c>emerge --oneshot portage</c>. You
219 might also be notified that "news items need reading". More on that next.
220 </p>
221
222 </body>
223 </subsection>
224 <subsection>
225 <title>Reading News Items</title>
226 <body>
227
228 <p>
229 When a Portage tree is synchronized to your system, Portage might warn you with
230 the following:
231 </p>
232
233 <pre caption="Portage informing that news items are available">
234 * IMPORTANT: 2 news items need reading for repository 'gentoo'.
235 * Use eselect news to read news items.
236 </pre>
237
238 <p>
239 Portage news items were created to provide a communication medium to push
240 critical messages to users via the rsync tree. To manage them you will need to
241 use <c>eselect news</c>. With the <c>read</c> subcommand, you can read all news
242 items. With <c>list</c> you can get an overview of the available news items, and
243 with <c>purge</c> you can remove them once you have read them and have no
244 further need for the item(s) anymore.
245 </p>
246
247 <pre caption="Handling Portage news">
248 # <i>eselect news list</i>
249 # <i>eselect news read</i>
250 </pre>
251
252 <p>
253 More information about the newsreader is available through its manual page:
254 <c>man news.eselect</c>.
255 </p>
256
257 </body>
258 </subsection>
259 <subsection>
260 <title>Choosing the Right Profile</title>
261 <body>
262
263 <p>
264 First, a small definition is in place.
265 </p>
266
267 <p>
268 A profile is a building block for any Gentoo system. Not only does it specify
269 default values for USE, CFLAGS and other important variables, it also locks
270 the system to a certain range of package versions. This is all maintained by the
271 Gentoo developers.
272 </p>
273
274 <p>
275 Previously, such a profile was untouched by the users. However, there may be
276 certain situations in which you may decide a profile change is necessary.
277 </p>
278
279 <p>
280 You can see what profile you are currently using with the following command:
281 </p>
282
283 <note>
284 The output of the command below is just an example and evolves over time.
285 </note>
286
287 <pre caption="Verifying system profile">
288 # <i>eselect profile list</i>
289 Available profile symlink targets:
290 [1] <keyval id="profile"/> *
291 [2] <keyval id="profile"/>/desktop
292 [3] <keyval id="profile"/>/desktop/gnome
293 [4] <keyval id="profile"/>/desktop/kde
294 </pre>
295
296 <p>
297 As you can see, there are also <c>desktop</c> subprofiles available for some
298 architectures. Running <c>eselect profile list</c> will show all available
299 profiles.
300 </p>
301
302 <p>
303 After viewing the available profiles for your architecture, you can use a
304 different one if you wish:
305 </p>
306
307 <pre caption="Changing profiles">
308 # <i>eselect profile set 2</i>
309 </pre>
310
311 <p test="func:keyval('arch')='AMD64'">
312 If you want to have a pure 64-bit environment, with no 32-bit applications or
313 libraries, you should use a non-multilib profile:
314 </p>
315
316 <pre test="func:keyval('arch')='AMD64'" caption="Switching to a non-multilib profile">
317 # <i>eselect profile list</i>
318 Available profile symlink targets:
319 [1] <keyval id="profile"/> *
320 [2] <keyval id="profile"/>/desktop
321 [3] <keyval id="profile"/>/desktop/gnome
322 [4] <keyval id="profile"/>/desktop/kde
323 [5] <keyval id="profile"/>/no-multilib
324 <comment>(Choose the no-multilib profile)</comment>
325 # <i>eselect profile set 5</i>
326 <comment>(Verify the change)</comment>
327 # <i>eselect profile list</i>
328 Available profile symlink targets:
329 [1] <keyval id="profile"/>
330 [2] <keyval id="profile"/>/desktop
331 [3] <keyval id="profile"/>/desktop/gnome
332 [4] <keyval id="profile"/>/desktop/kde
333 [5] <keyval id="profile"/>/no-multilib *
334 </pre>
335
336 <note>
337 The <c>developer</c> subprofile is specifically for Gentoo Linux development
338 tasks. It is <e>not</e> meant to help set up general development environments.
339 </note>
340
341 </body>
342 </subsection>
343 <subsection id="configure_USE">
344 <title>Configuring the USE variable</title>
345 <body>
346
347 <p>
348 <c>USE</c> is one of the most powerful variables Gentoo provides to its users.
349 Several programs can be compiled with or without optional support for certain
350 items. For instance, some programs can be compiled with gtk-support, or with
351 qt-support. Others can be compiled with or without SSL support. Some programs
352 can even be compiled with framebuffer support (svgalib) instead of X11 support
353 (X-server).
354 </p>
355
356 <p>
357 Most distributions compile their packages with support for as much as possible,
358 increasing the size of the programs and startup time, not to mention an enormous
359 amount of dependencies. With Gentoo you can define what options a package
360 should be compiled with. This is where <c>USE</c> comes into play.
361 </p>
362
363 <p>
364 In the <c>USE</c> variable you define keywords which are mapped onto
365 compile-options. For instance, <e>ssl</e> will compile ssl-support in the
366 programs that support it. <e>-X</e> will remove X-server support (note the
367 minus sign in front). <e>gnome gtk -kde -qt4</e> will compile your
368 programs with gnome (and gtk) support, and not with kde (and qt) support,
369 making your system fully tweaked for GNOME.
370 </p>
371
372 <p>
373 The default <c>USE</c> settings are placed in the <path>make.defaults</path>
374 files of your profile. You will find <path>make.defaults</path> files in the
375 directory which <path>/etc/portage/make.profile</path> points to and all parent
376 directories as well. The default <c>USE</c> setting is the sum of all <c>USE</c>
377 settings in all <path>make.defaults</path> files. What you place in
378 <path>/etc/portage/make.conf</path> is calculated against these defaults
379 settings. If you add something to the <c>USE</c> setting, it is added to the
380 default list. If you remove something from the <c>USE</c> setting (by placing
381 a minus sign in front of it) it is removed from the default list (if it was
382 in the default list at all). <e>Never</e> alter anything inside the
383 <path>/etc/portage/make.profile</path> directory; it gets overwritten when
384 you update Portage!
385 </p>
386
387 <p>
388 A full description on <c>USE</c> can be found in the second part of the Gentoo
389 Handbook, <uri link="?part=2&amp;chap=2">USE flags</uri>. A full description on
390 the available USE flags can be found on your system in
391 <path>/usr/portage/profiles/use.desc</path>.
392 </p>
393
394 <pre caption="Viewing available USE flags">
395 # <i>less /usr/portage/profiles/use.desc</i>
396 <comment>(You can scroll using your arrow keys, exit by pressing 'q')</comment>
397 </pre>
398
399 <p>
400 As an example we show a <c>USE</c> setting for a KDE-based system with DVD, ALSA
401 and CD Recording support:
402 </p>
403
404 <pre caption="Opening /etc/portage/make.conf">
405 # <i>nano -w /etc/portage/make.conf</i>
406 </pre>
407
408 <pre caption="USE setting">
409 USE="-gtk -gnome qt4 kde dvd alsa cdr"
410 </pre>
411
412 </body>
413 </subsection>
414 </section>
415 <section test="contains('AMD64 arm PPC PPC64 x86', func:keyval('arch'))">
416 <title>Optional: Using systemd</title>
417 <body>
418
419 <p>
420 The remainder of the Gentoo Handbook focuses on OpenRC as the default init
421 support system. If you want to use systemd instead, or are planning to use Gnome
422 3.8 and later (which requires systemd), please consult the <uri
423 link="https://wiki.gentoo.org/wiki/Systemd">systemd page</uri> on
424 the Gentoo wiki as it elaborates on the different configuration settings and
425 methods.
426 </p>
427
428 <p>
429 The Gentoo Handbook can then be followed with that page in mind.
430 </p>
431
432 </body>
433 </section>
434 <section>
435 <title>Timezone</title>
436 <body>
437
438 <p>
439 Finally select your timezone so that your system knows where it is physically
440 located. Look for your timezone in <path>/usr/share/zoneinfo</path>, then
441 write it in the <path>/etc/timezone</path> file.
442 </p>
443
444 <pre caption="Setting the timezone information">
445 # <i>ls /usr/share/zoneinfo</i>
446 <comment>(Suppose you want to use Europe/Brussels)</comment>
447 # <i>echo "Europe/Brussels" &gt; /etc/timezone</i>
448 </pre>
449
450 <p>
451 Please avoid the <path>/usr/share/zoneinfo/Etc/GMT*</path> timezones as their
452 names do not indicate the expected zones. For instance, <path>GMT-8</path> is
453 in fact GMT+8.
454 </p>
455
456 <p>
457 Next, reconfigure the timezone-data package, which will update the
458 <path>/etc/localtime</path> file for us, based on the <path>/etc/timezone</path>
459 entry. The <path>/etc/localtime</path> file is used by the system C library
460 to know the timezone the system is in.
461 </p>
462
463 <pre caption="Reconfiguring timezone-data">
464 # <i>emerge --config sys-libs/timezone-data</i>
465 </pre>
466
467 </body>
468 </section>
469
470 <section>
471 <title>Configure locales</title>
472 <body>
473
474 <p>
475 You will probably only use one or maybe two locales on your system. You have to
476 specify locales you will need in <path>/etc/locale.gen</path>.
477 </p>
478
479 <pre caption="Opening /etc/locale.gen">
480 # <i>nano -w /etc/locale.gen</i>
481 </pre>
482
483 <p>
484 The following locales are an example to get both English (United States) and
485 German (Germany) with the accompanying character formats (like UTF-8).
486 </p>
487
488 <pre caption="Specify your locales">
489 en_US ISO-8859-1
490 en_US.UTF-8 UTF-8
491 de_DE ISO-8859-1
492 de_DE@euro ISO-8859-15
493 </pre>
494
495 <note>
496 You can select your desired locales in the list given by running <c>locale -a</c>.
497 </note>
498
499 <warn>
500 We strongly suggest that you should use at least one UTF-8 locale because some
501 applications may require it.
502 </warn>
503
504 <p>
505 The next step is to run <c>locale-gen</c>. It will generates all the locales you
506 have specified in the <path>/etc/locale.gen</path> file.
507 </p>
508
509 <pre caption="Running locale-gen">
510 # <i>locale-gen</i>
511 </pre>
512
513 <p>
514 You can verify that your selected locales are available by running <c>locale -a</c>.
515 </p>
516
517 <p>
518 Once done, you now have the possibility to set the system-wide locale settings.
519 With <c>eselect locale list</c>, the available targets are displayed:
520 </p>
521
522 <pre caption="Displaying the available LANG settings">
523 # <i>eselect locale list</i>
524 Available targets for the LANG variable:
525 [1] C
526 [2] POSIX
527 [3] en_US
528 [4] en_US.iso88591
529 [5] en_US.utf8
530 [6] de_DE
531 [7] de_DE.iso88591
532 [8] de_DE.iso885915
533 [9] de_DE.utf8
534 [ ] (free form)
535 </pre>
536
537 <p>
538 With <c>eselect locale set &lt;value&gt;</c> the correct locale can be set:
539 </p>
540
541 <pre caption="Setting the LANG variable">
542 # <i>eselect locale set 9</i>
543 </pre>
544
545 <p>
546 Manually, this can still be accomplished through the
547 <path>/etc/env.d/02locale</path> file:
548 </p>
549
550 <pre caption="Setting the default system locale in /etc/env.d/02locale">
551 LANG="de_DE.UTF-8"
552 LC_COLLATE="C"
553 </pre>
554
555 <p>
556 Make sure a locale is set, as you could otherwise get warnings and errors
557 during kernel builds and other software deployments later in the installation.
558 </p>
559
560 <p>
561 Don't forget to reload your environment:
562 </p>
563
564 <pre caption="Reload shell environment">
565 # <i>env-update &amp;&amp; source /etc/profile</i>
566 </pre>
567
568 <p>
569 We made a full <uri link="https://wiki.gentoo.org/wiki/Localization/HOWTO">Localization
570 Guide</uri> to help you through this process. You can also read the detailed
571 <uri link="https://wiki.gentoo.org/wiki/UTF-8">UTF-8 article</uri> for very specific
572 informations to enable UTF-8 on your system.
573 </p>
574
575 </body>
576 </section>
577
578 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20