/[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.14 - (hide annotations) (download) (as text)
Thu Mar 2 13:32:47 2006 UTC (8 years, 8 months ago) by yoswink
Branch: MAIN
Changes since 1.13: +7 -6 lines
File MIME type: application/xml
Updated broken Gentoo/freebsd overlay link. Thanks to Flameeyes for the new link.

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

  ViewVC Help
Powered by ViewVC 1.1.20