Overlay/Local overlay

From Gentoo Wiki
Jump to: navigation, search

Creating a local overlay

A local overlay is useful for:

  • Installing an ebuild received from someone else.
  • Making a simple version bump to an ebuild.
  • Developing ebuilds.

A local repository (aka local overlay) can be set up with a few steps creating the mandatory elements of the repository format.

root #mkdir -p /usr/local/portage/{metadata,profiles}
root #echo 'NameOfOverlay' > /usr/local/portage/profiles/repo_name
root #echo 'masters = gentoo' > /usr/local/portage/metadata/layout.conf
root #chown -R portage:portage /usr/local/portage

Next, tell Portage about the overlay:

root #mkdir -p /etc/portage/repos.conf
FILE /etc/portage/repos.conf/local.conf
location = /usr/local/portage
masters = gentoo
auto-sync = no
NameOfOverlay is an example and should be changed to something more meaningful in all locations.
Setting the PORTDIR_OVERLAY variable in make.conf is deprecated (since?) and should not be used anymore.

Adding an ebuild to the overlay

Now that the basic layout is in order, you can add an ebuild to the overlay. In this example, app-dicts/artha-1.0.2 (available at [1]). We will assume the ebuild is in the homedir of the user myuser, and named artha-1.0.2.ebuild.

root #mkdir -p /usr/local/portage/app-dicts/artha
root #cp ~myuser/artha-1.0.2.ebuild /usr/local/portage/app-dicts/artha/artha-1.0.2.ebuild
root #chown -R portage:portage /usr/local/portage
root #pushd /usr/local/portage/app-dicts/artha
root #repoman manifest
root #popd

You should now be able to install the package from your overlay with emerge.

root #emerge --ask --verbose --oneshot app-dicts/artha

Simple version bump of an ebuild in the local overlay

In theory one can update an ebuild to the next version number with a "simple version bump". Indicators that this is promising are:

  • upstream fixed only minor bugs
  • dependencies did not change
  • upstream uses semantic version numbers and changed only the minor number [1]
  • the ebuild file is short and does not use many patches

For the simplest bump place a copy of the ebuild in your local overlay and update the version number in the filename.

We assume you have prepared your local overlay in bobs-overlay already and want to bump from app-emulation/docker-1.11.0 to app-emulation/docker-1.11.2

user $ cd /usr/local/overlays/bobs-overlay
user $ cp -r /usr/portage/app-emulation/docker .
user $ cd app-emulation/docker
user $ cp app-emulation/docker-1.11.0 app-emulation/docker-1.11.2
user $ repoman --digest=y -d full

now test the installation

root #emerge --ask =app-emulation/docker-1.11.2

you may add it to your version control system. If you use git:

user $ git add docker-1.11.2.ebuild
user $ git commit -a

Avoid a direct version bump

The direct version bump in the official tree is often suggested, but should be avoided, because

  • all changes get lost on the next sync of the tree
  • user contributions should be separated from the official tree
root # # do not do this:
root # # cd /usr/portage/app-emulation/docker
root # # cp app-emulation/docker-1.11.0 app-emulation/docker-1.11.2
root # # repoman --digest=y -d full


sys-devel/crossdev will place the ebuilds/categories it generates into one of four places in this order.

  1. An overlay specified on the command-line with the --ov-output (-oO) option
  2. An overlay named 'cross-${CTARGET}'
  3. An overlay named 'crossdev'
  4. Finally, it falls back on the overlay having the lowest priority value in /etc/portage/repos.conf/.

Most users will want to prevent crossdev from disturbing layman's overlays or the user's personal per-machine overlay (commonly created at /usr/local/portage). The best solution is to create an overlay specifically for crossdev's use:

root #mkdir -p /usr/local/portage-crossdev/{profiles,metadata}
root #echo 'crossdev' > /usr/local/portage-crossdev/profiles/repo_name
root #echo 'masters = gentoo' > /usr/local/portage-crossdev/metadata/layout.conf
root #chown -R portage:portage /usr/local/portage-crossdev

If the main Portage tree is synchronized by using Git, or any other method with Manifest files that do not include checksums for ebuilds, prevent "masked by: corruption" errors with:

FILE /usr/local/portage-crossdev/metadata/layout.conf
masters = gentoo
thin-manifests = true

Then instruct Portage and crossdev to use this overlay:

FILE /etc/portage/repos.conf/crossdev.conf
location = /usr/local/portage-crossdev
priority = 10
masters = gentoo
auto-sync = no
  1. one example of semantic version number is described on http://semver.org/