Difference between revisions of "Funtoo:Metatools/Advanced Usage"

Latest revision as of 21:47, June 8, 2022

Subpages:

Important

These pages are out of date. Please see the latest Funtoo:Metatools page for usage information.

Overview

Funtoo Linux uses "merge scripts" to create its kits and update meta-repo. These scripts work by sourcing ebuilds from various overlays, and combining them using special algorithms to yield the kits you use. A meta-repo is also generated, which points to the specific kits generated that are designed to work together.

Before starting, please read and understand the following pages:

Different Approaches

merge-all-kits can be used in a variety of ways. If you are an individual developer, you may want to use merge-all-kits in developer mode, which is its default mode. Developer mode makes it easy to generate a meta-repo and kits that you can test locally.

In developer mode, a meta-repo and all automatically-generated kit git repositories are created from scratch. These git repositories will have no remotes, so they will simply exist locally on disk, and they will not have any history shared with the Funtoo project. It you look at the commit history for the kits and meta-repo, you will see that they essentially have no history.

Another way to use merge-all-kits is with gitolite as a remote, which is documented under the Gitolite Setup sub-page. Using this configuration, merge-all-kits will write all of its destination git repositories to gitolite. You can then configure other systems to ego sync from gitolite as a source. This can be good in a distributed development environment. This method can also be used to create a meta-repo and kits that diverge from Funtoo's kit but still connect to its history.

Finally, the merge-all-kits script can be run in a production mode, which is very similar to using it with gitolite except that you may be pushing up your destination meta-repo and kits to a public location like GitHub or GitLab.

When first starting out with merge-all-kits, you should definitely start with developer mode and see if that meets your needs first.

Getting The Code

You can find the code that does this on code.funtoo.org, housed at code.funtoo.org. The script that does all the heavy-lifting is called merge-all-kits. Let's clone it from git, on the machine that will be generating new kits and meta-repo:

user $ git clone https://code.funtoo.org/bitbucket/scm/core/merge-scripts.git

You will also want to install the following dependencies so that the code can run:

root # emerge jinja lxml

Configuration and Paths

In general, you should run merge-all-kits as a regular user, and this user needs to be a member of the portage group.

In the user's home directory, create a ~/.merge directory with the following contents:

/root/.merge

[sources]

flora = https://code.funtoo.org/bitbucket/scm/co/flora.git
kit-fixups = https://code.funtoo.org/bitbucket/scm/co/flora.git
gentoo-staging = https://code.funtoo.org/bitbucket/scm/auto/gentoo-staging.git

[branches]

flora = master
kit-fixups = master
meta-repo = master

By default, merge-all-kits will create a ~/repo_tmp directory where it will store all of its work. Inside ~/repo_tmp/source-trees, source git trees that will be used to generate meta-repo will be cloned. Inside ~/repo_tmp/dest-trees, git repositories will be created to write results into. The meta-repo will be stored at /~repo_temp/dest-trees/meta-repo, and in developer mode, the kits will be stored in meta-repo, at ~/repo_tmp/dest-trees/meta-repo/kits, so that meta-repo is configured 'ready to use' at it would appear at /var/git/meta-repo. When 'production' mode is specified via the --prod switch, the meta-repo will not have kits stacked inside it but instead the kits will be written directly into ~/repo_tmp/dest-trees.

A metadata cache will also be created and stored at ~/repo_tmp/metadata-cache, and your user must be a member of the portage group for merge-all-scripts to be able to properly generate the metadata cache.

Running Merge-All-Kits

To run merge-all-kits, use it as follows:

user $ path/to/merge-scripts/bin/merge-all-kits 1.4-release

The script will then run, and it will git clone flora, kit-fixups and gentoo-staging from the URIs in the ~/.merge file, and assemble them into a complete meta-repo. The meta-repo will be located at $HOME/repo_tmp/dest-trees/meta-repo.

To use the meta-repo for testing, you can add the following lines to /etc/ego.conf:

/etc/ego.conf

[global]
meta_repo_path = /home/user/repo_tmp/dest-trees/meta-repo

Then, using ego 2.8.0 or later, run the following command:

root # ego sync --in-place

