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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.1 - (hide annotations) (download) (as text)
Wed Aug 31 14:19:33 2005 UTC (12 years, 3 months ago) by neysx
Branch: MAIN
File MIME type: application/xml
New doc from the G/FreeBSD team

1 neysx 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!-- $Header$ -->
3     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5     <guide link="/doc/en/gentoo-freebsd.xml">
6     <title>A short guide to Gentoo/FreeBSD</title>
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>
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>
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/>
31     <version>1.0</version>
32     <date>2005-08-31</date>
34     <chapter>
35     <title>Introduction to FreeBSD</title>
36     <section>
37     <title>What is FreeBSD?</title>
38     <body>
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>
53     </body>
54     </section>
55     <section>
56     <title>What is Gentoo/FreeBSD?</title>
57     <body>
59     <p>
60     Gentoo/FreeBSD is an effort effort to provide a fully-capable FreeBSD operating
61     system with Gentoo's design sensibilities. The long-term goal of the Gentoo/BSD
62     project is to allow users to choose any combination of *BSD or Linux kernels,
63     *BSD or GNU libc, and *BSD or GNU userland tools.
64     </p>
66     </body>
67     </section>
68     <section>
69     <title>FreeBSD and Linux</title>
70     <body>
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>
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     consistent
85     </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>
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>
100     <ul>
101     <li>
102     To get run-time dynamic linking fuctions like <c>dlopen()</c>, programs do
103     not need to be linked against libdl like on GNU/Linux. Instead they are
104     linked against libc
105     </li>
106     <li>
107     FreeBSD doesn't have an official tool for kernel compilation, thus you'll
108     have to resolve feature dependecies on your own
109     </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     support for these filesystems. However, accessing ext2/ext3 partitions is
114     already possible, but you cannot install your system on them.
115     </li>
116     </ul>
118     </body>
119     </section>
120     </chapter>
122     <chapter>
123     <title>Installing Gentoo/FreeBSD</title>
124     <section>
125     <title>Installation instructions</title>
126     <body>
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>
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>
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>
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>
161     <p>
162     Now that you have mounted the target partition, it is time to fetch and unpack
163     a stage3 tarball.
164     </p>
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     </pre>
176     <p>
177     In order for your install to work, you need to mount the <path>/dev</path>
178     filesystem from the currently running system into the Gentoo/FreeBSD mount
179     point before proceeding with the chroot.
180     </p>
182     <pre caption="Mounting the /dev filesystem and chrooting">
183     # <i>mount -t devfs none /mnt/gfbsd/dev/</i>
184     # <i>chroot /mnt/gfbsd/ /bin/bash</i>
185     </pre>
187     <p>
188     Once inside the chroot you have to obtain a copy of the Gentoo/FreeBSD overlay.
189     If you are not a Gentoo developer, you can get it from the mirror provided by
190     <mail link="carpaski@gentoo.org">Nick Jones</mail>. Theoretically, you could
191     put this overlay in any directory you like, but from now on we will just assume
192     that you have downloaded it to <path>/usr/local/portage/gentoo-freebsd</path>.
193     </p>
195     <pre caption="Getting the Gentoo/FreeBSD portage overlay">
196     # <i>cvs -d:pserver:anonymous@zarquon.twobit.net:/var/cvsroot -q -z9 co -R gentoo-projects/bsd/fbsd/</i>
197     </pre>
199     <p>
200     After you got hold of the Gentoo/FreeBSD overlay, it's time to link
201     <path>/etc/make.profile</path> to the correct profile and add get your
202     <path>/etc/make.conf</path> ready for Gentoo/FreeBSD.
203     </p>
205     <pre caption="Setting up the profile and editing /etc/make.conf">
206     # <i>ln -sf /usr/local/portage/gentoo-freebsd/profiles/default-bsd/fbsd/5.4/x86/ /etc/make.profile</i>
207     <comment>(FreeBSD's standard editor is ee, which is used to edit /etc/make.conf)</comment>
208     # <i>ee /etc/make.conf</i>
209     <comment>(Please make sure you add at least the following entries:)</comment>
210     CHOST="i686-gentoo-freebsd5.4"
211     ACCEPT_KEYWORDS="~x86-fbsd ~x86"
212     FEATURES="-sandbox collision-protect"
213     PORTDIR_OVERLAY="/usr/local/portage/gentoo-freebsd"
214     </pre>
216     <p>
217     Now, you have to obtain a copy of the main Gentoo Portage tree, which depending
218     on your connection might take quite a while.
219     </p>
221     <pre caption="Obtaining the portage tree">
222     # <i>emerge --sync</i>
223     </pre>
225     <p>
226     After you have synchronised your Portage tree, you only have to take a few last
227     steps before your Gentoo/FreeBSD system is ready to use.
228     </p>
230     <pre caption="Final configuration">
231     <comment>(Prevent crt1.o from getting removed by emerging gcc.)</comment>
232     # <i>chflags schg /usr/lib/crt1.o</i>
233     <comment>(Emerge binary packages for binutils and patch provided by the stage3 tarball.)</comment>
234     # <i>emerge -K binutils patch</i>
235     <comment>(Select the correct gcc.)</comment>
236     # <i>gcc-config 1</i>
237     <comment>(Re-emerging python, portage and py-freebsd.)</comment>
238     # <i>emerge python portage py-freebsd</i>
239     </pre>
241     <p>
242     Congratulations, by the time you have reached this step you should have a
243     running Gentoo/FreeBSD system! If you want, you can now rebuild the system's
244     core packages.
245     </p>
247     <pre caption="Rebuilding the FreeBSD core packages">
248     # <i>emerge -e system</i>
249     </pre>
251     <impo>
252     Please make absolutely sure you add your new Gentoo/FreeBSD installation to the
253     configuration of the bootloader, otherwise you won't be able to boot your newly
254     installed system! If you have no bootloader installed, you should run <c>emerge
255     boot0</c>.
256     </impo>
258     </body>
259     </section>
260     </chapter>
262     <chapter>
263     <title>Developing for Gentoo/FreeBSD</title>
264     <section>
265     <title>How to help </title>
266     <body>
268     <p>
269     There are many things you could help with, depending on your skill level and
270     spare time:
271     </p>
273     <ul>
274     <li>
275     We need GCC and binutils hackers who are able to port FreeBSD's patches to
276     the original versions of these tools provided by our main Portage tree
277     </li>
278     <li>
279     Working with userland ebuilds: this means working closely with other
280     developers in order to have our changes/patches accepted into the main tree
281     </li>
282     <li>
283     Security: if you are into security, we need you! Although security
284     advisories from the FreeBSD project are tracked and fixed, we can always
285     use help in this area
286     </li>
287     <li>
288     Contacts: we need people who can get in touch with FreeBSD developers to
289     maintain contacts between us and the original project to exchange patches
290     and discuss various problems and their solutions. Note that this should
291     never involve any kind of spamming of mailing lists or IRC channels
292     </li>
293     <li>
294     Testing: the more people are actively using Gentoo/FreeBSD, the more bugs
295     will be discovered, which helps us improving the quality of the port. If
296     you are good at describing bugs or problems, we definitely want to hear
297     from you
298     </li>
299     <li>
300     Other areas where we need help include: system ebuilds, baselayout,
301     creation of installation CDs, documentation, kernel hacking.
302     </li>
303     </ul>
305     </body>
306     </section>
307     <section>
308     <title>Building the system and dealing with issues</title>
309     <body>
311     <p>
312     Although Linux and FreeBSD both are Unix-like operating systems, there are some
313     important differences you have to know about if you want to contribute to our
314     development effort:
315     </p>
317     <ul>
318     <li>
319     FreeBSD doesn't use the GNU autotools (autoconf, automake, autoheader).
320     Instead, it uses its own implementation of <c>make</c>, putting
321     configuration options in external files and some .mk files that are
322     included with each Makefile. Although a lot of work has been put into
323     those .mk files, it is not hard to find some installations failling due to
324     a missing <c>${INSTALL}&nbsp;-d</c> somewhere. The easy way to deal with
325     this kind of problem is to read the Makefile to find the accompanying .mk
326     file, then open that file and try to figure out which part failed (this is
327     not really hard once you figure out where in the installation process it
328     stopped)
329     </li>
330     <li>
331     Besides, due to the fact that FreeBSD is a complete operating system, you
332     won't find things like a FreeBSD kernel tarball for download on a web site.
333     The system is meant to be concise, thus whenever you start making an ebuild
334     for something that uses system sources, you are very likely to run into
335     problems when it tries to access non-existent files or directories. This
336     generally occurs when a Makefile points to <path>${.CURDIR}/../sys</path>,
337     or when a Makefile has a source dependency on another system package. There
338     is no default rule on dealing with such issues, but generally one of the
339     following procedures helps:
340     <ul>
341     <li>
342     If the ebuild is trying to access kernel sources, patch it to point to
343     <path>/usr/src/sys</path>
344     </li>
345     <li>
346     If it's trying to access some other source that is provided by the
347     system, it's easier to add it to <c>$SRC_URI</c> and unpack it to
348     <c>$WORKDIR</c>
349     </li>
350     </ul>
351     </li>
352     <li>
353     In order to maintain a concise buildsystem, we have several tarballs which
354     are grouped by their functionality. This means that system libraries can be
355     found in the freebsd-lib tarball, which contains the sources you would
356     usually find in /usr/src/lib. On the other hand, freebsd-usrsbin contains
357     <path>/usr/sbin/*</path> tools and consists of sources from
358     <path>/usr/src/usr.sbin</path>.
359     </li>
360     </ul>
362     </body>
363     </section>
364     <section>
365     <title>Known issues</title>
366     <body>
368     <p>
369     At the moment, there are still quite a lot of known issues. Here are the ones
370     really worth noting:
371     </p>
373     <ul>
374     <li>
375     Some init scripts depend on the clock service which we don't provide right
376     now. You can just remove it from the dependencies of the script and report
377     that on our <uri link="http://bugs.gentoo.org/">bugzilla</uri>. Please
378     remember to use the "Gentoo BSD" product for your submission
379     </li>
380     <li>
381     Some ebuilds have hardcoded -ldl flags to link against libdl to get
382     <c>dlopen()</c>. This needs to be fixed
383     </li>
384     <li>
385     xorg-x11 and .15 won't build. Until this has been fixed, you can
386     revert to xorg-x11- An ebuild can be obtained via <uri
387     link="http://viewcvs.gentoo.org">ViewCVS</uri>
388     </li>
389     <li>glib and gnome in general need a lot of fixes to be backported.</li>
390     </ul>
392     </body>
393     </section>
394     </chapter>
396     <chapter>
397     <title>Contact</title>
398     <section>
399     <body>
401     <p>
402     At list of Gentoo/FreeBSD developers can be found at the <uri
403     link="/proj/en/gentoo-alt/bsd/fbsd/">project page</uri>. Other ways to contact
404     Gentoo/FreeBSD developers include our IRC Channel <c>#gentoo-bsd</c> on
405     Freenode, as well as the mailing list <mail>gentoo-bsd@gentoo.org</mail>. To
406     subscribe just send an empty email to
407     <mail>gentoo-bsd-subscribe@gentoo.org</mail> and follow the instructions
408     included in the reply.
409     </p>
411     </body>
412     </section>
413     </chapter>
414     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20