FreeBSD is a free (license) Unix-like operating system. Back in 1993 when development of 386BSD stopped, two projects were born: NetBSD, commonly known to run on a huge number of architetures, and FreeBSD which focuses mainly on the x86 platform. FreeBSD is renowned for its stability, performance and security, thus being used from small to huge companies all over the world. FreeBSD's current production release version is 5.4, which is also used as the foundation for the Gentoo/FreeBSD project.

Gentoo/FreeBSD is an effort effort to provide a fully-capable FreeBSD operating system with Gentoo's design sensibilities. The long-term goal of the Gentoo/BSD project is to allow users to choose any combination of *BSD or Linux kernels, *BSD or GNU libc, and *BSD or GNU userland tools.

Users migrating from Linux to FreeBSD commonly consider the two operating systems "almost the same". In fact, FreeBSD really shares a lot of similarities with Linux distributions in general. Nevertheless, it has some key differences that are worth noting:

• Contrary to Linux, which actually only refers to the kernel, FreeBSD is a complete operating system, consisting of a C library, userland tools and much more. This development approach makes the overall system very consistent
• Contrary to the Linux kernel, FreeBSD development is not led by one person, but instead managed by a small group of people called the Core Team.

Besides, FreeBSD also has some technical differences which set it apart from Linux. Some of them are very important to know, even if you don't plan on joining the Gentoo/FreeBSD development effort:

• To get run-time dynamic linking fuctions like dlopen(), programs do not need to be linked against libdl like on GNU/Linux. Instead they are linked against libc
• FreeBSD doesn't have an official tool for kernel compilation, thus you'll have to resolve feature dependecies on your own
• FreeBSD uses UFS/UFS-2 as its filesystems and has no official support for e.g. ReiserFS or XFS. However, there are projects for adding read-only support for these filesystems. However, accessing ext2/ext3 partitions is already possible, but you cannot install your system on them.

After this short introduction, it's about time to finally install Gentoo/FreeBSD. Unfortunately, we currently lack our own installation media, so you have to choose between two alternative installation methods. The first would be to use an existing FreeBSD installation to partition your hard drive and use it as a base for installing Gentoo/FreeBSD. Alternatively, you can also use the excellent FreeSBIE LiveCD as an installation medium for Gentoo/FreeBSD.

Before you can begin with the installation, you have to setup a hard disk for use with Gentoo/FreeBSD. This can either be done via sysinstall (available from a current FreeBSD installation as well as from within FreeSBIE) or by manually using the commands fdisk, disklabel and newfs. If you have never set up a FreeBSD system before, sysinstall may be the better option for you. If you face difficulties while partitioning or formatting your hard disks, have a look at the great FreeBSD Handbook or hop onto #gentoo-bsd on the Freenode IRC server.

Once you're done setting up your disks, you have to create a mount point for your Gentoo/FreeBSD installation and mount all the necessary partitions.

# mkdir /mnt/gfbsd
(Replace X with the correct numbers for your hard disk.)
# mount /dev/adXsXa /mnt/gfbsd

Now that you have mounted the target partition, it is time to fetch and unpack a stage3 tarball.

(Any other Gentoo mirror which includes the experimental/ directory will also work.)
# wget http://gentoo.osuosl.org/experimental/x86/freebsd/stage3-x86-fbsd-20050811.tar.bz2
# cp stage3-x86-fbsd-20050811.tar.bz2 /mnt/gfbsd/
# cd /mnt/gfbsd/
# tar -jxvpf stage3-x86-fbsd-20050811.tar.bz2
(You can delete the tarball with the following command if you want to.)
# rm stage3-x86-fbsd-20050811.tar.bz2
(Create a home directory for root.)
# mkdir /mnt/gfbsd/root

Before chrooting into the newly-extracted stage, you first must obtain a copy of the Gentoo/FreeBSD overlay. If you are not a Gentoo developer, you can get it from the mirror provided by Nick Jones. Theoretically, you could put this overlay in any directory you like, but from now on we will just assume that you have downloaded it to /usr/local/portage/gentoo-freebsd.

# cvs -d:pserver:anonymous@zarquon.twobit.net:/var/cvsroot -q -z9 co -R gentoo-projects/bsd/fbsd/

In order for your install to work, you need to mount the /dev filesystem from the currently running system into the Gentoo/FreeBSD mount point before proceeding with the chroot.

# mount -t devfs none /mnt/gfbsd/dev/
# chroot /mnt/gfbsd/ /bin/bash

After you got hold of the Gentoo/FreeBSD overlay, it's time to link /etc/make.profile to the correct profile and add get your /etc/make.conf ready for Gentoo/FreeBSD.