This will ensure that the proper kit branches in your meta-repo are checked out and that all the repos.conf and profiles files in /etc/portage are configured correctly for your repository to be used. Note that no actual "git pull" will be performed -- this is intentional and a special feature of the --in-place option -- because your local git repositories have no remotes to pull from and contain all the information they need to be used.

You're now ready to use your meta-repo directly:

root # emerge foo

@@ Line 1: / Line 1: @@
-This page documents how to set up a local development environment that will allow full local testing of changes. This includes generating your own meta-repo and kits with your custom changes, as well as getting metro set up for unit tests.
+{{Subpages|Gitolite Setup}}
+{{Important|These pages are out of date. Please see the latest [[Funtoo:Metatools]] page for usage information.}}
 == Overview ==
-For our local development setup, we will be using [http://gitolite.com gitolite] on our development workstation. Gitolite will make things quite a bit easier by managing git repositories for us. Then we will use use a variety of repositories from Funtoo Linux to generate our own meta-repo and kits, which we can then test using [[Metro]].
+Funtoo Linux uses "merge scripts" to create its kits and update meta-repo. These scripts work by sourcing ebuilds from various overlays, and combining them using special algorithms to yield the kits you use. A meta-repo is also generated, which points to the specific kits generated that are designed to work together.
+Before starting, please read and understand the following pages:
+* [[Kit-fixups]]
+* [[Kit-fixups/FAQ]]
+== Different Approaches ==
-== Gitolite  ==
+{{c|merge-all-kits}} can be used in a variety of ways. If you are an individual developer, you may want to use {{c|merge-all-kits}} in ''developer mode'', which is its default mode. Developer mode makes it easy to generate a meta-repo and kits that you can test locally.
-=== Installation ===
+In developer mode, a {{c|meta-repo}} and all automatically-generated kit git repositories are created from scratch. These git repositories will have no remotes, so they will simply exist locally on disk, and they will not have any history shared with the Funtoo project. It you look at the commit history for the kits and meta-repo, you will see that they essentially have no history.
-To set up gitolite on your LAN, first choose a system that will be used to house your meta-repo and kits git repositories. This can be done locally, on the same system you will be using for testing (and even development), or you can set it up on a dedicated system. On this system, perform the following steps as root:
+Another way to use {{c|merge-all-kits}} is with {{c|gitolite}} as a remote, which is documented under the [[#Gitolite Setup|Gitolite Setup]] sub-page. Using this configuration, {{c|merge-all-kits}} will write all of its destination git repositories to gitolite. You can then configure other systems to {{c|ego sync}} from gitolite as a source. This can be good in a distributed development environment. This method can also be used to create a meta-repo and kits that ''diverge'' from Funtoo's kit but still connect to its history.
+Finally, the {{c|merge-all-kits}} script can be run in a production mode, which is very similar to using it with gitolite except that you may be pushing up your destination meta-repo and kits to a public location like GitHub or GitLab.
+When first starting out with {{c|merge-all-kits}}, you should definitely start with developer mode and see if that meets your needs first.
+== Getting The Code ==
+You can find the code that does this on code.funtoo.org, housed at [https://code.funtoo.org/bitbucket/projects/CORE/repos/merge-scripts/browse code.funtoo.org]. The script that does all the heavy-lifting is called {{c|merge-all-kits}}. Let's clone it from git, on the machine that will be generating new kits and meta-repo:
 {{console|body=
-# ##i##useradd -m repos
+$ ##i##git clone https://code.funtoo.org/bitbucket/scm/core/merge-scripts.git
 }}
-The {{c|repos}} user will be a dedicated user account on the system that will have gitolite enabled and will house our git repositories. Now, we are going to {{c|su}} to this new user and perform gitolite configuration:
+You will also want to install the following dependencies so that the code can run:
 {{console|body=
-$ ##i##git clone https://github.com/sitaramc/gitolite
+# ##i##emerge jinja lxml
-$ ##i##install -d ~/bin
 }}
-Now, as the {{c|repos}} user, add the following to the end of your {{c|~/.bashrc}} file:
+== Configuration and Paths ==
-{{file|body=
+In general, you should run {{c|merge-all-kits}} as a regular user, and this user needs to be a member of the {{c|portage}} group.
-export PATH=$HOME/bin:$PATH
+In the user's home directory, create a {{f|~/.merge}} directory with the following contents:
+{{file|name=/root/.merge|body=
+[sources]
+flora = https://code.funtoo.org/bitbucket/scm/co/flora.git
+kit-fixups = https://code.funtoo.org/bitbucket/scm/co/flora.git
+gentoo-staging = https://code.funtoo.org/bitbucket/scm/auto/gentoo-staging.git
+[branches]
+flora = master
+kit-fixups = master
+meta-repo = master
 }}
-What we're doing is setting up a {{c|bin}} directory where the {{c|gitolite}} command will be installed, which will be in your path, so that you can use it more easily. With this done, perform the following steps:
+By default, {{c|merge-all-kits}} will create a {{c|~/repo_tmp}} directory where it will store all of its work. Inside {{f|~/repo_tmp/source-trees}}, source git trees that will be used to generate meta-repo will be cloned. Inside {{f|~/repo_tmp/dest-trees}}, git repositories will be created to write results into. The meta-repo will be stored at {{c|/~repo_temp/dest-trees/meta-repo}}, and in developer mode, the kits will be stored in meta-repo, at {{c|~/repo_tmp/dest-trees/meta-repo/kits}}, so that meta-repo is configured 'ready to use' at it would appear at {{f|/var/git/meta-repo}}. When 'production' mode is specified via the {{c|--prod}} switch, the meta-repo will not have kits stacked inside it but instead the kits will be written directly into {{c|~/repo_tmp/dest-trees}}.
+A metadata cache will also be created and stored at {{c|~/repo_tmp/metadata-cache}}, and your user must be a member of the {{c|portage}} group for {{c|merge-all-scripts}} to be able to properly generate the metadata cache.
+== Running Merge-All-Kits ==
+To run {{c|merge-all-kits}}, use it as follows:
+{{console|body=
+$ ##i##path/to/merge-scripts/bin/merge-all-kits 1.4-release
+}}
+The script will then run, and it will git clone flora, kit-fixups and gentoo-staging from the URIs in the {{c|~/.merge}} file, and assemble them into a complete meta-repo. The meta-repo will be located at {{f|$HOME/repo_tmp/dest-trees/meta-repo}}.
+To use the {{c|meta-repo}} for testing, you can add the following lines to {{f|/etc/ego.conf}}:
+{{file|name=/etc/ego.conf|body=
+[global]
+meta_repo_path = /home/user/repo_tmp/dest-trees/meta-repo
+}}
+Then, using ego 2.8.0 or later, run the following command:
 {{console|body=
-$ ##i##source ~/.bashrc
+# ##i##ego sync --in-place
-$ ##i##gitolite/install -ln
+}}
+This will ensure that the proper kit branches in your meta-repo are checked out and that all the repos.conf and profiles files in {{c|/etc/portage}} are configured correctly for your repository to be used. Note that no actual "{{c|git pull}}" will be performed -- this is intentional and a special feature of the {{c|--in-place}} option -- because your local git repositories have no remotes to pull from and contain all the information they need to be used.
-Now, your {{c|repos}} account is almost ready to be used for hosting repositories. The way gitolite works is that it is going to basically take over ssh access to the account, so that when you connect via ssh with git, it will perform its own authentication. For this to work, you will need to enable your own "master key" to access gitolite. To do this, you'll want to decide from which account you'll want to administer gitolite itself. I prefer to use my "drobbins" account on my development workstation, so I will copy my ssh public key from {{c|~/.ssh/id_rsa.pub}} to {{c|/var/tmp/drobbins.pub}} on the gitolite system, and then perform the following steps to "prime" gitolite with this admin public key:
+You're now ready to use your meta-repo directly:
 {{console|body=
-$ ##i##gitolite setup -pk /var/tmp/drobbins.pub
+# ##i##emerge foo
 }}
-Gitolite will now be initialized to recognize the {{c|drobbins}} remote account as an administrator. This is important because we will be performing the rest of gitolite setup over ssh, using this account.
+[[Category:Official Documentation]]
+[[Category:Development]]