/[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.6 - (hide annotations) (download) (as text)
Wed Sep 21 19:16:21 2005 UTC (8 years, 9 months ago) by jkt
Branch: MAIN
Changes since 1.5: +4 -6 lines
File MIME type: application/xml
21:09 <@jkt|> Flameeyes: btw, would you get angry if I change your mailing list stuff to link to lists.xml?
21:10 <@Flameeyes> jkt|, no problem, just don't remove the reference to #gentoo-bsd as there is where we discuss most of the things :P

1 cam 1.4 <?xml version="1.0" encoding="UTF-8"?>
2 jkt 1.6 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-freebsd.xml,v 1.5 2005/09/21 19:04:05 jkt 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     Otavio R. Piske
16     </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 jkt 1.6 <version>1.4</version>
32 jkt 1.5 <date>2005-09-21</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     # <i>mkdir /mnt/gfbsd</i>
157     <comment>(Replace X with the correct numbers for your hard disk.)</comment>
158     # <i>mount /dev/adXsXa /mnt/gfbsd</i>
159     </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     <comment>(Any other Gentoo mirror which includes the experimental/ directory will also work.)</comment>
168     # <i>wget http://gentoo.osuosl.org/experimental/x86/freebsd/stage3-x86-fbsd-20050811.tar.bz2</i>
169     # <i>cp stage3-x86-fbsd-20050811.tar.bz2 /mnt/gfbsd/</i>
170     # <i>cd /mnt/gfbsd/</i>
171     # <i>tar -jxvpf stage3-x86-fbsd-20050811.tar.bz2</i>
172     <comment>(You can delete the tarball with the following command if you want to.)</comment>
173     # <i>rm stage3-x86-fbsd-20050811.tar.bz2</i>
174 rane 1.3 <comment>(Create a home directory for root.)</comment>
175     # <i>mkdir /mnt/gfbsd/root</i>
176     </pre>
177    
178     <p>
179     Before chrooting into the newly-extracted stage, you first must obtain a copy of
180     the Gentoo/FreeBSD overlay. If you are not a Gentoo developer, you can get it
181     from the mirror provided by <mail link="carpaski@gentoo.org">Nick Jones</mail>.
182     Theoretically, you could put this overlay in any directory you like, but from
183     now on we will just assume that you have downloaded it to
184     <path>/usr/local/portage/gentoo-freebsd</path>.
185     </p>
186    
187     <pre caption="Getting the Gentoo/FreeBSD portage overlay">
188     # <i>cvs -d:pserver:anonymous@zarquon.twobit.net:/var/cvsroot -q -z9 co -R gentoo-projects/bsd/fbsd/</i>
189 neysx 1.1 </pre>
190    
191     <p>
192     In order for your install to work, you need to mount the <path>/dev</path>
193     filesystem from the currently running system into the Gentoo/FreeBSD mount
194     point before proceeding with the chroot.
195     </p>
196    
197     <pre caption="Mounting the /dev filesystem and chrooting">
198     # <i>mount -t devfs none /mnt/gfbsd/dev/</i>
199     # <i>chroot /mnt/gfbsd/ /bin/bash</i>
200     </pre>
201    
202     <p>
203     After you got hold of the Gentoo/FreeBSD overlay, it's time to link
204     <path>/etc/make.profile</path> to the correct profile and add get your
205     <path>/etc/make.conf</path> ready for Gentoo/FreeBSD.
206     </p>
207    
208     <pre caption="Setting up the profile and editing /etc/make.conf">
209     # <i>ln -sf /usr/local/portage/gentoo-freebsd/profiles/default-bsd/fbsd/5.4/x86/ /etc/make.profile</i>
210     <comment>(FreeBSD's standard editor is ee, which is used to edit /etc/make.conf)</comment>
211     # <i>ee /etc/make.conf</i>
212     <comment>(Please make sure you add at least the following entries:)</comment>
213 cam 1.4 CHOST="i686-gentoo-freebsd5.4"
214     ACCEPT_KEYWORDS="~x86-fbsd ~x86"
215 neysx 1.1 FEATURES="-sandbox collision-protect"
216     PORTDIR_OVERLAY="/usr/local/portage/gentoo-freebsd"
217     </pre>
218    
219     <p>
220     Now, you have to obtain a copy of the main Gentoo Portage tree, which depending
221     on your connection might take quite a while.
222     </p>
223    
224     <pre caption="Obtaining the portage tree">
225     # <i>emerge --sync</i>
226     </pre>
227    
228     <p>
229     After you have synchronised your Portage tree, you only have to take a few last
230     steps before your Gentoo/FreeBSD system is ready to use.
231     </p>
232    
233     <pre caption="Final configuration">
234 rane 1.3 <comment>(Prevent crt1.o from getting removed by emerging gcc.)</comment>
235 neysx 1.1 # <i>chflags schg /usr/lib/crt1.o</i>
236 rane 1.3 <comment>(Update the binutils installed by the stage3 tarball.)</comment>
237     # <i>emerge -u binutils</i>
238     <comment>(Select the correct gcc.)</comment>
239 neysx 1.1 # <i>gcc-config 1</i>
240 rane 1.3 # <i>source /etc/profile</i>
241     <comment>(Start the following script to fix a current bug in the stage3.)</comment>
242     # <i>/usr/local/portage/gentoo-freebsd/scripts/domove.sh</i>
243     <comment>(Re-emerge python, portage and py-freebsd.)</comment>
244 fox2mike 1.2 # <i>emerge --nodeps python portage py-freebsd</i>
245 neysx 1.1 </pre>
246    
247 rane 1.3 <note>
248     After gcc-config you will notice a message about GCC-SPECS which you can safely
249     ignore.
250     </note>
251    
252 neysx 1.1 <p>
253     Congratulations, by the time you have reached this step you should have a
254     running Gentoo/FreeBSD system! If you want, you can now rebuild the system's
255     core packages.
256     </p>
257    
258     <pre caption="Rebuilding the FreeBSD core packages">
259     # <i>emerge -e system</i>
260     </pre>
261    
262     <impo>
263     Please make absolutely sure you add your new Gentoo/FreeBSD installation to the
264 fox2mike 1.2 configuration of your bootloader, otherwise you won't be able to boot your newly
265     installed system! If you don't have another bootloader installed, you should use
266     <c>boot0</c>, as it is currently the only one supported by FreeBSD.
267 neysx 1.1 </impo>
268    
269 fox2mike 1.2 <pre caption="Installing and setting up boot0">
270     # <i>emerge boot0</i>
271     <comment>(Leave the chroot environment)</comment>
272     # <i>exit</i>
273     <comment>(Issued from outside the chroot)</comment>
274     # <i>fdisk -b -B /mnt/gfbsd/boot/boot0 /dev/adX</i>
275     # <i>chroot /mnt/gfbsd /bin/bash</i>
276     # <i>disklabel -B adXsY</i>
277     </pre>
278    
279     <p>
280     If you need additonal information on setting up <c>boot0</c>, please consult
281     <uri link="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/boot.html">
282     chapter 12</uri> of the FreeBSD handbook.
283     </p>
284    
285     <p>
286     When you did <c>emerge system</c>, the sources for the FreeBSD kernel got
287     installed to <path>/usr/src/sys</path>. Configuring and compiling a custom
288     kernel is really different from compiling Linux, so if you are not familiar with
289     the process we encourage you to have a look at <uri
290     link="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html">
291     chapter 8</uri> of the FreeBSD handbook.
292     </p>
293    
294     <p>
295     Please note that currently only the "Traditional" way of building the kernel is
296     supported on Gentoo/FreeBSD! Also note that <c>make install</c> will probably
297     ask you for a <path>/boot/device.hints</path> file. A default version can be
298     found in the <path>conf</path> subdirectory of the <c>GENERIC</c> configuration
299     and is called <path>GENERIC.hints</path>
300     </p>
301    
302 neysx 1.1 </body>
303     </section>
304     </chapter>
305    
306     <chapter>
307     <title>Developing for Gentoo/FreeBSD</title>
308     <section>
309 cam 1.4 <title>How to help</title>
310 neysx 1.1 <body>
311    
312     <p>
313     There are many things you could help with, depending on your skill level and
314     spare time:
315     </p>
316    
317     <ul>
318     <li>
319     We need GCC and binutils hackers who are able to port FreeBSD's patches to
320 cam 1.4 the original versions of these tools provided by our main Portage tree.
321 neysx 1.1 </li>
322     <li>
323 jkt 1.5 Working on current ebuilds: this means working closely with ebuild maintainers
324     in order to create patches or modify ebuilds in a way that can be accepted
325     into the main tree.
326 neysx 1.1 </li>
327     <li>
328     Security: if you are into security, we need you! Although security
329     advisories from the FreeBSD project are tracked and fixed, we can always
330 cam 1.4 use help in this area.
331 neysx 1.1 </li>
332     <li>
333     Contacts: we need people who can get in touch with FreeBSD developers to
334     maintain contacts between us and the original project to exchange patches
335     and discuss various problems and their solutions. Note that this should
336 cam 1.4 never involve any kind of spamming of mailing lists or IRC channels.
337 neysx 1.1 </li>
338     <li>
339     Testing: the more people are actively using Gentoo/FreeBSD, the more bugs
340     will be discovered, which helps us improving the quality of the port. If
341     you are good at describing bugs or problems, we definitely want to hear
342 cam 1.4 from you.
343 neysx 1.1 </li>
344     <li>
345     Other areas where we need help include: system ebuilds, baselayout,
346     creation of installation CDs, documentation, kernel hacking.
347     </li>
348     </ul>
349    
350     </body>
351     </section>
352     <section>
353     <title>Building the system and dealing with issues</title>
354     <body>
355    
356     <p>
357     Although Linux and FreeBSD both are Unix-like operating systems, there are some
358     important differences you have to know about if you want to contribute to our
359     development effort:
360     </p>
361    
362     <ul>
363     <li>
364     FreeBSD doesn't use the GNU autotools (autoconf, automake, autoheader).
365     Instead, it uses its own implementation of <c>make</c>, putting
366     configuration options in external files and some .mk files that are
367     included with each Makefile. Although a lot of work has been put into
368 cam 1.4 those .mk files, it is not hard to find some installations failing due to
369 neysx 1.1 a missing <c>${INSTALL}&nbsp;-d</c> somewhere. The easy way to deal with
370     this kind of problem is to read the Makefile to find the accompanying .mk
371     file, then open that file and try to figure out which part failed (this is
372     not really hard once you figure out where in the installation process it
373 cam 1.4 stopped).
374 neysx 1.1 </li>
375     <li>
376     Besides, due to the fact that FreeBSD is a complete operating system, you
377     won't find things like a FreeBSD kernel tarball for download on a web site.
378     The system is meant to be concise, thus whenever you start making an ebuild
379     for something that uses system sources, you are very likely to run into
380     problems when it tries to access non-existent files or directories. This
381     generally occurs when a Makefile points to <path>${.CURDIR}/../sys</path>,
382     or when a Makefile has a source dependency on another system package. There
383     is no default rule on dealing with such issues, but generally one of the
384     following procedures helps:
385     <ul>
386     <li>
387     If the ebuild is trying to access kernel sources, patch it to point to
388     <path>/usr/src/sys</path>
389     </li>
390     <li>
391     If it's trying to access some other source that is provided by the
392     system, it's easier to add it to <c>$SRC_URI</c> and unpack it to
393     <c>$WORKDIR</c>
394     </li>
395     </ul>
396     </li>
397     <li>
398     In order to maintain a concise buildsystem, we have several tarballs which
399     are grouped by their functionality. This means that system libraries can be
400     found in the freebsd-lib tarball, which contains the sources you would
401     usually find in /usr/src/lib. On the other hand, freebsd-usrsbin contains
402     <path>/usr/sbin/*</path> tools and consists of sources from
403     <path>/usr/src/usr.sbin</path>.
404     </li>
405     </ul>
406    
407     </body>
408     </section>
409     <section>
410     <title>Known issues</title>
411     <body>
412    
413     <p>
414     At the moment, there are still quite a lot of known issues. Here are the ones
415     really worth noting:
416     </p>
417    
418     <ul>
419     <li>
420     Some init scripts depend on the clock service which we don't provide right
421     now. You can just remove it from the dependencies of the script and report
422     that on our <uri link="http://bugs.gentoo.org/">bugzilla</uri>. Please
423 cam 1.4 remember to use the "Gentoo BSD" product for your submission.
424 neysx 1.1 </li>
425     <li>
426     Some ebuilds have hardcoded -ldl flags to link against libdl to get
427 jkt 1.5 <c>dlopen()</c>. This needs to be fixed (for further information, please
428     consult our <uri link="/proj/en/gentoo-alt/bsd/maintnotes.xml#doc_chap3">
429     our Gentoo/*BSD Technotes Guide</uri>.
430 neysx 1.1 </li>
431     <li>glib and gnome in general need a lot of fixes to be backported.</li>
432     </ul>
433    
434     </body>
435     </section>
436     </chapter>
437    
438     <chapter>
439     <title>Contact</title>
440     <section>
441     <body>
442    
443     <p>
444 cam 1.4 A list of Gentoo/FreeBSD developers can be found at the <uri
445 neysx 1.1 link="/proj/en/gentoo-alt/bsd/fbsd/">project page</uri>. Other ways to contact
446     Gentoo/FreeBSD developers include our IRC Channel <c>#gentoo-bsd</c> on
447 jkt 1.6 Freenode, as well as the <uri link="/main/en/lists.xml">gentoo-bsd mailing
448     list</uri>.
449 neysx 1.1 </p>
450    
451     </body>
452     </section>
453     </chapter>
454     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20