template: post title: Gentoo overlays for noobs author: flewkey timestamp: 1617058460 license: CC-BY In Gentoo, packages are stored in ebuild repositories. The primary repository is the [Gentoo](https://gitweb.gentoo.org/repo/gentoo.git/) repository, and users can add secondary repositories (overlays) on top of it. All you need to make an overlay of your own is a text editor. You should also install a quality assurance tool to check your work. The two that I know of are [app-portage/repoman](https://packages.gentoo.org/packages/app-portage/repoman) and [dev-util/pkgcheck](https://packages.gentoo.org/packages/dev-util/pkgcheck). --- ### Creating the overlay 1. `mkdir test-overlay && cd $_` 2. `mkdir profiles metadata` 3. `echo test-overlay > profiles/repo_name` 4. `echo masters = gentoo > metadata/layout.conf` Congratulations, you now have the basic directory structure of a Gentoo overlay. Now that we've named our repository and set the repository master to the Gentoo ebuild repository, we are ready to go. At this point, you can turn this folder into a git repository, create your initial commit, and push it somewhere. I personally recommend doing this since it makes changes easy to track, and allows you to sync it between devices. If you don't want to do this, add `auto-sync = false` to your layout.conf to tell Portage not to sync it with anything. To check that your repository is good, run `repoman` or `pkgcheck scan` in the root of your repository. It is good to keep an eye on it to keep the quality of your ebuilds from going in the gutter. After that, let's tell Portage about it! Create `/etc/portage/repos.conf/test-overlay.conf` and add the following: ``` [test-overlay] location = /path/to/test-overlay auto-sync = No ``` Your repository is now ready for packaging data. --- ### Our first ebuild In Gentoo, [ebuilds](https://wiki.gentoo.org/wiki/Ebuild) are used to make packages. An ebuild is like a recipe that tells Portage how to build and install a package. For this example, we're going to make an ebuild for [gui-apps/swaybg](https://packages.gentoo.org/packages/gui-apps/swaybg). Don't peek at the Gentoo ebuild yet! First, let's create a folder for the package. `mkdir -p gui-apps/swaybg && cd $_` Before we make an ebuild, let's create a metadata.xml file. Vim users will notice that this is already filled out, thanks to the power of [gentoo-syntax](https://gitweb.gentoo.org/proj/gentoo-syntax.git). We can specify a bit more, but all we need is a maintainer. ``` john@example.com John Doe ``` Now we can create an ebuild. First, open [the swaybg repository](https://github.com/swaywm/swaybg) and check the version that we want to package. The only version is "1.0", so we can package that. Let's create a file called "swaybg-1.0.ebuild". For vim users the gentoo-syntax tool should have already filled part of this out for you. If not, it should be something like this. ``` # Copyright 2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 EAPI=7 DESCRIPTION="" HOMEPAGE="" SRC_URI="" LICENSE="" SLOT="0" KEYWORDS="~amd64 ~x86" DEPEND="" RDEPEND="${{DEPEND}}" BDEPEND="" ``` By the way, information about naming ebuilds is available on the [development guide](https://devmanual.gentoo.org/ebuild-writing/file-format/index.html#file-naming-rules). ### Information Now, we should fill out the metadata. Let's add a description, paste in the homepage link, and specify the license as "MIT". The SRC_URI should link to a copy of the latest version, like so: `SRC_URI="https://github.com/swaywm/${{PN}}/archive/${{PV}}.tar.gz -> ${{P}}.tar.gz"` A list of variables that you can use are also available on the [development guide](https://devmanual.gentoo.org/ebuild-writing/variables/index.html), by the way. ### Dependencies We can see that swaybg uses meson to build, so we will write `inherit meson` at the top of the ebuild to inherit [meson.eclass](https://devmanual.gentoo.org/eclass-reference/meson.eclass/index.html). This will automatically make our ebuild use the Meson build system. Now, we deal with dependencies. Runtime dependencies go in RDEPEND, and build dependencies are split between BDEPEND and DEPEND. In practice, DEPEND is used to list dependencies required for both building and using the package, hence the RDEPEND="${{DEPEND}}" line. A look into meson.build shows the following dependencies: - wayland-client - wayland-protocols - cairo - gdk-pixbuf-2.0 - scdoc (optional) Looking closely, we can also see that pkgconfig is used in meson.build, so pkgconfig is a dependency as well. We also won't need to list meson as a dependency, since we already inherited meson.eclass. (If the version of Meson it requires is unstable though, it might be worth adding it to prevent Portage from trying and failing to build it with the stable version.) Now let's track down the packages for our dependencies. - [dev-libs/wayland](https://packages.gentoo.org/packages/dev-libs/wayland) - [dev-libs/wayland-protocols](https://packages.gentoo.org/packages/dev-libs/wayland-protocols) - [x11-libs/cairo](https://packages.gentoo.org/packages/x11-libs/cairo) - [x11-libs/gdk-pixbuf](https://packages.gentoo.org/packages/x11-libs/gdk-pixbuf) - [virtual/pkgconfig](https://packages.gentoo.org/packages/virtual/pkgconfig) - [app-text/scdoc](https://packages.gentoo.org/packages/app-text/scdoc) Shoving them all into the DEPEND variable wouldn't be the end of the world, but it is good to sort them out. All of these are required for building the package, so none of them will go in RDEPEND. As for BDEPEND, we know that pkgconfig and wayland-protocols obviously won't be needed to run it. This leaves scdoc. We know that it goes in BDEPEND, but it is an optional dependency that is _only used to build documentation_, so we will make it optional. ### Optional manpages First, we will add the [man](https://packages.gentoo.org/useflags/man) USE flag to our ebuild, and use the + sign to enable it by default. Because this is a global use flag, we do not need to define it in metadata.xml. `IUSE="+man"` Then, we will specify app-text/scdoc as an optional dependency in BDEPENDS: `man? ( app-text/scdoc )` Finally, we need to tell Meson to only build documentation when the "man" USE flag is enabled. The meson.build file shows that the man-pages Meson option controls this. It is passed to the "required" argument, making it a [feature option](https://mesonbuild.com/Build-options.html#features). The meson.eclass docs provide us with an [example](https://devmanual.gentoo.org/eclass-reference/meson.eclass/index.html#lbAE) of how to configure Meson based on USE flags, so I will blatantly copy that. ``` src_configure() {{ local emesonargs=( $(meson_feature man man-pages) ) meson_src_configure }} ``` ### Finishing Now, we will generate a Manifest, which will allow Portage to check the integrity of the ebuild and it's source files. We can use the ebuild tool to do this. `ebuild ./swaybg-1.0.ebuild manifest` Alternatively, repoman users can use the following command to generate the Manifest for an entire folder. `repoman manifest` All right, this should be complete! Now, it is time to run `repoman` or `pkgcheck scan` to look for issues. If it looks similar to what's below, then all should be good. ``` # Copyright 2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 EAPI=7 inherit meson DESCRIPTION="Wallpaper tool for Wayland compositors" HOMEPAGE="https://github.com/swaywm/swaybg" SRC_URI="https://github.com/swaywm/${{PN}}/archive/${PV}.tar.gz -> ${{P}}.tar.gz" LICENSE="MIT" SLOT="0" IUSE="+man" KEYWORDS="~amd64 ~x86" DEPEND=" dev-libs/wayland x11-libs/cairo x11-libs/gdk-pixbuf " RDEPEND="${{DEPEND}}" BDEPEND=" dev-libs/wayland-protocols virtual/pkgconfig man? ( app-text/scdoc ) " src_configure() {{ local emesonargs=( $(meson_feature man man-pages) ) meson_src_configure }} ``` After this, you should try to merge your ebuild to check for issues. Assuming that you have added your repository to repos.conf, you can merge it like a normal ebuild. `emerge -1 gui-apps/swaybg::test-overlay` Alternatively, assuming that your dependencies are already installed, you can merge it directly. `ebuild ./swaybg-1.0.ebuild merge` ### Committing In an ebuild repository, it is generally a good idea to prefix your commit message with the name of your package. We will add our Manifest and ebuild, then commit. `git add Manifest swaybg-1.0.ebuild` `git commit -m "gui-apps/swaybg: New package"` Users of repoman can also use `repoman commit`, which will automatically prefix their commit with the package name and add some extra information. Once you're happy, feel free to push your work. Just make sure that it is in good shape. Changing history and forcing a git push in an ebuild repository is a terrible idea. ### Checking our work Now let's look at [swaybg-1.0.ebuild](https://gitweb.gentoo.org/repo/gentoo.git/tree/gui-apps/swaybg/swaybg-1.0.ebuild) and see how we did. Despite trying to be thorough for the sake of the blog post, I still missed some things. - x11-libs/gdk-pixbuf and x11-libs/cairo are under BDEPEND - I did not notice that they were statically linked since I don't understand Meson well. - It prevents swaybg from running alongside versions of gui-wm/sway below 1.1_alpha1 - Likely because that is the version where [swaybg became standalone](https://github.com/swaywm/sway/releases/tag/1.1-rc1). - Compiler warnings are silenced - They are probably only useful for developers, so why not? - The ebuild uses usex instead of meson_feature - meson_feature wasn't added until [2019-03-17](https://gitweb.gentoo.org/repo/gentoo.git/commit/eclass/meson.eclass?id=eeb4c7afa12a3acb5773fbfdb4e6e1b1f626e731), so the authors probably just missed it. Hopefully this gave a bit of insight into making ebuilds in Gentoo. Making an ebuild is easy, but making a good quality ebuild takes practice. There are many techniques to learn while making ebuilds, and the resources below will help greatly. Use them, keep making ebuilds, and they will improve with time. Good luck, and godspeed! - [Gentoo Ebuild Repository](https://gitweb.gentoo.org/repo/gentoo.git/) - It is smart to see how Gentoo developers do their work. - [Gentoo Development Guide](https://devmanual.gentoo.org/) - Contains the eclass reference, function reference, etc. - [Gentoo Python Guide](https://dev.gentoo.org/~mgorny/python-guide/) - [#gentoo-dev-help @ freenode](https://webchat.freenode.net/?channels=#gentoo-dev-help) - [Gentoo Portage Overlays](http://gpo.zugaina.org/) - Allows you to search for ebuilds from different overlays. --- ### Sharing with others If you've made your overlay into a git repository, you can easily share it with your friends! Although they could always clone it and add it to their repos.conf manually, it is easier to do so using a tool. The two I know of are [app-eselect/eselect-repository](https://packages.gentoo.org/packages/app-eselect/eselect-repository) and [app-portage/layman](https://packages.gentoo.org/packages/app-portage/layman). For eselect-repository, they can run the following command: `eselect repository test-overlay git https://git.example.com/test-overlay.git` For layman, the only easy way I know of is to create your own [repositories.xml](https://api.gentoo.org/overlays/repositories.xml) list with your repository in it, upload it somewhere, and get people to specify it with layman. `layman -f -o https://example.com/repositories.xml -a test-overlay` You will likely want to get your repository added to the [Gentoo overlays](overlays.gentoo.org) list, which will allow users to add your repository by name and avoid the shenanigans above. Information on how to do this is available on [the wiki](https://wiki.gentoo.org/wiki/Project:Overlays/Overlays_guide). By the way, if you would like your ebuilds to go to the most people, you can always contribute to the [GURU](https://wiki.gentoo.org/wiki/Project:GURU) project, or some other appropriate overlay. Have fun writing ebuilds!