how to make your own gentoo linux overlay

So before we start, I have my own overlay @ https://ari.lt/overlay and am running it for a while, it was a bit painful for me to make one at the start and to help new Gentoo users I am making this blog post, anyway, here's how you do it:

# Step one -- Think of a name

Think of a name you will give your overlay because this information will be needed in later steps

# Step two -- Folder structure

To start with we need files and folders to work with, all names ending with a / are folders and everything else is a file, please make sure to also apply the templates in <...>, for example <year> would be the current year:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
./
├── LICENSE
├── metadata/
│  └── layout.conf
├── overlays.xml
├── profiles/
│  └── repo_name
├── README.md
├── repositories.xml
├── sets/
├── sets.conf
└── <overlay name>.conf

# Step three -- License

The LICENSE file should have your license, if it doesn't already please pick one, for example on my overlay I went for GPLv3, but you can also go for some other open source licenses, like GPLv2, WTFPL, BSD 3-clause, etc.

Write that license to the LICENSE file

# Step four -- Master overlays

This step is always the same, you have to set the master overlay in metadata/layout.conf file, the master is usually going to be gentoo, so in metadata/layout.conf add this content:

1
masters = gentoo

# Step five -- Overlay index files

Overlay index files are these files:

Both of these files should have the same content, make sure to fill in the templates that are in SCREAMING_SNAKE_CASE:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE repositories SYSTEM "https://www.gentoo.org/dtd/repositories.dtd">
<repositories xmlns="" version="1.0">
    <repo quality="experimental" status="unofficial">
        <name><![CDATA[OVERLAY_NAME]]></name>
        <description lang="en"><![CDATA[OVERLAY_DESCRIPTION]]></description>
        <homepage>OVERLAY_HOMEPAGE</homepage>
        <owner type="project">
            <email>OWNER_EMAIL</email>
            <name><![CDATA[OWNER_FULL_NAME]]></name>
        </owner>

        <!--
            Optional (this is an example because it's hard to template it):

            <source type="git">https://github.com/TruncatedDinosour/dinolay.git</source>
            <source type="git">git://github.com/TruncatedDinosour/dinolay.git</source>
            <source type="git">git@github.com:TruncatedDinosour/dinolay.git</source>
            <feed>https://github.com/TruncatedDinosour/dinolay/commits/main.atom</feed>
        -->
    </repo>
</repositories>

Once again, don't forget that all of these files have the same exact content, and no, it cannot be a symlink AFAIK

# Step six -- Profiles

You only need one file in the profiles folder -- repo_name, the content of it should be your overlay name, for example:

1
dinolay

This is the repo_name content on my own overlay, basically the template is

1
<overlay name>

# Step seven -- Readme

README.md is an optional file, it's just used for information to give to users, it can have any content but here's a nice template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# <overlay name>

> <overlay description>

## Installation

### Manual

```bash
$ sudo mkdir -p /etc/portage/repos.conf
$ sudo cp <overlay name>.conf /etc/portage/repos.conf/<overlay name>.conf
$ sudo emerge --sync '<overlay name>'
```

### Eselect repository

```bash
$ sudo eselect repository add '<overlay name>' '<overlay sync method (e.g. git)>' '<overlay sync url>'
$ sudo eselect repository enable '<overlay name>'
$ sudo emerge --sync '<overlay name>'
```

And once you get into the Offical Gentoo API, for example Like I did you also add how to add your overlay through layman:

1
2
3
4
5
6
### Layman

```bash
$ sudo layman -a '<overlay name>'
$ sudo layman -s '<overlay name>'
```

# Step eight -- Sets

This directory is optional, although you can have sets of packages in there, like have you ever heard a term called 'world set', it's the same thing, just on your own overlay

Read more about it here

# Step nine -- Sets configuration

This file is needed unlike the sets directory, you should have this content in it, although once again, please don't forget to fill in the template:

1
2
3
4
[<overlay name> sets]
class = portage.sets.files.StaticFileSet
multiset = true
directory = ${repository:<overlay name>}/sets/

# Step ten -- Portage overlay configuration

This file, although optional, will help the users of your overlay so much, they can just download this file, put it in /etc/portage/repos.conf/<repo name>.conf and then run

1
sudo emerge --sync '<repo name>'

And they have it installed, anyway, this is what that file should have

1
2
3
4
[<overlay name>]
location = /var/db/repos/<overlay name>
sync-type = <overlay sync type>
sync-uri = <overlay sync url>

E.g. for git it'd be:

1
2
3
4
[<overlay name>]
location = /var/db/repos/<overlay name>
sync-type = git
sync-uri = https://some.git.service/me/my-overlay.git

# Finishing

And that's it, you can now publish your overlay on for example GitHub, like I did on https://ari.lt/overlay, it's very easy, if you are confused about anything, refer to that repo yourself