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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.4 - (show annotations) (download) (as text)
Sun Sep 11 16:27:55 2005 UTC (13 years, 6 months ago) by cam
Branch: MAIN
Changes since 1.3: +26 -26 lines
File MIME type: application/xml
Fixed minor typos, no content changes.

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-freebsd.xml,v 1.3 2005/09/10 21:09:01 rane Exp $ -->
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.2</version>
32 <date>2005-09-10</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 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 </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 functions 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 dependencies 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. Accessing ext2/ext3 partitions is already
114 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 <comment>(Create a home directory for root.)</comment>
175 # <i>mkdir /mnt/gfbsd/root</i>
176 </pre>
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>
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 </pre>
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>
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>
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>
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 CHOST="i686-gentoo-freebsd5.4"
214 ACCEPT_KEYWORDS="~x86-fbsd ~x86"
215 FEATURES="-sandbox collision-protect"
216 PORTDIR_OVERLAY="/usr/local/portage/gentoo-freebsd"
217 </pre>
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>
224 <pre caption="Obtaining the portage tree">
225 # <i>emerge --sync</i>
226 </pre>
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>
233 <pre caption="Final configuration">
234 <comment>(Prevent crt1.o from getting removed by emerging gcc.)</comment>
235 # <i>chflags schg /usr/lib/crt1.o</i>
236 <comment>(Update the binutils installed by the stage3 tarball.)</comment>
237 # <i>emerge -u binutils</i>
238 <comment>(Select the correct gcc.)</comment>
239 # <i>gcc-config 1</i>
240 # <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 # <i>emerge --nodeps python portage py-freebsd</i>
245 </pre>
247 <note>
248 After gcc-config you will notice a message about GCC-SPECS which you can safely
249 ignore.
250 </note>
252 <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>
258 <pre caption="Rebuilding the FreeBSD core packages">
259 # <i>emerge -e system</i>
260 </pre>
262 <impo>
263 Please make absolutely sure you add your new Gentoo/FreeBSD installation to the
264 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 </impo>
269 <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>
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>
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>
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>
302 </body>
303 </section>
304 </chapter>
306 <chapter>
307 <title>Developing for Gentoo/FreeBSD</title>
308 <section>
309 <title>How to help</title>
310 <body>
312 <p>
313 There are many things you could help with, depending on your skill level and
314 spare time:
315 </p>
317 <ul>
318 <li>
319 We need GCC and binutils hackers who are able to port FreeBSD's patches to
320 the original versions of these tools provided by our main Portage tree.
321 </li>
322 <li>
323 Working with userland ebuilds: this means working closely with other
324 developers in order to have our changes/patches accepted into the main tree.
325 </li>
326 <li>
327 Security: if you are into security, we need you! Although security
328 advisories from the FreeBSD project are tracked and fixed, we can always
329 use help in this area.
330 </li>
331 <li>
332 Contacts: we need people who can get in touch with FreeBSD developers to
333 maintain contacts between us and the original project to exchange patches
334 and discuss various problems and their solutions. Note that this should
335 never involve any kind of spamming of mailing lists or IRC channels.
336 </li>
337 <li>
338 Testing: the more people are actively using Gentoo/FreeBSD, the more bugs
339 will be discovered, which helps us improving the quality of the port. If
340 you are good at describing bugs or problems, we definitely want to hear
341 from you.
342 </li>
343 <li>
344 Other areas where we need help include: system ebuilds, baselayout,
345 creation of installation CDs, documentation, kernel hacking.
346 </li>
347 </ul>
349 </body>
350 </section>
351 <section>
352 <title>Building the system and dealing with issues</title>
353 <body>
355 <p>
356 Although Linux and FreeBSD both are Unix-like operating systems, there are some
357 important differences you have to know about if you want to contribute to our
358 development effort:
359 </p>
361 <ul>
362 <li>
363 FreeBSD doesn't use the GNU autotools (autoconf, automake, autoheader).
364 Instead, it uses its own implementation of <c>make</c>, putting
365 configuration options in external files and some .mk files that are
366 included with each Makefile. Although a lot of work has been put into
367 those .mk files, it is not hard to find some installations failing due to
368 a missing <c>${INSTALL}&nbsp;-d</c> somewhere. The easy way to deal with
369 this kind of problem is to read the Makefile to find the accompanying .mk
370 file, then open that file and try to figure out which part failed (this is
371 not really hard once you figure out where in the installation process it
372 stopped).
373 </li>
374 <li>
375 Besides, due to the fact that FreeBSD is a complete operating system, you
376 won't find things like a FreeBSD kernel tarball for download on a web site.
377 The system is meant to be concise, thus whenever you start making an ebuild
378 for something that uses system sources, you are very likely to run into
379 problems when it tries to access non-existent files or directories. This
380 generally occurs when a Makefile points to <path>${.CURDIR}/../sys</path>,
381 or when a Makefile has a source dependency on another system package. There
382 is no default rule on dealing with such issues, but generally one of the
383 following procedures helps:
384 <ul>
385 <li>
386 If the ebuild is trying to access kernel sources, patch it to point to
387 <path>/usr/src/sys</path>
388 </li>
389 <li>
390 If it's trying to access some other source that is provided by the
391 system, it's easier to add it to <c>$SRC_URI</c> and unpack it to
392 <c>$WORKDIR</c>
393 </li>
394 </ul>
395 </li>
396 <li>
397 In order to maintain a concise buildsystem, we have several tarballs which
398 are grouped by their functionality. This means that system libraries can be
399 found in the freebsd-lib tarball, which contains the sources you would
400 usually find in /usr/src/lib. On the other hand, freebsd-usrsbin contains
401 <path>/usr/sbin/*</path> tools and consists of sources from
402 <path>/usr/src/usr.sbin</path>.
403 </li>
404 </ul>
406 </body>
407 </section>
408 <section>
409 <title>Known issues</title>
410 <body>
412 <p>
413 At the moment, there are still quite a lot of known issues. Here are the ones
414 really worth noting:
415 </p>
417 <ul>
418 <li>
419 Some init scripts depend on the clock service which we don't provide right
420 now. You can just remove it from the dependencies of the script and report
421 that on our <uri link="http://bugs.gentoo.org/">bugzilla</uri>. Please
422 remember to use the "Gentoo BSD" product for your submission.
423 </li>
424 <li>
425 Some ebuilds have hardcoded -ldl flags to link against libdl to get
426 <c>dlopen()</c>. This needs to be fixed.
427 </li>
428 <li>
429 xorg-x11 and .15 won't build. Until this has been fixed, you can
430 revert to xorg-x11- An ebuild can be obtained via <uri
431 link="http://viewcvs.gentoo.org">ViewCVS</uri>.
432 </li>
433 <li>glib and gnome in general need a lot of fixes to be backported.</li>
434 </ul>
436 </body>
437 </section>
438 </chapter>
440 <chapter>
441 <title>Contact</title>
442 <section>
443 <body>
445 <p>
446 A list of Gentoo/FreeBSD developers can be found at the <uri
447 link="/proj/en/gentoo-alt/bsd/fbsd/">project page</uri>. Other ways to contact
448 Gentoo/FreeBSD developers include our IRC Channel <c>#gentoo-bsd</c> on
449 Freenode, as well as the mailing list <mail>gentoo-bsd@gentoo.org</mail>. To
450 subscribe just send an empty email to
451 <mail>gentoo-bsd-subscribe@gentoo.org</mail> and follow the instructions
452 included in the reply.
453 </p>
455 </body>
456 </section>
457 </chapter>
458 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20