diff --git a/posts/2021-03-29-gentoo-overlays-for-noobs.md b/posts/2021-03-29-gentoo-overlays-for-noobs.md new file mode 100644 index 0000000..2bddcab --- /dev/null +++ b/posts/2021-03-29-gentoo-overlays-for-noobs.md @@ -0,0 +1,344 @@ +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!