[ << ] [ < ] [ Home ] [ > ] [ >> ]

2. Gentoo/Alt Overlay

• The Overlay
• Development

2.a. The Overlay

Reasoning behind

Gentoo/Alt projects often need to change current ebuilds to let them know about their userland, libc or what else. These changes can be non-trivial, and should usually be hold until the maintainer of the ebuild can take a look to the patches and make sure that they works as intended.

The drawback is that then Gentoo/Alt users can't make use of the ebuilds on the fly, and developers might try to do the same thing more than one time as they might not know what the other developers worked on.

The overlay idea is took from Gentoo/FreeBSD, that used the overlay to apply patches that involved, for example, malloc patches, userland checks and other things that should have been reviewed before going into main tree.

In and Out

The overlay is intended to work as a cache of ebuilds while they are being tested (for totally new packages) or while the patches are being reviewed by ebuild maintainers.

In the case of packags that goes on the overlay just to wait for review by ebuilds maintainers, their addition should be direct, with obviously the same name of the original package. It's usually better, if the patch is trivial, to open a bug and note that in the ChangeLog for the overlaid package just before adding the package to the overlay itself, unless the patches needs to be tested for a while before submitting them to the ebuild maintainer.

As soon as a patch is merged in main tree, the ebuilds in the overlay needs to go, to avoid having unneeded ebuilds there. It's also important to have the ebuilds be in sync with the main tree in case of revision bumps.

Where

For developers, the overlay is available on Gentoo's Subversion repositories in svn+ssh://username@svn.gentoo.org/var/svnroot/gentoo-alt/trunk/overlay. It's not restricted, so please don't go over other's changes without notifying before, unless they causes problem on all the systems. Always try to get a solution that does work for every project while changes the minimum quantity of code.

As the overlay is intended to be used by users, too, daily snapshots can be found on mirrors as /experimental/snapshots/portage-alt-overlay-latest.tar.bz2. The daily snapshot can be fetched and used as portage overlay, and should be safe to be used in both Gentoo/Alt and Gentoo/Linux systems, also if might happen that the overlay interfere with Gentoo/Linux. In case that happens, remember to contact Gentoo/Alt developers so that the issues can be checked and resolved.

2.b. Development

Committing

One of the reasons why Subversion was chosen instead of CVS is that it supports atomic commits, does not expand keywords (like $Header: $) and so we can use it without using a two-step commit for manifests.

For this reason, the third line of ebuilds is safe to remain $Header: $ so that it will be safe when it's being moved to main portage.

When committing, it's important to use echangelog, also if it's an overlay to state the reasons why the ebuild is being changed. It's simple to write a bash function to get the commit done at one time:

svncommit() {
  [[ -n $(echo *.ebuild) ]] && { echangelog "$@" }
  ebuild $(ls *.ebuild | head -n 1) manifest || return 1
  svn ci -m "$@" || return 1
}

Repoman still has a couple of issues when used in overlays, especially with Subversion, and with extra categories, as it's being done on Gentoo/Alt, but these things can be easily fixed in the future, and are just side problems.

echangelog still does not support Subversion-reposited ebuilds, so until it supports them fully, its output will be a bit limited, not telling when files are added and when are removed. It also returns a failure error to the caller, so it can't be checked against for failures.

Distfiles

Because ebuilds in the overlay are public to the users, their distfiles should be present in the mirrors. As the overlay ebuilds are not parsed by mirroring scripts, the distfiles loaded directly into the local dev.gentoo.org distfiles directory will be removed when "dead" distfiles are removed.

To avoid having the distfiles removed, especially for tarballs that was created ad-hoc, it's important to whitelist the extra files. To do so, log into dev.gentoo.org and open the /space/distfiles-whitelist/current file. There, place one by line all the files you put or are going to put in the mirrors that should not be removed. The whitelist lasts for six months.

[ << ] [ < ] [ Home ] [ > ] [ >> ]

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.