flewkey/flewkey.com
1
0
Fork 0
Code Releases Activity

Blog: Gentoo overlays for noobs

Browse Source
This commit is contained in:
Ryan Fox 2021-03-29 23:06:03 +00:00
parent d3c284c79e
commit fe3ef13a1b
Signed by: flewkey
GPG Key ID: 94F56ADFD848851E
1 changed files with 344 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

344
posts/2021-03-29-gentoo-overlays-for-noobs.md Normal file
View File

@ -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.
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
<pkgmetadata>
<maintainer type="person">
<email>john@example.com</email>
<name>John Doe</name>
</maintainer>
</pkgmetadata>
```
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!