Funtoo Linux FAQ

General Funtoo Stuff

What is funtoo.org?

Funtoo.org is a place to put all my stuff.

What kind of stuff?

Well, I have Funtoo Linux, which is a Gentoo Linux variant. Then I have technical articles -- some new, and some updated versions of originals that appeared on IBM developerWorks.

Then I have Metro, an operating system build tool, and I have keychain, which is a tool to help you manage RSA and DSA keys for ssh.

So Funtoo is not just Funtoo Linux.

What is 'Funtoo' all about? And 'Funtoo Linux'?

Funtoo by itself refers to this site, or the larger Funtoo project run by Daniel Robbins. That's just a fancy way of saying that Funtoo refers to all the stuff I'm doing.

Funtoo Linux refers specifically to my variant of Gentoo Linux.

If you see me use the phrase Funtoo Portage tree or Funtoo ebuild, I'm just talking about our separate (and slightly different) Portage tree, or our version of an ebuild.

Is Funtoo Linux a fork of Gentoo Linux?

It depends on your definition of fork. Officially, I am calling Funtoo Linux a Gentoo Linux variant, meaning that it is more like another flavor of Gentoo than a fork.

We share our changes and bug fixes with the Gentoo project, so Gentoo is free to merge in any of our changes at any time. We also merge in Gentoo's changes every few days.

I could officially call Funtoo Linux a fork of Gentoo Linux, but Gentoo could merge most of our changes into Gentoo proper and then what would Funtoo Linux be? It'd be my variant of Gentoo, that's what it'd be. So let's just call it a variant of Gentoo.

What is the best way to interact with the Funtoo community?

I recommend joining the funtoo-dev mailing list and, if desired, hanging out in the #funtoo irc channel on freenode.

The funtoo-dev mailing list as well as the #funtoo irc channel are unmoderated, open discussion forums for both Funtoo Linux users and developers. In addition, these are also the official lists for discussing other Funtoo projects such as Metro and Keychain.

What is the minimum kernel version I can use with Funtoo Linux?

Both Funtoo Linux stable and Funtoo Linux unstable will be compatible with kernel 2.6.18 and above for the forseeable future, because being compatible with RHEL 5 kernels is important to me.

I test compatibility with 2.6.18-based Red Hat Enterprise Linux kernels. Some server and virtualization configurations require a RHEL 5 kernel to work correctly. For this reason, we will maintain compatibility with 2.6.18+ and RHEL 5.3+ kernels in particular. This policy will be re-evaluated as future versions of RHEL are released.

This is a lower kernel version than is currently compatible with a default install of Gentoo. Gentoo is using a version of sys-fs/udev that requires kernel 2.6.20 or later.

Why is Funtoo Linux still using udev-135?

Funtoo Linux currently uses udev-135 by default rather than a later version, because it maintains compatibility with 2.6.18-based (and in particular, enterprise) kernels and greater. RHEL 5.3 is currently using udev-095, and SLES 11 is using udev-128. There is a masked udev-146+ available for those who need it.

I am keeping udev-135 the default so that critical enterprise Linux functionality is not impacted in the default build of Funtoo.

Funtoo Linux's udev-135 ebuild is completely different from the Gentoo udev-135 ebuild. It has different initialization scripts, and has also been patched to address a security issue that affected udev prior to version 141.

But udev-135 is incompatible with pulseaudio.

I now have an easy fix for this -- unmask udev-146 or greater. Funtoo now has a modern udev ebuild, with "extras" support, but you must unmask it if you need it. To unmask, do the following:

install -d /etc/portage/package.unmask
echo "sys-fs/udev" > /etc/portage/package.unmask/udev

In a future desktop profile, a modern udev will likely be unmasked by default.

What Architectures does Funtoo Linux support?

While Funtoo Linux can run on any architecture that Gentoo Linux supports, we are only maintaining Funtoo Linux for x86 and amd64 architectures. Adding support for other architectures may require a little bit of unmasking work in our Portage tree -- or not. We're not testing anything but x86 and amd64, so we don't know :)

Why is your package.mask a directory?

I decided to convert /usr/portage/profiles/package.mask to a directory as soon as I discovered that this was a supported feature in the current Portage. This allows a modular approach to be used for package.mask, so that funtoo-related masks can be organized and kept separate from upstream masks. This allows us to maintain the package.masks more easily.

How should a developer use package.mask?

We currently have four files in the package.mask directory -- gentoo, funtoo, funtoo-cautionary and sunrise. Gentoo is an almost pristine version of the upstream gentoo package.mask. It differs from gentoo only in that we will remove stuff from it that we no longer want in it, but we don't add masks to this file. So if there is a mask in gentoo, you know it came upstream from Gentoo.

