Reading time: 4 minutes, 0 seconds
When creating packages for experimental software or cutting edge versions of stable ones, it is common to use Overlays. in Gentoo.
The tool the manage these overlays is called layman. Obviously, there are several references describing how to add your overlay to the list of the official ones that are available through layman.
For more information about layman, please refer to layman wiki page
Finally, I had time to resume working on the enlightenment-live overlay, that I maintain. Therefore, I am gonna give you a little bit of information that I collected during my time creating ebuilds and setting up a pipeline to make sure the ebuilds were reasonably ok.
File system structure
Gentoo has an abundant documentation about Overlays. At this Gentoo Overlays Wiki page you can find a perfect starting point.
Besides the obvious structure having one folder for each ebuild category, each one containing a folder per package, I added a couple of other entries. Below, you can find my overlay structure, naturally based on the structure outlined at this Gentoo Wiki Page
enlightenment-live | README.md | └───examples | | # Example files | └───package.keywords | └───package.use └───metadata | | # Overlay metadata | └───layout.conf └───profiles | | # Specify settings for individual architecture | └───hppa | | | # Mask a use flag for a package on specific platform | | └───package.use.mask └───sets | | # Definition of sets, AKA collections of packages to be installed together | └───enlightenment-core-9999 | └───enlightenment-apps-9999
Apparently, using the
profiles folder is not very common. I did not find a lot of examples. Nevertheless, I find it extremely useful.
Basically, you can specify use flags to be excluded on a specific platform. This can be quite handy on certain occasions. Personally, I used it to mask the
vlc flag on architecture on which it is not supported.
Test it locally
Once your overlay has been created and getting populated with its first ebuilds, you most probably want to test them locally. You can easily set.
/etc/portage/make.conf and set the
PORTDIR_OVERLAY to the folder containing your overlay.
Now emerge will take that folder into account when looking for ebuilds.
Minimum repository validation
Gentoo has a small and handy utility to make sure ebuilds are properly written. The utility is repoman. More information is available on its Gentoo Repoman Wiki Page.
This is the output I get when I run
repoman full -d
ebuild.badheader 2 app-editors/ecrire/ecrire-9999.ebuild: Stale CVS header on line: 3 app-misc/equate/equate-9999.ebuild: Stale CVS header on line: 3 ebuild.minorsyn 1 x11-wm/enlightenment/enlightenment-9999.ebuild: Ebuild contains leading spaces on line: 39 Please fix these important QA issues first. RepoMan sez: "Make your QA payment on time and you'll never see the likes of me."
For a comprehensive list of errors and what do they mean, refer to this page The first problem was silly and I just had to update the ebuild with the recent template. The latter was just a matter of tab instead of spaces (I mixed some vim and pycharm editing).
After addressing them, you should read something like
RepoMan scours the neighborhood... RepoMan sez: "If everyone were like you, I'd be out of business!"
Once you feel confident and ready to release your overlay, you can proceed to share it by submitting a pull request at https://github.com/gentoo/api-gentoo-org to merge the relevant change to include your overlay. Please, do refer to the Gentoo documentation about this.