Custom repository

From Gentoo Wiki
(Redirected from Overlay/Local overlay)
Jump to: navigation, search

Creating a local overlay

See Handbook:AMD64/Portage/CustomTree#Defining a custom repository

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 the 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 to a newer version of app-emulation/docker.

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

Now test the installation:

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

Finished ebuilds should be added to the version control system. If using git, consider adding a pull request to GitHub.

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

Do not do this:

root # # cd /usr/portage/app-emulation/docker
root # # cp docker-1.11.0 docker-1.12.6
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

See also


  1. one example of semantic version number is described on