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 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 functions 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 dependencies 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. 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/gentoo
(Replace X with the correct numbers for your hard disk.)
# mount /dev/adXsXa /mnt/gentoo

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

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

Before chrooting into the newly-extracted stage, you first must obtain an up-to-date copy of the Gentoo/FreeBSD overlay. The easiest way to achieve this is to to get our latest snapshot which you than extract to /mnt/gentoo/usr/local/portage

# cd /mnt/gentoo/usr/local/portage
# wget http://gentoo.osuosl.org/experimental/snapshots/portage-alt-overlay-latest.tar.bz2
# tar -xjf portage-alt-overlay-latest.tar.bz2

Alternatively, you can also use Subversion to check out the current version of the overlay. If you are interested in this possibility, please refer to the Gentoo/ALT overlay documentation.

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/gentoo/dev/
# cp /etc/resolv.conf /mnt/gentoo/etc
# chroot /mnt/gentoo/ /bin/bash
# source /etc/profile

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/portage-alt-overlay/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/portage-alt-overlay"

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
(It's also possible to retrieve the Portage tree in another way:)
# cd /
# wget http://gentoo.osuosl.org/snapshots/portage-latest.tar.bz2
# tar -xjf portage-latest.tar.bz2 -C /usr/
# emerge --metadata

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/gentoo/boot/boot0 /dev/adX
# chroot /mnt/gentoo /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 on current ebuilds: this means working closely with ebuild maintainers in order to create patches or modify ebuilds in a way that can be 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 failing 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.
• glib and gnome in general need a lot of fixes to be backported.

A 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 gentoo-bsd mailing list.