Overlay
Overlays are used in gentoo to install and manage packages that are not available in the main portage tree or for writing and testing new ebuilds.
Overlays can greatly expand the range of packages available for you to install, but are generally contain less-well-tested ebuilds than the main portage tree. Depending on the overlay, there may be no, or very limited support offered for packages from overlays, or systems that use many packages from overlays. In general, don't post bugs for overlay ebuilds.
Be discriminating when adding overlays to your system - the more that you add, the more likely it becomes that they will clutter up your package tree and introduce bugs that the Gentoo developers cannot replicate or fix.
To install an ebuild that you found somewhere, read about making a Local Overlay, then how to add a package to a local overlay.
Contents |
[edit] Types of Overlay
There are three major types of overlay;
- Official Overlays
- Unofficial (user-maintained) Overlays
- Local Overlays
Official overlays are listed on overlays.gentoo.org. They are generally experimental ground for gentoo developers and teams to work on new packages and versions. Further description is available on the Gentoo Overlays Project website and on the List_of_overlays.
Unofficial overlays are those maintained by gentoo users on their own webspace. The quality and trustworthiness of ebuilds in overlays like this is impossible to guarantee - read the ebuilds first and use at your own risk! It is also possible that unofficial overlays may be malicious, and deliberately introduce security holes, such as contaminated versions of core applications like GCC or OpenSSH. Be careful!
Local overlays are overlays which exist only on users local hard disks. Generally these have two uses;
- Installing packages from ebuilds found on bugzilla or elsewhere
- ebuild testing and writing
[edit] Per overlay control of keywords
Sometimes one wants to use unstable packages from an overlay, but stable packages from the main gentoo repo, or the other way around. Setting ACCEPT_KEYWORDS in make.conf applies to the main portage repo and all overlays. To achieve per-overlay control of accepted keywords, do not set ACCEPT_KEYWORDS in make.conf
Instead, set the desired unstable repos in package.keywords, where "gentoo" is the main portage overlay. For example, to use unstable packages from portage and the pentoo overlay, set the following in package.keywords
*/*::gentoo */*::pentoo
Remember that mixing stable and unstable packages can lead to problems in many cases. Use with care, and don't expect support if you break packages by using odd combinations of unstable packages.
[edit] Using Overlays with Portage - Layman
Layman is a tool designed to help automate management of your local repository of overlays you want included into your Gentoo system. Most of its documentation can be found on its website or man page.
Start with installing Layman.
[edit] Listing and Adding Overlays
You can print a list of overlays to choose from:
Add an overlay by using:
You may first have to install the version control system used by the overlay you need.
Or, you can adjust the USE flags of the app-portage/layman package, and re-emerging layman will automatically pull in the version control systems that you specify.
Example:
Davical and the awl library ebuilds are available on the sunrise overlay. You'll have to add this overlay to your system:
emerge layman
From there, you can keep the overlay in sync with the command:
[edit] make.conf
Once you have added at least one overlay, uncomment the ``source <PATH>`` line below as appropriate for your version of layman.
... # If you have >=app-portage/layman-1.3.0 # source "/var/lib/layman/make.conf" # If you have >=app-portage/layman-1.2.0 # source "/usr/local/portage/layman/make.conf" # If you have <app-portage/layman-1.2.0 # source "/usr/portage/local/layman/make.conf" ...
[edit] Synchronising
Just like portage, overlays need to be synchronised to keep up to date.
Individually:
Or all added overlays:
[edit] Using Overlays with Paludis
Paludis has full native support for multiple repositories. Overlays are merely a special case where a repository has another 'master' repository.
In its default location, /etc/paludis/repositories contains configuration files for overlays. You can add an overlay by manually writing new files, or by using playman -- a ruby script included with Paludis when built with ruby. playman can only create repository information files, not modify or delete them. You'll have to do this manually.
Please note that if you're using Paludis, you might not need a local overlay, because paludis comes with a neat tool called importare.
It is also possible to install extra overlays from paludis. You need to have the special repository of repositories (aka r^2 repository) added to paludis :
format = unavailable name = layman location = /var/repositories/overlays/layman sync = tar+http://git.exherbo.org/layman_repositories.tar.bz2 importance = -100
"unavailable"-type repository will contain other repositories. It also contains information on packages they provide, for searching purposes.
But you will also need another repository to track what repositories you installed with paludis :
format = repository
config_filename = /etc/paludis/repositories/%{repository_template_name}.conf
config_template = /etc/paludis/repository.template
Now, every added repository will appear as additional *.conf file in /etc/paludis/repositories. And it will be removed once you uninstall a repository with paludis.
File repository.template can be used to provide certain defaults for repositories, e.g. location on disk, location of extra caches paludis can optionally use, etc.
You can put here all valid repository configuration stanzas, format and sync have to be unmodified.
format = %{repository_template_format}
location = /var/repositories/%{repository_template_name}
sync = %{repository_template_sync}
master_repository = gentoo
names_cache = /mnt/storage/overlays/paludis_data/names
write_cache = /mnt/storage/overlays/paludis_data/meta
distdir=/mnt/storage/distfiles
It is recommended to keep names_cache and write_cache outside of repository directory. If repository is synced with rsync these directories will be erased every time, causing problems.
Every repository added will have the same settings as this file, variables %{repository_template_format} and %{repository_template_name} and %{repository_template_sync} will be altered according to repository's settings accordingly.
Before you can use this repository with paludis, you need to sync it first
cave sync x-layman
Now you can e.g. add sunrise repository by issuing a command :
cave resolve repository/sunrise -x
Which will make paludis set up /etc/paludis/repositories/sunrise.conf and sync that repository. It will also be recorded as installed.
Adding a repository might fail if you are missing necessary tools to check out files from it, e.g. subversion, git, rsync etc.
[edit]
The "unavailable"-type repository not only contains list of other repositories, but also carries an index of packages each of these repositories provides.
Packages from these repositories will show up in search results and will be taken into consideration when trying to resolve installation plan when using paludis.
For example, let's look at example system. It uses classic gentoo repository named "gentoo" and unavailable-type repository named "layman".
User tries to find app-admin/paco package with paludis. This package is not available in gentoo repository.
cave show paco
* app-admin/paco
::layman (2.0.9-r1 (in ::foo-overlay))X* {:0}
app-admin/paco-2.0.9-r1:0::layman (in ::foo-overlay)
Description Source code package organizer
Owning repository foo-overlay
Repository description Piotr's fixes and new packages
Repository homepage http://github.com/slashbeast/foo-overlay
Masked
unavailable In a repository which is unavailable
The following can be established from the message :
- version 2.0.9-r1 is in foo-overlay
- foo-overlay is in layman repository
- the system is not using the foo-overlay repository
In other words, package app-admin/paco is currently unavailable, because system is not using the foo-overlay repository.
To be able to install the package the repository called "foo-overlay" must first be added to the active repositories list.
cave resolve repository/foo-overlay -x
After doing this, package will become available.
Similar message will show up when attempting to install an unavailable package, with a similar suggestion about repository.
[edit] Removing Overlays
If you want to remove an overlay from your system, you should check what you have installed from it first. To do this, we will use the eix tool.
You will now have some output displaying all the packages that you have installed, where *one version or more is available in the overlay*. This is not the same as "everything listed is something that you have installed from an overlay". You may have packages installed, where some versions are from the portage tree and others from the overlay. Do not remove these, you just have to make sure that you have the versions from portage, not from the overlay.
Check the output, and remove the packages that you don't want/need any more.
Update, depclean, then remove extra packages.
Run eix once more to check: (there should be no output)
[edit] Removing Overlays with Layman (portage)
Finally, remove the overlay:
Check that no dependencies are broken.
[edit] Removing Overlays with Paludis
TODO: Need paludis info.
[edit] Local Overlays
[edit] Creating a Local Overlay with Portage
To create a local overlay, the first step is to choose a directory in which it will live. A common place is /usr/local/portage/. You also need to add a profiles directory and specify a repository name.
Next, you need to make portage aware of the overlay through make.conf
... PORTDIR_OVERLAY="/usr/local/portage/" # If you have added overlays with layman, this line must be below the PORTDIR_OVERLAY line source /var/lib/layman/make.conf ...
[edit] Creating a Local Overlay with Paludis
Paludis users need to create a new file in /etc/paludis/repositories/, for example one called /etc/paludis/repositories/local_overlay.conf. In it, place these contents:
location=${ROOT}/usr/local/portage/
sync =
master_repository = gentoo
format = ebuild
names_cache = ${location}/.cache/names
write_cache = /var/cache/paludis/metadata
And sync this repository:
[edit] Adding packages to a Local Overlay
Now you can add ebuilds to /usr/local/portage/ in the same way the portage tree, or any ebuild-style overlay is populated.
For example, if you want to emerge www-foo/foofox-3.5 which you found in the bug tracker, create a directory for it, move the ebuild into the directory.
Next, you need to create a digest for portage to use to check the files that it downloads (Read up on writing ebuilds to find out what digests are).
Now you can install it like any other package.
and put your ebuild inside /usr/local/portage/my-libs/mypackage/
If you're using paludis, don't forget to sync your local overlay first.
[edit] See Also
[edit] External Links
- Gentoo Overlays
- Project Sunrise - Gentoo User Overlay
- Layman
- gentoo.zougloub.eu Search engine for packages in the main tree, plus overlays.
- gpo.zugaina.org Search engine for packages in overlays and main tree.
- Gentoo Overlays: Users' Guide
- Layman homepage
- browse overlays that you have not installed