funtoo is where we place our masks. funtoo-cautionary is where we place masks that are designed to shield us from upstream unstable version changes to core packages, since we don't want to simply follow Gentoo unstable -- instead, we want to control when gcc and glibc switch to new versions. sunrise contains a bunch of sunrise and other miscellaneous masks from the mpd overlays. It is currently sort of our "junk drawer" that we'll get around to cleaning up at some point.

Do you use the normal Gentoo system profiles?

I've made some minor changes to the Funtoo Linux profiles/ directory, and I'll continue to make improvements as time goes on. The most recent change I made (as of 17 Jul 2009) was to add net-dns/openresolv to the core system profile. Since Funtoo development focuses primarily on the core system, you can expect our system profiles to be somewhat different from Gentoo's. However, from a user perspective, you use them the same way and we have the same profile names that are in Gentoo.

Is Funtoo Linux More Stable Than Gentoo Linux?

That is a hard question to answer directly, as one person's definition of "stable" may be different than another person's, and I do not know how you intend to use Funtoo Linux. So rather than tackle the question head-on, I can give you some additional information that may help you decide:

  • Both Funtoo Linux and Gentoo Linux have a stable and unstable (~) tree
  • The Funtoo and Gentoo trees are 99% identical. However, there are signficant differences in certain areas, particularly the core system and Perl.
  • Funtoo and Gentoo trees do have some significant differences for core packages, particularly openrc, baselayout and udev.
  • If it is important to you, Metro is tested daily to ensure that it can build Funtoo Linux (and Gentoo Linux) successfully. However, these builds are not performed in advance of the changes hitting the public git-based Portage tree.
  • Any Metro Funtoo Linux build failures found are typically fixed in the Funtoo Portage within 0-1 days. Gentoo build failures are only fixed if they are related to an issue with Metro. So there is very fast response in Funtoo to core system build failures. In Gentoo, this process is not as integrated.
  • Funtoo merges in upstream changes from Gentoo Portage every 1-3 days.
  • Daniel Robbins focuses primarily on using and testing the core, non-GUI/non-X system.
  • The Funtoo tree contains Perl 5.10 and a few other merged trees. Perl 5.8 in Gentoo is no longer being maintained by the Perl developers. However, Perl 5.10 has not been tested in Funtoo Linux as thoroughly as Perl 5.8 has been tested in Gentoo.
  • Both Funtoo Linux stable and unstable will soon have OpenRC 0.5.0, dhcpcd-5 and OpenResolv integrated by default. This does mean that Funtoo will soon experience some key changes to how network interfaces are configured.
  • Funtoo Linux unstable tries to upgrade certain core packages such as udev, gcc and glibc much less frequently than Gentoo unstable. This may or may not be a benefit to you, depending on what you are looking for. Basically, I am trying to offer the package updates of Gentoo Linux unstable without as much of the (too frequent, in my opinion) core system changes that can often cause problems for people.
  • The Funtoo tree typically receives one large Gentoo merge every few days. In contrast, the Gentoo rsync tree receives updates hourly. This means that the changes in the Funtoo tree are compressed into a single monolithic event, whereas the Gentoo tree undergoes continual, but less signficant, change every hour.
  • Significant build-related bugs found by Funtoo that also impact Gentoo Linux are sent upstream to bugs.gentoo.org.

Do you use Gentoo's Guide XML for Documentation?

I originally created Gentoo's Guide XML format for documentation, but I've recently decided to transition away from it in favor of ReStructuredText. ReStructuredText is a plaintext markup syntax that is easy to edit or read in a regular text-based text editor, but that can be converted to other formats such as XML and HTML.

Nearly all of funtoo.org articles and documents are maintained in ReStructuredText format. HTML versions of the documentation are generated by first converting the .rst file to XML using rst2xml.py (part of the docutils distribution), and then using XSLT to convert the resultant XML to HTML. This allows more control over the output than using rst2html.py, so I can do things like expand Bio and Copyright macros, etc.

To view the plaintext ReStructuredText version of a document, append /index.rst to any funtoo.org URL. For example, here is the ReStructuredText version of this document

The documents and scripts used to generate this Web site are located on Funtoo's GitHub website project page.

Are you looking for translators?

Many kind people have provided translations of the funtoo.org pages, and the old version of the site used to contain these translations. However, after much consideration, I've decided to not provide translated versions of funtoo.org pages, for several reasons:

  • Translated documents tend to become out-of-date
  • Updating the translated documents is quite a bit of work
  • Most people online seem to have at least a basic grasp of English

For these reasons, I'm going to focus on improving the quantity and quality of English documentation, and not focus on translations for now.