# ln -sf /usr/local/portage/gentoo-freebsd/profiles/default-bsd/fbsd/5.4/x86/ /etc/make.profile
(FreeBSD's standard editor is ee, which is used to edit /etc/make.conf)
# ee /etc/make.conf
(Please make sure you add at least the following entries:)
CHOST="i686-gentoo-freebsd5.4" 
ACCEPT_KEYWORDS="~x86-fbsd ~x86" 
FEATURES="-sandbox collision-protect"
PORTDIR_OVERLAY="/usr/local/portage/gentoo-freebsd"

Now, you have to obtain a copy of the main Gentoo Portage tree, which depending on your connection might take quite a while.

# emerge --sync

After you have synchronised your Portage tree, you only have to take a few last steps before your Gentoo/FreeBSD system is ready to use.

(Prevent crt1.o from getting removed by emerging gcc.)
# chflags schg /usr/lib/crt1.o
(Update the binutils installed by the stage3 tarball.)
# emerge -u binutils
(Select the correct gcc.)
# gcc-config 1
# source /etc/profile
(Start the following script to fix a current bug in the stage3.)
# /usr/local/portage/gentoo-freebsd/scripts/domove.sh
(Re-emerge python, portage and py-freebsd.)
# emerge --nodeps  python portage py-freebsd

Congratulations, by the time you have reached this step you should have a running Gentoo/FreeBSD system! If you want, you can now rebuild the system's core packages.

# emerge -e system

# emerge boot0
(Leave the chroot environment)
# exit
(Issued from outside the chroot)
# fdisk -b -B /mnt/gfbsd/boot/boot0 /dev/adX
# chroot /mnt/gfbsd /bin/bash
# disklabel -B adXsY

If you need additonal information on setting up boot0, please consult chapter 12 of the FreeBSD handbook.

When you did emerge system, the sources for the FreeBSD kernel got installed to /usr/src/sys. Configuring and compiling a custom kernel is really different from compiling Linux, so if you are not familiar with the process we encourage you to have a look at chapter 8 of the FreeBSD handbook.

Please note that currently only the "Traditional" way of building the kernel is supported on Gentoo/FreeBSD! Also note that make install will probably ask you for a /boot/device.hints file. A default version can be found in the conf subdirectory of the GENERIC configuration and is called GENERIC.hints

There are many things you could help with, depending on your skill level and spare time:

• We need GCC and binutils hackers who are able to port FreeBSD's patches to the original versions of these tools provided by our main Portage tree
• Working with userland ebuilds: this means working closely with other developers in order to have our changes/patches accepted into the main tree
• Security: if you are into security, we need you! Although security advisories from the FreeBSD project are tracked and fixed, we can always use help in this area
• Contacts: we need people who can get in touch with FreeBSD developers to maintain contacts between us and the original project to exchange patches and discuss various problems and their solutions. Note that this should never involve any kind of spamming of mailing lists or IRC channels
• Testing: the more people are actively using Gentoo/FreeBSD, the more bugs will be discovered, which helps us improving the quality of the port. If you are good at describing bugs or problems, we definitely want to hear from you
• Other areas where we need help include: system ebuilds, baselayout, creation of installation CDs, documentation, kernel hacking.

Although Linux and FreeBSD both are Unix-like operating systems, there are some important differences you have to know about if you want to contribute to our development effort:

• FreeBSD doesn't use the GNU autotools (autoconf, automake, autoheader). Instead, it uses its own implementation of make, putting configuration options in external files and some .mk files that are included with each Makefile. Although a lot of work has been put into those .mk files, it is not hard to find some installations failling due to a missing ${INSTALL} -d somewhere. The easy way to deal with this kind of problem is to read the Makefile to find the accompanying .mk file, then open that file and try to figure out which part failed (this is not really hard once you figure out where in the installation process it stopped)
• Besides, due to the fact that FreeBSD is a complete operating system, you won't find things like a FreeBSD kernel tarball for download on a web site. The system is meant to be concise, thus whenever you start making an ebuild for something that uses system sources, you are very likely to run into problems when it tries to access non-existent files or directories. This generally occurs when a Makefile points to ${.CURDIR}/../sys, or when a Makefile has a source dependency on another system package. There is no default rule on dealing with such issues, but generally one of the following procedures helps:
  • If the ebuild is trying to access kernel sources, patch it to point to /usr/src/sys
  • If it's trying to access some other source that is provided by the system, it's easier to add it to $SRC_URI and unpack it to $WORKDIR
• In order to maintain a concise buildsystem, we have several tarballs which are grouped by their functionality. This means that system libraries can be found in the freebsd-lib tarball, which contains the sources you would usually find in /usr/src/lib. On the other hand, freebsd-usrsbin contains /usr/sbin/* tools and consists of sources from /usr/src/usr.sbin.

At the moment, there are still quite a lot of known issues. Here are the ones really worth noting:

• Some init scripts depend on the clock service which we don't provide right now. You can just remove it from the dependencies of the script and report that on our bugzilla. Please remember to use the "Gentoo BSD" product for your submission
• Some ebuilds have hardcoded -ldl flags to link against libdl to get dlopen(). This needs to be fixed
• xorg-x11 6.8.99.14 and .15 won't build. Until this has been fixed, you can revert to xorg-x11-6.8.99.13. An ebuild can be obtained via ViewCVS
• glib and gnome in general need a lot of fixes to be backported.

At list of Gentoo/FreeBSD developers can be found at the project page. Other ways to contact Gentoo/FreeBSD developers include our IRC Channel #gentoo-bsd on Freenode, as well as the mailing list gentoo-bsd@gentoo.org. To subscribe just send an empty email to gentoo-bsd-subscribe@gentoo.org and follow the instructions included in the reply.