Install a New Overlay

This article is in progress.

This HOWTO is based on the standard directories for overlays and the portage tree. For an example of an alternate location please see the Gentoo installation guide.

An overlay is a secondary portage tree, used to install and manage gentoo packages (ebuilds) which are not in the main portage tree.

The standard overlay location is /usr/portage/overlay/. The standard portage tree location is /usr/portage/tree/. It is important that the overlay and the portage tree are NOT in the same directory. Placing the overlay in the same directory as the portage tree will cause the overlay to be overwritten the first time you emerge sync.

The first thing we need to do is define the overlay directory in /etc/make.conf. It can be useful to keep your previous overlay so we place the new overlay in a unique directory that is at the same level as the previous overlay. In this case it is /usr/portage/overlays/20060122. The 20060122 happens to be the date of the new overlay.

KURO-BOX-EM #cd /etc KURO-BOX-EM etc #nano make.conf

Edit the PORTDIR_OVERLAY line to point to the new overlay directory. PORTDIR_OVERLAY="/var/overlays/20060122"

Next we set up the portage profile. The file /etc/make.profile is a symbolic link from /etc to the profile in the overlay. You will need to remove the old link.

KURO-BOX-EM etc #rm make.profile

We must replace the link with a new link that points to the overlay. The link is the relative diretory from /etc. Notice we have to go up 1 level (../) from /etc before going back down the /usr part of the directory tree. KURO-BOX-EM etc #ln -s ../usr/portage/overlays/20060122/profiles/kurobox make.profile

Next we need to let portage know where the overlay is located. We do this with another symbolic link that points from the profile in the overlay, to the profile in the official portage tree.

KURO-BOX-EM etc #cd /usr/portage/overlays

Notice the 20060122 in the following lines. Change it to the date of your overlay in order to point to the correct directory. It is the relative path from the profile in the overlay to the profile in the official portage tree. Each ../ indicates a directory up in the tree. Just count the directories up and then add the path back down. KURO-BOX-EM overlays #echo "../../../../portage/profiles/default-linux/ppc/2005.1/ppc" > 20060122/profiles/kurobox/parent KURO-BOX-EM overlays #cd /etc

Now lets regenerate the portage cache. This would be a good time for a bathroom break or a quick run to the store for a snack. KURO-BOX-EM etc #emerge metadata Updating Portage cache: 100% KURO-BOX-EM etc #

Now we'll check if the system is up to date while at the same time testing portage. KURO-BOX-EM etc #emerge -puD system