Using Funtoo Linux, Portage and Git

How do I start using Funtoo Linux?

For information on how to start using Funtoo Linux, see the Funtoo Linux Quick Install Guide.

Is it possible to convert an existing Gentoo Linux install to Funtoo Linux?

Yes, quite a few people have converted an existing Gentoo Linux installation to Funtoo Linux in-place, and it should generally work. However, you should be aware of a few things before attempting this:

  • We do not officially support this method, and although it has worked for many people, it may not work for you. Do not do this on a system where you have no allowance for failure.
  • The preferred method of installing Funtoo Linux is to install it from scratch.
  • You should back up any critical data first. We do not guarantee that you will not run into issues.
  • Again, prepare for failure. Something may go wrong with the transition and you may be left with an inoperable system. You should be prepared to perform a fresh install of Funtoo Linux if this happens.
  • Even if you successfully migrate to Funtoo Linux, it may be difficult to migrate back to Gentoo Linux due to differences in core packages, and due to the fact that we don't actively test migrations from Funtoo Linux to Gentoo Linux, nor do we account for this in our ebuilds.
  • Don't do this with the idea of being able to switch back and forth between Gentoo Linux and Funtoo Linux "on the fly." That is not something that the Funtoo project or the Gentoo project supports, and it will not work.
  • We only suggest this approach for competent and responsible Linux users.

To convert an existing Gentoo Linux installation to Funtoo Linux, you will need to perform the following steps:

  • Unmask and install the latest 2.2-based version of Portage
  • emerge git
  • Move your existing /usr/portage to /usr/portage.old.
  • Download a Funtoo Portage snapshot from the Funtoo Portage snapshot repository.
  • Extract it to /usr, then enter /usr/portage and type git checkout funtoo.org
  • Run emerge --sync to update your tree and cache metadata for optimal performance
  • You should now be able to upgrade core packages. Try emerge -aveD world --jobs=4
  • Be sure to run etc-update prior to rebooting
  • Consult the Funtoo Linux Quick Install Guide to ensure you are familiar with configuration differences between Funtoo Linux and Gentoo Linux, and modify your network and modules configuration accordingly.
  • At this point, your system should be converted into a Funtoo Linux system.

If this process fails for any reason, we'd be interested to know where you ran into issues. Please contact us on the funtoo-dev mailing list to let us know. However, because we don't officially support this in-place conversion, we may simply suggest that you try again by installing Funtoo Linux the normal way from a LiveCD, as detailed in the Funtoo Linux Quick Install Guide.

I can't use emerge --sync to download an initial Portage tree.

Yes, Portage doesn't do that yet. To grab an initial Portage tree, download a current git-based snapshot from from the Funtoo Portage snapshot repository. Then, type the following commands:

# cd /usr
# tar xf /path/to/portage-current.tar.bz2
# cd portage
# git checkout funtoo.org

Once you have git-based Portage tree in place, Portage 2.2 will realize that you are using Funtoo Linux and will perform git updates rather than rsync updates when you type emerge --sync.

How do I update my git-based Portage tree?

If you already have an existing git-based Portage tree, you can update it by typing:

# emerge --sync

I set up my initial git-based Portage tree, but /usr/portage seems to be empty.

You forgot to type:

# cd /usr/portage
# git checkout funtoo.org

Funtoo Linux's portage tree snapshot ships with a mostly empty branch active by default to reduce the size of the resultant snapshot tarball.

Git complains and aborts when I emerge --sync.

It appears that a previous git merge was interrupted or did not complete, leaving your portage tree in an intermediate state. Typically, this can be fixed by typing:

# cd /usr/portage
# git reset --hard origin/funtoo.org

This should restore your portage tree to a consistent state and allow future emerge --sync commands to complete successfully.

If this doesn't work, then you may have a conflicted merge. Maybe you modified some local ebuilds? To view conflicts, type git diff --stat from within the /usr/portage directory. You can choose to either resolve these conflicts or revert back to the official Funtoo Portage tree.

If you want to throw away your local changes and simply use the Funtoo Portage tree, you'll need to remove all the files in /usr/portage besides the .git directory, and then trying the git reset --hard origin/funtoo.org command again, as follows:

# cd /usr/portage
# mv distfiles ..
# rm -rf * .gitignore
# git reset --hard origin/funtoo.org
# mv ../distfiles .

Now everything should be working again.

I can't seem to use overlays with Funtoo Linux. What's wrong?

To use overlays with Funtoo Linux, create an /etc/portage/repos.conf file containing the following lines:

[funtoo]
aliases = gentoo

Information regarding this change is covered in Zack Medico's blog post.

How do I tell if a problem I am having originates from Gentoo or Funtoo?

