Difference between revisions of "Creating Your Own Overlay"

From Funtoo
Jump to navigation Jump to search
(46 intermediate revisions by 13 users not shown)
Line 1: Line 1:
This page intends to get your local overlay going, show how to revision bump a package, and sync your goodies to github.
More involved developers may want to consider contributing to Funtoo Linux by maintaining an independent ''overlay''.  


We will use /var/overlay as primary location directory. This directory can be located anywhere, below is an example location.
Traditionally, an overlay is a Portage repository that can be added dynamically to a user's system to augment the available ebuilds and [[Catpkg|catpkgs]]. However, with Funtoo it is also possible for our automated scripts to merge your overlay, or parts of it, into Funtoo Linux itself. If you are maintaining quite a few ebuilds, this lets us "pull" from your independently-maintained overlay so that you don't need to submit lots of pull requests via https://code.funtoo.org. So it can be a very serious time savings for developers who are more advanced.
{{console|body=###i## mkdir /var/overlay}}


Clone the skeleton from github.  Change the repo name from skeleton to your own repo name as you want to see it when emerging.
==Creating Your Overlay ==


{{console|body=###i##  cd /var/overlay
There are two ways to create an overlay that we'll cover. The first is quite simple and can be done via https://code.funtoo.org. Simply go to https://code.funtoo.org/bitbucket/projects/CO/repos/skeleton-overlay/browse and click the "Create fork" button:
###i## git clone http://git.funtoo.org/skeleton-overlay/ local && cd local
###i## echo "myoverlayname" > /var/overlay/local/profiles/repo_name}}


Change the readme message to what you want to show up on the front page of your repo:  
[[File:create fork.png|480px|center]]


{{file|name=/var/overlay/local/README.rst|lang=|desc=Set the github front page message|body=
At this point, you will be presented with the next screen, where you should type in a new name for your overlay, ''disable fork syncing'', and click "Fork Repository".
This overlay is from so and so funtoo user.  Order a $15/month container today @ funtoo.org
}}


Insert portage structure category & package directories. For example i want to fix apparmor to include the very latest source , i would mkdir -p /var/overlay/local/sys-apps/apparmor then copy the old ebuild i found online (or on my computer) to the directory.  {{f|/var/overlay/local/sys-apps/apparmor/apparmor-2.8.4.ebuild}} is where the old ebuild would sit.  Copy it to the latest upstream version number.  {{c|cp apparmor-2.8.4.ebuild apparmor-2.9.2.ebuild}} then run the ebuild manifest file.
[[File:fork_overlay2.png|480px|center]]


{{console|body=###i## mkdir -p /var/overlay/local/app-category/package-name
=== Making it Public ===
###i## mv package-oldversion.ebuild /var/overlay/local/app-category/package-name/package-oldversion.ebuild
###i## cp /var/overlay/local/app-category/package-name/package-oldversion.ebuild /var/overlay/local/app-category/package-name/package-newversion.ebuild
###i## ebuild *.ebuild manifest}}


for init files, patches etc:
You have now created your own initial overlay, but it is not visible to the public. To make it visible to the public, go to {{c|Repository Settings}}, then {{c|Repository Permissions}} and finally check {{c|Public Access -- Enable}}. Your repository can now be seen (but not modified) by others.
example{{c|/var/overlay/local/sys-apps/apparmor/files/apparmor-init}}
{{console|body=###i## mkdir /var/overlay/local/app-category/package-name/files
###i## nano /var/overlay/local/app-category/package-name/files/package-init}}


Add your overlay to make.conf:
=== Learning More About code.funtoo.org ===
{{file|name=/etc/portage/make.conf|lang=|desc=Insert the local overlay|body=
PORTDIR_OVERLAY="/var/overlay/local"
}}


You're ready to emerge the new version, you don't need to sync, you can make minor changes, then emerge, and if it breaks again you can make more minor changes, and emerge again. Once you're satisfied with the ebuild its time to share your fun goodies.
To learn more about code.funtoo.org, please see the following video. We will still need to perform some finishing steps to get the overlay ready for use, which we will cover below.
=== GIT ===
{{note|make [[SSH#Passwordless_Authentication | ssh keys]] and upload them to github or else entering your password will get very old very quick.}}


https://github.com/666threesixes666  = my github user account<br />
{{#evt:service=youtube|id=https://youtu.be/V6PfB64oMWo|dimensions=480|alignment=center|autoresize=true}}
https://github.com/666threesixes666/tripsix = my /var/overlay/local/profiles/repo_name contents




{{console|body=###i## cd /var/overlay/local
=== Cloning and Finishing Touches ===
###i## git init
 
###i## git add .
You will now want to add a ssh key to code.funtoo.org (see video above for more information.) Then, clone it locally, and perform the following steps to properly set the overlay name:
###i## git commit -m 'First commit'
 
###i## git remote add origin git@github.com:666threesixes666/tripsix.git
{{console|body=
###i## git remote set-url origin git@github.com:666threesixes666/tripsix.git
$ ##i##git clone ssh://git@code.funtoo.org:7999/~drobbins/my-overlay.git
###i## git remote -v
Cloning into 'my-overlay'...
###i## git push origin master}}
remote: Enumerating objects: 16, done.
remote: Counting objects: 100% (16/16), done.
If flaws are discovered in your ebuild, you can repair the ebuild/patches/init files/conf.d files within them and upload them to github by these commands:
remote: Compressing objects: 100% (12/12), done.
{{console|body=###i## cd /var/overlay/local
remote: Total 16 (delta 4), reused 0 (delta 0)
###i## git add . && git commit -m 'updates' && git push origin master}}
Receiving objects: 100% (16/16), 8.64 KiB {{!}} 8.64 MiB/s, done.
Resolving deltas: 100% (4/4), done.
$ ##i##cd my-overlay
$ ##i##echo "my-overlay" > profiles/repo_name
$ ##i##sed -i 's/skeleton/my-overlay/' metadata/layout.conf
$ ##i##git add .
$ ##i##git commit -a -m "Setting initial repo name."
$ ##i##git push
}}
 
{{Tip|Now is also a good time to review the {{c|README.rst}} and {{c|LICENSE.txt}} and customize as needed.}}
 
Now, your overlay is ready for new ebuilds to be committed to it. But before we do that, we should configure Portage to "see" your overlay and any packages it contains.
 
=== Create repos.conf Entry ===
 
Create the following file in order to register your overlay with Portage:
 
{{file|name=/etc/portage/repos.conf/my-overlay.conf|lang=|desc=Add your overlay to portage|body=
[my-overlay]
location = /home/myuser/my-overlay
auto-sync = no
priority = 10
}}
 
{{tip|The {{c|priority}} key is needed to ensure that your overlay has higher priority to the kit's overlays, which are default priority 1.}}
 
Now, you are ready to add new ebuilds that are not present in portage tree or fix the ebuilds from portage tree you are not satisfied with, updating old packages or removing newer package versions.
 
For example, to create an updated version of the package {{c|net-misc/autossh}} not currently in the repository, create the directory tree {{f|net-misc/autossh}} under {{c|my-overlay}}. In the {{f|autossh}} directory you created, you can add new {{c|autossh-x.y.z.ebuild}} files.
 
[[Category:Portage]]
[[Category:Official Documentation]]

Revision as of 15:54, November 12, 2019

More involved developers may want to consider contributing to Funtoo Linux by maintaining an independent overlay.

Traditionally, an overlay is a Portage repository that can be added dynamically to a user's system to augment the available ebuilds and catpkgs. However, with Funtoo it is also possible for our automated scripts to merge your overlay, or parts of it, into Funtoo Linux itself. If you are maintaining quite a few ebuilds, this lets us "pull" from your independently-maintained overlay so that you don't need to submit lots of pull requests via https://code.funtoo.org. So it can be a very serious time savings for developers who are more advanced.

Creating Your Overlay

There are two ways to create an overlay that we'll cover. The first is quite simple and can be done via https://code.funtoo.org. Simply go to https://code.funtoo.org/bitbucket/projects/CO/repos/skeleton-overlay/browse and click the "Create fork" button:

Create fork.png

At this point, you will be presented with the next screen, where you should type in a new name for your overlay, disable fork syncing, and click "Fork Repository".

Fork overlay2.png

Making it Public

You have now created your own initial overlay, but it is not visible to the public. To make it visible to the public, go to Repository Settings, then Repository Permissions and finally check Public Access -- Enable. Your repository can now be seen (but not modified) by others.

Learning More About code.funtoo.org

To learn more about code.funtoo.org, please see the following video. We will still need to perform some finishing steps to get the overlay ready for use, which we will cover below.


Cloning and Finishing Touches

You will now want to add a ssh key to code.funtoo.org (see video above for more information.) Then, clone it locally, and perform the following steps to properly set the overlay name:

user $ git clone ssh://git@code.funtoo.org:7999/~drobbins/my-overlay.git
Cloning into 'my-overlay'...
remote: Enumerating objects: 16, done.
remote: Counting objects: 100% (16/16), done.
remote: Compressing objects: 100% (12/12), done.
remote: Total 16 (delta 4), reused 0 (delta 0)
Receiving objects: 100% (16/16), 8.64 KiB | 8.64 MiB/s, done.
Resolving deltas: 100% (4/4), done.
user $ cd my-overlay
user $ echo "my-overlay" > profiles/repo_name
user $ sed -i 's/skeleton/my-overlay/' metadata/layout.conf
user $ git add .
user $ git commit -a -m "Setting initial repo name."
user $ git push
   Tip

Now is also a good time to review the README.rst and LICENSE.txt and customize as needed.

Now, your overlay is ready for new ebuilds to be committed to it. But before we do that, we should configure Portage to "see" your overlay and any packages it contains.

Create repos.conf Entry

Create the following file in order to register your overlay with Portage:

   /etc/portage/repos.conf/my-overlay.conf - Add your overlay to portage
[my-overlay]
location = /home/myuser/my-overlay
auto-sync = no
priority = 10
   Tip

The priority key is needed to ensure that your overlay has higher priority to the kit's overlays, which are default priority 1.

Now, you are ready to add new ebuilds that are not present in portage tree or fix the ebuilds from portage tree you are not satisfied with, updating old packages or removing newer package versions.

For example, to create an updated version of the package net-misc/autossh not currently in the repository, create the directory tree net-misc/autossh under my-overlay. In the autossh directory you created, you can add new autossh-x.y.z.ebuild files.