/[gentoo]/xml/htdocs/doc/en/gentoo-freebsd.xml
Gentoo

Contents of /xml/htdocs/doc/en/gentoo-freebsd.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.17 - (hide annotations) (download) (as text)
Wed May 3 01:01:04 2006 UTC (8 years, 4 months ago) by rane
Branch: MAIN
Changes since 1.16: +63 -39 lines
File MIME type: application/xml
updates from #132071

1 cam 1.4 <?xml version="1.0" encoding="UTF-8"?>
2 rane 1.17 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-freebsd.xml,v 1.16 2006/03/30 08:41:57 neysx Exp $ -->
3 neysx 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5     <guide link="/doc/en/gentoo-freebsd.xml">
6     <title>A short guide to Gentoo/FreeBSD</title>
7    
8     <author title="Author">
9     <mail link="ignacio.arquelatour@gmail.com">Ignacio Arque-Latour</mail>
10     </author>
11     <author title="Author">
12     <mail link="citizen428@gentoo.org">Michael Kohl</mail>
13     </author>
14     <author title="Author">
15 rane 1.8 <mail link="angusyoung@gentoo.org">Otavio R. Piske</mail>
16 neysx 1.1 </author>
17     <author title="Author">
18     <mail link="ka0ttic@gentoo.org">Aaron Walker</mail>
19     </author>
20    
21     <abstract>
22     This document gives some general information on FreeBSD, as well as
23     installation instructions for Gentoo/FreeBSD. It also includes some reference
24     for people interested in helping out with development.
25     </abstract>
26    
27     <!-- The content of this document is licensed under the CC-BY-SA license -->
28     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
29     <license/>
30    
31 rane 1.17 <version>2.4</version>
32     <date>2006-05-03</date>
33 neysx 1.1
34     <chapter>
35     <title>Introduction to FreeBSD</title>
36     <section>
37     <title>What is FreeBSD?</title>
38     <body>
39    
40     <p>
41     <uri link="http://www.freebsd.org/">FreeBSD</uri> is a free (<uri
42     link="http://www.freebsd.org/copyright/freebsd-license.html">license</uri>)
43     Unix-like operating system. Back in 1993 when development of <uri
44     link="http://www.386bsd.org/">386BSD</uri> stopped, two projects were born:
45     <uri link="http://www.netbsd.org/">NetBSD</uri>, commonly known to run on a
46 rane 1.17 huge number of architectures, and FreeBSD which supports the x86, amd64, ia64,
47 neysx 1.15 sparc64 and alpha platforms.FreeBSD is renowned for its stability, performance
48     and security, thus being used from small to huge companies all over the world.
49     FreeBSD's current production release version is 6.0, which is also used as the
50     foundation for the Gentoo/FreeBSD project. The previous 5.x branch is being
51     continued by the FreeBSD project as a service release, but is no more worked on by
52     the Gentoo/FreeBSD developers.
53 neysx 1.1 </p>
54    
55     </body>
56     </section>
57     <section>
58     <title>What is Gentoo/FreeBSD?</title>
59     <body>
60    
61     <p>
62 neysx 1.16 <uri link="/proj/en/gentoo-alt/bsd/fbsd/">Gentoo/FreeBSD</uri> is a subproject of the
63     <uri link="/proj/en/gentoo-alt/">Gentoo/Alt project</uri>, with the goal of providing
64 neysx 1.15 a fully-capable FreeBSD operating system featuring the design sensibilities known from
65     Gentoo Linux, like the init system and the portage package management system.
66 neysx 1.1 </p>
67    
68     </body>
69     </section>
70     <section>
71     <title>FreeBSD and Linux</title>
72     <body>
73    
74     <p>
75     Users migrating from Linux to FreeBSD commonly consider the two operating
76     systems "almost the same". In fact, FreeBSD really shares a lot of similarities
77     with Linux distributions in general. Nevertheless, it has some key differences
78     that are worth noting:
79     </p>
80    
81     <ul>
82     <li>
83     Contrary to Linux, which actually only refers to the kernel, FreeBSD is a
84     complete operating system, consisting of a C library, userland tools and
85     much more. This development approach makes the overall system very
86 cam 1.4 consistent.
87 neysx 1.1 </li>
88     <li>
89     Contrary to the Linux kernel, FreeBSD development is not led by one person,
90     but instead managed by a small group of people called the <uri
91     link="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributors/staff-core.html">Core
92     Team</uri>.
93     </li>
94     </ul>
95    
96     <p>
97     Besides, FreeBSD also has some technical differences which set it apart
98     from Linux. Some of them are very important to know, even if you don't plan on
99     joining the Gentoo/FreeBSD development effort:
100     </p>
101    
102     <ul>
103     <li>
104 cam 1.4 To get run-time dynamic linking functions like <c>dlopen()</c>, programs do
105 neysx 1.1 not need to be linked against libdl like on GNU/Linux. Instead they are
106 cam 1.4 linked against libc.
107 neysx 1.1 </li>
108     <li>
109     FreeBSD doesn't have an official tool for kernel compilation, thus you'll
110 cam 1.4 have to resolve feature dependencies on your own.
111 neysx 1.1 </li>
112     <li>
113     FreeBSD uses UFS/UFS-2 as its filesystems and has no official support for
114     e.g. ReiserFS or XFS. However, there are projects for adding read-only
115 cam 1.4 support for these filesystems. Accessing ext2/ext3 partitions is already
116     possible, but you cannot install your system on them.
117 neysx 1.1 </li>
118     </ul>
119    
120     </body>
121     </section>
122     </chapter>
123    
124     <chapter>
125     <title>Installing Gentoo/FreeBSD</title>
126     <section>
127     <title>Installation instructions</title>
128     <body>
129    
130     <p>
131     After this short introduction, it's about time to finally install
132     Gentoo/FreeBSD. Unfortunately, we currently lack our own installation media, so
133     you have to choose between two alternative installation methods. The first
134     would be to use an existing FreeBSD installation to partition your hard drive
135     and use it as a base for installing Gentoo/FreeBSD. Alternatively, you can also
136     use the excellent <uri link="http://www.freesbie.org/">FreeSBIE LiveCD</uri> as
137     an installation medium for Gentoo/FreeBSD.
138     </p>
139    
140 neysx 1.15 <note>
141     If you are intending to use FreeSBIE for installing Gentoo/FreeBSD, please make
142     sure to use a version based on FreeBSD 6.0! Experimental versions can be downloaded
143     from <uri link="http://torrent.freesbie.org/">FreeSBIE's Bittorrent tracker</uri> and
144     version 20060118 has been tested to work for the purposes described in this document.
145     </note>
146    
147 rane 1.17 <note>
148     We use <c>ee</c> as a default editor in this guide but you can choose
149     <c>vim</c>, <c>nano</c> or any other editor you like to configure your system.
150     </note>
151    
152 neysx 1.1 <p>
153     Before you can begin with the installation, you have to setup a hard disk for
154     use with Gentoo/FreeBSD. This can either be done via <c>sysinstall</c>
155     (available from a current FreeBSD installation as well as from within FreeSBIE)
156 neysx 1.15 or by manually using the commands <c>fdisk</c>, <c>disklabel</c> and <c>newfs</c>.
157     If you have never set up a FreeBSD system before, <c>sysinstall</c> may be the
158     better option for you. In that case make sure that you don't use the sysinstall
159     launched by FreeBSD's or FreeSBIE's installers, but use the following command instead:
160     </p>
161    
162     <pre caption="Partitioning with sysinstall">
163     # <i>sysinstall diskPartitionEditor diskPartitionWrite diskLabelEditor diskLabelCommit</i>
164     </pre>
165    
166     <p>
167     If you face difficulties
168 neysx 1.1 while partitioning or formatting your hard disks, have a look at the great
169     <uri link="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/">FreeBSD
170     Handbook</uri> or hop onto <c>#gentoo-bsd</c> on the Freenode IRC server.
171     </p>
172    
173     <p>
174     Once you're done setting up your disks, you have to create a mount point for
175     your Gentoo/FreeBSD installation and mount all the necessary partitions.
176     </p>
177    
178     <pre caption="Creating a mount point and mounting partitions">
179 rane 1.8 # <i>mkdir /mnt/gentoo</i>
180 neysx 1.1 <comment>(Replace X with the correct numbers for your hard disk.)</comment>
181 rane 1.8 # <i>mount /dev/adXsXa /mnt/gentoo</i>
182 neysx 1.1 </pre>
183    
184     <p>
185 neysx 1.15 If you're using the FreeSBIE LiveCD and you already had an UFS partition on
186     your hard disk, it has already been mounted read-only to <path>/mnt/ufs.1</path>.
187     If you want to use that location for your installation, you'll have to remount it
188     in read-write mode:
189     </p>
190    
191     <pre caption="Remounting a partition in read-write mode">
192 neysx 1.16 # <i>mount -u -o rw /mnt/ufs.1</i>
193 neysx 1.15 </pre>
194    
195     <p>
196 neysx 1.1 Now that you have mounted the target partition, it is time to fetch and unpack
197     a stage3 tarball.
198     </p>
199    
200     <pre caption="Obtaining and unpacking a stage3 tarball">
201 rane 1.8 # <i>cd /mnt/gentoo/</i>
202 neysx 1.1 <comment>(Any other Gentoo mirror which includes the experimental/ directory will also work.)</comment>
203 neysx 1.15 # <i>wget http://gentoo.osuosl.org/experimental/x86/freebsd/stages/gentoo-freebsd-6.0-stage-20060221.tar.bz2</i>
204     # <i>tar -jxvpf gentoo-freebsd-6.0-stage-20060221</i>
205 neysx 1.1 <comment>(You can delete the tarball with the following command if you want to.)</comment>
206 neysx 1.15 # <i>rm gentoo-freebsd-6.0-stage-20060221</i>
207 rane 1.3 </pre>
208    
209     <p>
210 cam 1.12 Before chrooting into the newly-extracted stage, you first must obtain an
211     up-to-date copy of the Gentoo/FreeBSD overlay. The easiest way to achieve this
212     is to to get our latest snapshot which you then extract to
213     <path>/mnt/gentoo/usr/local/portage</path>.
214 rane 1.3 </p>
215    
216 rane 1.8 <pre caption="Getting the Gentoo/FreeBSD Portage overlay">
217     # <i>cd /mnt/gentoo/usr/local/portage</i>
218 jkt 1.7 # <i>wget http://gentoo.osuosl.org/experimental/snapshots/portage-alt-overlay-latest.tar.bz2</i>
219     # <i>tar -xjf portage-alt-overlay-latest.tar.bz2</i>
220 jkt 1.11 <comment>(You now can safely delete the snapshot with the following command.)</comment>
221     # <i>rm portage-alt-overlay-latest.tar.bz2</i>
222 neysx 1.1 </pre>
223    
224     <p>
225 rane 1.8 Alternatively, you can also use Subversion to check out the current version of
226 yoswink 1.14 the overlay. If you are interested in this possibility, please refer to the
227     <uri
228     link="/proj/en/gentoo-alt/contribute/index.xml?part=1&amp;chap=3">Gentoo/ALT
229     overlay documentation</uri>.
230 jkt 1.7 </p>
231    
232     <p>
233 neysx 1.1 In order for your install to work, you need to mount the <path>/dev</path>
234     filesystem from the currently running system into the Gentoo/FreeBSD mount
235     point before proceeding with the chroot.
236     </p>
237    
238     <pre caption="Mounting the /dev filesystem and chrooting">
239 rane 1.8 # <i>mount -t devfs none /mnt/gentoo/dev/</i>
240     # <i>cp /etc/resolv.conf /mnt/gentoo/etc</i>
241     # <i>chroot /mnt/gentoo/ /bin/bash</i>
242 jkt 1.7 # <i>source /etc/profile</i>
243 neysx 1.1 </pre>
244    
245     <p>
246     After you got hold of the Gentoo/FreeBSD overlay, it's time to link
247     <path>/etc/make.profile</path> to the correct profile and add get your
248     <path>/etc/make.conf</path> ready for Gentoo/FreeBSD.
249     </p>
250    
251 rane 1.17 <p>
252     Now, you have to obtain a copy of the main Gentoo Portage tree, which depending
253     on your connection might take quite a while.
254     </p>
255    
256     <pre caption="Obtaining the Portage tree">
257     # <i>emerge --sync</i>
258     <comment>(It's also possible to retrieve the Portage tree in another way:)</comment>
259     # <i>cd /</i>
260     # <i>wget http://gentoo.osuosl.org/snapshots/portage-latest.tar.bz2</i>
261     # <i>tar -xjf portage-latest.tar.bz2 -C /usr/</i>
262     # <i>emerge --metadata</i>
263     </pre>
264    
265 neysx 1.1 <pre caption="Setting up the profile and editing /etc/make.conf">
266 neysx 1.15 # <i>ln -sf /usr/local/portage/portage-alt-overlay/profiles/default-bsd/fbsd/6.0/x86/ /etc/make.profile</i>
267 neysx 1.1 <comment>(FreeBSD's standard editor is ee, which is used to edit /etc/make.conf)</comment>
268     # <i>ee /etc/make.conf</i>
269     <comment>(Please make sure you add at least the following entries:)</comment>
270 neysx 1.15 CHOST="i686-gentoo-freebsd6.0"
271 rane 1.17 ACCEPT_KEYWORDS="~x86-fbsd"
272 neysx 1.1 FEATURES="-sandbox collision-protect"
273 jkt 1.7 PORTDIR_OVERLAY="/usr/local/portage/portage-alt-overlay"
274 neysx 1.1 </pre>
275    
276 neysx 1.15 <note>
277 rane 1.17 You can have a very limited system by using ~x86-fbsd keyword alone; you might
278     want to put ~x86 in your ACCEPT_KEYWORDS if you want access to more packages
279     but you might find broken dependencies and non-working packages; please rather
280     use package.keywords when testing packages and report working ones on <uri
281     link="http://bugs.gentoo.org">Bugzilla</uri> for the product Gentoo/Alt.
282 neysx 1.15 </note>
283    
284 neysx 1.1 <p>
285 cam 1.12 In order to boot correctly, you will need to create the <path>/proc</path>
286     directory.
287 jkt 1.11 </p>
288    
289     <pre caption="Creating the /proc directory">
290     # <i>mkdir /proc</i>
291     </pre>
292    
293     <p>
294     If you want, you can now rebuild the system's core packages.
295 neysx 1.1 </p>
296    
297 jkt 1.11 <pre caption="Rebuilding the FreeBSD core packages (Optional)">
298 neysx 1.1 # <i>emerge -e system</i>
299     </pre>
300    
301 jkt 1.11 <p>
302 cam 1.12 When you did <c>emerge -e system</c>, the sources for the FreeBSD kernel got
303     installed to <path>/usr/src/sys</path>. If you skipped this step, you can get
304 jkt 1.11 them in the following way:
305     </p>
306    
307     <pre caption="Geting the FreeBSD kernel sources">
308     # <i>emerge freebsd-sources</i>
309     </pre>
310    
311     <p>
312 cam 1.12 Configuring and compiling a custom kernel is really different from compiling
313     Linux, so if you are not familiar with the process we encourage you to have a
314     look at <uri
315     link="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html">
316 jkt 1.11 chapter 8</uri> of the FreeBSD handbook.
317     </p>
318    
319     <p>
320 cam 1.12 Please note that currently only the "Traditional" way of building the kernel is
321 jkt 1.11 supported on Gentoo/FreeBSD! Also note that <c>make install</c> will probably
322     ask you for a <path>/boot/device.hints</path> file. A default version can be
323     found in the <path>conf</path> subdirectory of the <c>GENERIC</c> configuration
324 neysx 1.15 and is called <path>GENERIC.hints</path>.
325 jkt 1.11 </p>
326    
327     <p>
328 cam 1.12 Now is the time to do some basic system configuration and settings. First, we
329     are going to setup the filesystem mounting points in <path>/etc/fstab</path>.
330 jkt 1.11 </p>
331    
332     <pre caption="Editing the filesystem in /etc/fstab">
333     # <i>ee /etc/fstab</i>
334     <comment>(This is an example, replace X and Y with the correct numbers for your hard disk.)</comment>
335     #Device Mountpoint Fstype Options Dump Pass
336     /dev/adXsYb none swap sw 0 0
337     /dev/adXsYa / ufs rw 1 1
338     /dev/adXsYe /usr/home ufs rw 2 2
339     /dev/adXsYd /tmp ufs rw 2 2
340     /dev/acdX /cdrom cd9660 ro,noauto 0 0
341     </pre>
342    
343     <p>
344     Now would also be a good time to set up your network connection before the final
345     reboot.
346     </p>
347    
348 rane 1.17 <p>
349     You can find all the information necessary to configure your network in the
350     <uri link="/doc/en/handbook/handbook-x86.xml?part=4&amp;chap=1">Gentoo
351     Handbook</uri>.
352     </p>
353 jkt 1.11
354     <p>
355 rane 1.17 To have your network interface activated at boot time, you have to add it to
356     the default runlevel.
357 vanquirius 1.13 </p>
358    
359     <pre caption="Adding your network adapter to the default runlevel">
360     # <i>rc-update add net.rl0 default</i>
361     </pre>
362    
363     <p>
364 rane 1.17 Your system's hostname can be changed in <path>/etc/conf.dhostname</path>.
365 jkt 1.11 </p>
366    
367     <pre caption="Setting up the machine's hostname">
368 rane 1.17 # <i>ee /etc/conf.d/hostname</i>
369     <comment>(Set the HOSTNAME variable to your hostname)</comment>
370     HOSTNAME="tux"
371     </pre>
372    
373     <p>
374     You should also configure your domain name, which is done in the
375     <path>/etc/conf.d/domainname</path> file:
376     </p>
377    
378     <pre caption="Setting the domainname">
379     # <i>ee /etc/conf.d/domainname</i>
380     <comment>(Set the DNSDOMAIN variable to your domain name)</comment>
381     DNSDOMAIN="homenetwork"
382     </pre>
383    
384     <p>
385     If you have a NIS domain, you need to define it in the
386     <path>/etc/conf.d/domainname</path> file:
387     </p>
388    
389     <pre caption="Setting the NIS domainname">
390     # <i>ee /etc/conf.d/domainname</i>
391     <comment>(Set the NISDOMAIN variable to your NIS domain name)</comment>
392     NISDOMAIN="my-nisdomain"
393 jkt 1.11 </pre>
394    
395     <p>
396 cam 1.12 In case you need to use another keyboard layout for your language, you have to
397     set the correct value in <path>/etc/conf.d/syscons</path>. The following example
398     uses the Spanish layout, so you'll have to adjust it to your need if you want to
399     use another one.
400 jkt 1.11 </p>
401    
402     <pre caption="Changing your keyboard layout (Optional)">
403     # <i>ee /etc/conf.d/syscons</i>
404     KEYMAP="spanish.iso.acc"
405     <comment>(Possible layouts can be found in /usr/share/syscons/keymaps).</comment>
406     </pre>
407    
408 neysx 1.1 <impo>
409     Please make absolutely sure you add your new Gentoo/FreeBSD installation to the
410 fox2mike 1.2 configuration of your bootloader, otherwise you won't be able to boot your newly
411 cam 1.12 installed system! If you don't have another bootloader installed, you should use
412 jkt 1.11 <c>boot0</c>, as it is currently the only one supported by FreeBSD. In this case
413 cam 1.12 please don't forget to use your other operating systems to <c>boot0</c>'s
414 jkt 1.11 configuration.
415 neysx 1.1 </impo>
416    
417 fox2mike 1.2 <pre caption="Installing and setting up boot0">
418     # <i>emerge boot0</i>
419     <comment>(Leave the chroot environment)</comment>
420     # <i>exit</i>
421     <comment>(Issued from outside the chroot)</comment>
422 neysx 1.15 # <i>fdisk -B -b /mnt/gentoo/boot/boot0 /dev/adX</i>
423 rane 1.8 # <i>chroot /mnt/gentoo /bin/bash</i>
424 fox2mike 1.2 # <i>disklabel -B adXsY</i>
425     </pre>
426    
427     <p>
428 rane 1.17 If you need additional information on setting up <c>boot0</c>, please consult
429 cam 1.12 <uri
430     link="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/boot.html">chapter
431     12</uri> of the FreeBSD handbook.
432 fox2mike 1.2 </p>
433    
434     <p>
435 cam 1.12 Now would be a good time to set a password for the <c>root</c> user and to add
436 jkt 1.11 another user account for your day-to-day work.
437 fox2mike 1.2 </p>
438    
439 jkt 1.11 <pre caption="Changing the root password and adding a new user">
440     # <i>passwd</i>
441     <comment>(If you need help in adding a user please consult the FreeBSD handbook).</comment>
442     # <i>adduser</i>
443     </pre>
444    
445 fox2mike 1.2 <p>
446 cam 1.12 Congratulations, you have just finished your Gentoo/FreeBSD installation which
447     you can start exploring after the final reboot. Have fun!
448 fox2mike 1.2 </p>
449    
450 jkt 1.11 <pre caption="Rebooting the system">
451     # <i>exit</i>
452     # <i>reboot</i>
453     </pre>
454    
455 neysx 1.1 </body>
456     </section>
457     </chapter>
458    
459     <chapter>
460     <title>Developing for Gentoo/FreeBSD</title>
461     <section>
462 cam 1.4 <title>How to help</title>
463 neysx 1.1 <body>
464    
465     <p>
466     There are many things you could help with, depending on your skill level and
467     spare time:
468     </p>
469    
470     <ul>
471     <li>
472 cam 1.12 Working on current ebuilds: this means working closely with ebuild
473     maintainers in order to create patches or modify ebuilds in a way that can
474     be accepted into the main tree.
475 neysx 1.1 </li>
476     <li>
477     Security: if you are into security, we need you! Although security
478     advisories from the FreeBSD project are tracked and fixed, we can always
479 cam 1.4 use help in this area.
480 neysx 1.1 </li>
481     <li>
482     Contacts: we need people who can get in touch with FreeBSD developers to
483     maintain contacts between us and the original project to exchange patches
484     and discuss various problems and their solutions. Note that this should
485 cam 1.4 never involve any kind of spamming of mailing lists or IRC channels.
486 neysx 1.1 </li>
487     <li>
488     Testing: the more people are actively using Gentoo/FreeBSD, the more bugs
489     will be discovered, which helps us improving the quality of the port. If
490     you are good at describing bugs or problems, we definitely want to hear
491 cam 1.4 from you.
492 neysx 1.1 </li>
493     <li>
494     Other areas where we need help include: system ebuilds, baselayout,
495     creation of installation CDs, documentation, kernel hacking.
496     </li>
497     </ul>
498    
499     </body>
500     </section>
501    
502     <section>
503     <title>Known issues</title>
504     <body>
505    
506     <p>
507     At the moment, there are still quite a lot of known issues. Here are the ones
508     really worth noting:
509     </p>
510    
511     <ul>
512     <li>
513     Some init scripts depend on the clock service which we don't provide right
514     now. You can just remove it from the dependencies of the script and report
515     that on our <uri link="http://bugs.gentoo.org/">bugzilla</uri>. Please
516 cam 1.4 remember to use the "Gentoo BSD" product for your submission.
517 neysx 1.1 </li>
518     <li>glib and gnome in general need a lot of fixes to be backported.</li>
519 neysx 1.15 <li>
520     The init system currently provided by Gentoo/FreeBSD's baselayout package is
521     not the same version used by Gentoo Linux and lacks some of its features. Work
522     on making newer versions working is underway.
523     </li>
524 neysx 1.1 </ul>
525    
526     </body>
527     </section>
528     </chapter>
529    
530     <chapter>
531     <title>Contact</title>
532     <section>
533     <body>
534    
535     <p>
536 cam 1.4 A list of Gentoo/FreeBSD developers can be found at the <uri
537 neysx 1.1 link="/proj/en/gentoo-alt/bsd/fbsd/">project page</uri>. Other ways to contact
538     Gentoo/FreeBSD developers include our IRC Channel <c>#gentoo-bsd</c> on
539 jkt 1.6 Freenode, as well as the <uri link="/main/en/lists.xml">gentoo-bsd mailing
540     list</uri>.
541 neysx 1.1 </p>
542    
543     </body>
544     </section>
545     </chapter>
546     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20