You can tell if there are any Funtoo changes to an ebuild by typing:

# git diff origin/gentoo.org package-version.ebuild

Any differences will be displayed to the terminal. If there is no output, then our version of the ebuild is the same as the gentoo version.

How can I see the differences between the Gentoo and Funtoo Portage trees?

Here are various ways you can compare the Gentoo and Funtoo Portage trees:

$ git log origin/funtoo.org ^origin/gentoo.org
$ git log --graph --left-right origin/funtoo.org..origin/gentoo.org
$ git diff --name-status origin/gentoo.org
$ git diff origin/gentoo.org

Thanks to Caleb Cushing for this list of commands.

Is Paludis compatible with the Funtoo Portage tree?

Paludis does not appear to be compatible with the Funtoo Portage tree, unfortunately. It does not support the package.mask directory without additional hooks, and also does not support merging device nodes. These features are supported by by Portage and we use both of these capabilities. I think that both package.mask (and package.keywords, etc.) directories are a good idea, and I also think it's a good idea for the package manager to support device nodes, which is particularly useful for the udev and baselayout ebuilds. Funtoo Linux has separate versions of these packages, and these ebuilds are easier to maintain if device nodes are correctly supported by the package manger, and the package.mask directory is a great help to us as well.

We could maintain a patched version of Paludis that would be useable with the Funtoo Portage tree, but I don't want to get into the business of supporting a non-standard package manager as the upstream project seems not seem very supportive of getting these compatibility issues resolved, and thus this could turn into a maintenance burden for Funtoo. So I'd rather just not support Paludis for now.

How do I report a bug?

The best way to report your bug is to describe the issue you are having on the funtoo-dev mailing list. Another option is to ask for support in the #funtoo irc channel. In general, it's best to contact us first about an issue you are having, rather than opening a Gentoo bug report, unless you are quite familiar with the issue and are fairly certain that it is not a Funtoo Linux issue.

If you report a bug to Gentoo that may impact Funtoo Linux in some way, please post information about it to the funtoo-dev mailing list so we are aware of the issue.

How do I become a Funtoo developer?

We don't have any special process for turning someone into an official Funtoo developer. Participate in the funtoo-dev mailing list and #funtoo irc channel, share patches with us, clone our tree, and collaborate with us.

Forking the Portage Tree

I have forked my own Portage tree. How do I generate metadata for it?

First, add FEATURES="metadata-transfer to your /etc/make.conf file. Then type the following commands:

# cd /usr/portage
# egencache --update --jobs=4
# cd metadata/cache
# git add .
# git commit -a

egencache is part of sys-apps/portage and was kindly integrated by Zack Medico, Portage maintainer.

I want to revert a package tree in my repository to the Gentoo or Funtoo version.

I perform this step in the funtoo.org tree whenever Gentoo merges something from the sunrise overlay into Gentoo. When this happens, I want to remove our old sunrise version in our tree and simply continue to track the new upstream Gentoo version. I also don't want to have to deal with merge conflicts, so I want our ebuild directory to match the ebuild directory tree from Gentoo exactly. Here are the steps I follow to do it. So, say my current working branch is funtoo.org and I perform a merge:

# git merge origin/gentoo.org

I have some conflicts, and some of them are in the net-misc/foobar directory. Upon investigation, I see that net-misc/foobar was part of sunrise but has now been merged into Gentoo. To prevent future merge conflicts, I want to throw away our version and add Gentoo's net-misc/foobar tree. Here's how to do it:

# cd net-misc
# git rm -rf foobar
# git checkout origin/gentoo.org -- foobar

The net-misc/foobar tree in the index now matches the one from origin/gentoo.org exactly. The next step (after resolving all outstanding conflicts and generating and adding new metadata -- see FAQ question above) is to simply run git commit -a.

Where can I learn more about git?

So, you want to learn more about git, do you? Here's some inside information -- take the time to get familiar with how git's architecture works internally. This will help you to truly understand git, and make your journey much more rewarding. To get this in-depth understanding of git, I strongly recommend you take a look at the following resources as soon as you're able:

Git Architecture

In addition to understanding git's internal architecture, you'll also need to know how to do things both complex and mudane using git. Here is a bunch of documentation, articles and videos that will help you to become productive with git:

Documentation

Recommended Articles

Recommended Videos

About the Author

silly photo
This is not really me

Daniel Robbins is the founder of the Gentoo community and creator of the Gentoo Linux operating system. Daniel resides in New Mexico with his wife Mary and two energetic daughters, and is founder and lead of Funtoo. Daniel has also written many technical articles for IBM developerWorks, Intel Developer Services and C/C++ Users Journal.