Difference between pages "Install/fr/Stage3" and "Forking An Ebuild"

< Install‎ | fr(Difference between pages)
(Quelle architecture?)
 
m
 
Line 1: Line 1:
<noinclude>
+
Often, a Funtoo developer needs to fork an upstream ebuild. This is necessary when we want to apply fixes to it. This page will explain the concepts of forking and how this works in the context of Funtoo.
{{InstallPart|installation de l'archive du Stage 3}}
+
</noinclude>
+
=== Installion du Stage 3 ===
+
  
La prochaine étape dans la mise en place de Funtoo Linux consiste à télécharger et à installer le Stage 3. Le Stage 3 fournit un système pré-compilé qui sert de point de départ à l'installation du système d'exploitation Funtoo Linux. Ouvrez une nouvelle fenêtre dans votre navigateur Web en allant à l'une de ces adresses: 
+
== Portage Tree Generation ==
{{MirrorList}}
+
  
Navigons dans les répertoires des miroirs afin de trouver l'archive qui convient à notre installation.
+
Funtoo Linux generates its Portage tree using a special script that essentially takes a Gentoo tree as its starting point, and then applies various modifications to it. The modifications involve adding packages from various overlays, including our [https://github.com/funtoo/funtoo-overlay Funtoo-overlay]. Some packages added are brand new, while other packages are our special forked versions that replace existing packages.  
  
==== Quelle version choisir? ====
+
In the vast majority of cases, when we fork a package, we take full responsibility for all ebuilds associated with that package, meaning that we have a full copy of the <tt>sys-foo/bar</tt> directory in one of our overlays.
  
'''En cas d'incertitude, sélectionnez <code>funtoo-current</code>.'''
+
If you're interested in seeing the actual script that does all these things, take a look at the following files:
  
Funtoo Linux offre différentes variantes de ses versions pré-compilées. En voici une liste ainsi que leur trait distinctif:
+
; http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/current-update.sh: cronned script that calls <tt>merge.py</tt>.
 +
;http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge.py: python script that does the heavy lifting of combining Gentoo tree with various overlays, including our flora and funtoo-overlay. When we want to change what overlays we merge, what packages we exclude as a matter of policy (such as stale packages in some overlays), we make changes to this file.
 +
; http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge_utils.py: python module that contains classes and methods that implement the merging functionality.
  
{{TableStart}}
+
== Forking an Ebuild ==
<tr><th class="info">Version</th><th class="info">Description</th></tr>
+
<tr><td><code>funtoo-current</code></td><td>La version la plus souvent choisie. Les mises à jour sont fréquentes et rapides. C'est le choix de prédilection de la plupart des utilisateurs d'un poste de travail.</td></tr>
+
<tr><td><code>funtoo-current-hardened</code></td><td>Similaire à <code>funtoo-current</code>, mais construite autour d'un toolchain plus rigoureux.</td></tr>
+
<tr><td><code>funtoo-stable</code></td><td>Version misant sur la fiabilité des paquets, les mises à jour sont moins fréquentes.</td></tr>
+
{{TableEnd}}
+
  
Consultez [[Funtoo_Linux#What_are_the_differences_between_.27stable.27.2C_.27current.27_and_.27experimental.27_.3F|le wiki sur les différences entre «stable», «current» et «experimental»]] pour en savoir plus.
+
In general, we fork ebuilds from Gentoo that we want to modify in some way. Before you fork an ebuild, it's important to understand that in general we fork entire packages, not just a single ebuild. This means that if you want to make some changes to <tt>sys-foo/bar</tt>, you are going to fork all <tt>sys-foo/bar</tt> ebuilds, and then Funtoo will be responsible for continuing to maintain these ebuilds until the package is unforked. Here are the steps we would use to fork <tt>sys-foo/bar</tt>:
 
+
==== Quelle architecture?  ====
+
 
+
'''En cas d'incertitude, optez pour <code>x86-64bit</code>, ou possiblement <code>pure64</code> pour l'installation sur un serveur.'''
+
 
+
Choix disponibles pour les ordinateurs compatibles PC:
+
 
+
{{TableStart}}
+
<tr><th class="info">Architecture</th><th class="info">Description</th></tr>
+
<tr><td><code>x86-64bit</code></td><td>Conçu pour les processeurs modernes 64-bit. Utilise un jeu d'instructions et un adressage 64-bit. Demeure compatible avec les applications 32-bit en fournissant le support «multilib».</td></tr>
+
<tr><td><code>pure64</code></td><td>Conception identique au précédent '''sans le support 32-bit'''.</td></tr>
+
<tr><td><code>x86-32bit</code></td><td>Pour les machines 32-bit telles Athlon XP, Pentium 4, ou Atom antérieur.</td></tr>
+
{{TableEnd}}
+
 
+
==== Moutures 64-bit ====
+
 
+
À l'intérieur de la section <code>/funtoo-current/x86-64bit/</code> sur l'un de nos miroirs, vous y verrez plusieurs sous-ensembles de Funtoo Linux 64-bit. Ce sont des Stage 3 spécialement conçus pour tourner un type de processeur particulier afin d'offir le meilleur rendement possible. Ces versions pré-compilées du système Funtoo Linux vous font profiter du jeu d'instructions spécifique à chaque processeur.
+
 
+
Si votre processeur est du type AMD, téléchargez un stage3 d'un des répertoires <code>generic_64</code>, <code>amd64-k8</code>, <code>amd64-k10</code>, <code>amd64-bulldozer</code>, <code>amd64-piledriver</code>, <code>amd64-steamroller</code> ou <code>amd64-jaguar</code>.  Voir [[Subarches#64-bit AMD Processors|notre liste de moutures 64-bit AMD]]
+
pour obtenir de l'aide sur le choix de la mouture qui vous convient le mieux.
+
 
+
Si votre processeur est du type Intel, téléchargez un stage3 d'un des répertoires <code>generic_64</code>, <code>atom_64</code>, <code>core2_64</code> ou <code>corei7</code>. La mouture <code>corei7</code> convient parfaitement aux processeurs Intel dernier cri, incluant Core i3 et Core i5 ainsi  que plusieurs Xeons. Voir [[Subarches#64-bit Intel Processors|notre liste de moutures Intel 64-bit]] pour vous aider à faire un choix judicieux.
+
 
+
Pour les processeurs 32-bit, téléchargez un stage3 d'un des répertoires <code>generic_32</code>, <code>i686</code>, <code>core2_32</code>, <code>atom_32</code> ou <code>athlon-xp</code>.
+
 
+
==== Réglage de la date ====
+
 
+
{{Important|Il y a des risques que Portage ne télécharge pas correctement l'archive du fichier d'installation quand la date du système s'éloigne trop de la date courante, voire des mois ou des années. Cela en raison du fait que certains sources sont téléchargés via HTTPS qui utilise des certificats SSL. Ces certificats fournissent une date d'activation et une date d'expiration. Cependant, si l'écart n'est pas trop prononcé, vous pouvez probablement ignorer cette étape pour l'instant.}}
+
 
+
Vérifions maintenant si l'heure et la date sont conformes aux valeurs UTC. Utilisez la commande <code>date</code> pour vérifier le tout:
+
  
 +
# Find <tt>sys-foo/bar</tt> in you regular Portage tree. Make sure you have run <tt>emerge --sync</tt> recently to ensure it is up-to-date. If you want to fork from very recent changes that are not yet in our tree, you may need to grab the most recent Gentoo Portage tree to serve as your source for <tt>sys-foo/bar</tt> (this typically isn't necessary.)
 
<console>
 
<console>
# ##i##date
+
# alias to recursively grab latest from Gentoo Portage tree WITHOUT history
lundi 22 décembre 2014, 09:06:06 (UTC-0500)
+
# usage: getgen gentoo-x86/dev-db/mongodb
 +
alias getgen="cvs -d :pserver:anonymous@anoncvs.gentoo.org:/var/cvsroot export -D$(date '+%Y-%m-%d')"
 
</console>
 
</console>
 +
# Copy the <tt>sys-foo/bar</tt> directory in its entirety to <tt>funtoo-overlay/sys-foo/bar</tt>.
 +
# Make any necessary modifications to <tt>funtoo-overlay/sys-foo/bar</tt>.
 +
# Perform some funtoo-ification steps prior to commit.
 +
# Add and commit the changes to funtoo-overlay.
 +
# Push changes to funtoo-overlay.
  
Si vous devez corriger les date et heure, utilisez cette forme de la commande date: <code>date MMDDhhmmYYYY</code>, en gardant à l'esprit que <code>hhmm</code> représente le format 24 heures.
+
At this point, the forked <tt>sys-foo/bar</tt> package will be part of funtoo-overlay. The next time our unified Portage tree is generated by <tt>merge.py</tt> (the one that users have in their <tt>/usr/portage</tt> and is updated via <tt>emerge --sync</tt>), your forked ebuild will be used in place of the Gentoo ebuild. Why is this? It is because our <tt>merge.py</tt> script has been defined with a policy that any ebuilds in funtoo-overlay will replace any existing Gentoo ebuilds if they exist. The mechanism of replacement is that our <tt>sys-foo/bar</tt> directory will be used in place of Gentoo's <tt>sys-foo/bar</tt> directory. So this is how the forking process works.
  
Une fois le réglage complété, cela constitue une très bonne idée que d'initialiser l'horloge matérielle avec l'heure UTC:
+
== Funtoo-ification ==
  
<console>
+
When we fork a package from Gentoo, we perform the following tweaks to the package directory before committing:
# ##i##hwclock --systohc
+
</console>
+
  
==== Téléchargement du Stage3 ====
+
# Removal of <tt>ChangeLog</tt>.
 +
# Run <tt>ebuild foo-1.0.ebuild digest</tt> before committing. This will cause the <tt>Manifest</tt> file to be regenerated. Gentoo has a lot more entries in this file than we do, since we use mini-Manfiests that only include DIST listings (for distfiles only.) We want to commit our mini-Manifest (still called <tt>Manifest</tt>, just with less entries in it) rather than the one that came from Gentoo.
 +
# Edit the top of each ebuild, and remove all <tt>Copyright</tt> and <tt>$Header:</tt> lines at the top of the file. We have a LICENSE.txt and COPYRIGHT.txt file in the root of our Portage tree, which is easier to maintain than keeping all the years up-to-date in each ebuild. Also, the <tt>$Header:</tt> line is there for the CVS version control system in Gentoo which Funtoo does not use. ''The only comment that should remain on the top of the ebuild is the one stating that it is distributed under the GPLv2.''.
  
Une fois à la racine du système Funtoo Linux, utilisez l'utilitaire <code>wget</code> pour télécharger l'archive Stage 3 que vous avez choisie pour votre système Funtoo Linux. Le fichier sera enregistré ainsi dans le dossier <code>/mnt/funtoo</code>:
+
<console>
 +
# If you find yourself doing this often, place this function in your .bashrc, .zshrc, etc
 +
funtooize() {
 +
    if [ -z "$1" ]; then
 +
        search_path='.'
 +
    else
 +
        search_path=$1
 +
    fi
  
<console># ##i##cd /mnt/funtoo
+
    find $search_path -type f -exec sed -i -e '/^# Copyright\|^# \$Header/d' {} +
# ##i##wget http://build.funtoo.org/funtoo-current/x86-64bit/generic_64/stage3-latest.tar.xz
+
    find $search_path -type f -name "ChangeLog*" -delete
 +
    find $search_path -type f -name '*.ebuild' -exec ebuild {} manifest \;
 +
}
 
</console>
 
</console>
  
Souvenez-vous qu'un système 64-bit exécute autant les jeux d'instructions 64-bit que 32-bit. Par contre un système 32-bit n'exécute que les jeux d'instructions 32-bit. Assurez-vous également de choisir un Stage 3 conçu spécifiquement pour votre type de processeur. Si vous avez quelque incertitude, misez sur un choix sûr en téléchargeant un Stage 3 <code>generic_64</code> ou <code>generic_32</code> selon le cas.
+
Here are a few additional changes that you are allowed to make to any forked ebuilds:
  
Extrayez le contenu du fichier d'archive avec la commande suivante:
+
# Line length greater than 80 characters. Gentoo enforces an 80-character line length limit. We don't.
<console>
+
# <tt>KEYWORDS</tt> of <tt>*</tt> and <tt>~*</tt>. Gentoo does not allow these shortcuts. We do. They allow you to say "all arches" and "all unstable arches" in a concise way. Gentoo doesn't allow these shortcuts because it's Gentoo's policy to have each arch team manually approve each package. We do not have this policy so we can use the shortcuts.
# ##i##tar xpf stage3-latest.tar.xz
+
# Use of <tt>4-python</tt> EAPI. We allow the use of this EAPI for enhanced python functionality.
</console>
+
  
{{Important|Il est très important d'utiliser l'option "<code>'''p'''</code>". Elle instruit <code>tar</code> de ''préserver'' les permissions et les droits de propriété qui existent dans l'archive. Autrement les permissions d'accès aux fichiers seront incorrectes.}}
+
[[Category:Development]]

Latest revision as of 05:25, May 30, 2015

Often, a Funtoo developer needs to fork an upstream ebuild. This is necessary when we want to apply fixes to it. This page will explain the concepts of forking and how this works in the context of Funtoo.

Portage Tree Generation

Funtoo Linux generates its Portage tree using a special script that essentially takes a Gentoo tree as its starting point, and then applies various modifications to it. The modifications involve adding packages from various overlays, including our Funtoo-overlay. Some packages added are brand new, while other packages are our special forked versions that replace existing packages.

In the vast majority of cases, when we fork a package, we take full responsibility for all ebuilds associated with that package, meaning that we have a full copy of the sys-foo/bar directory in one of our overlays.

If you're interested in seeing the actual script that does all these things, take a look at the following files:

http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/current-update.sh
cronned script that calls merge.py.
http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge.py
python script that does the heavy lifting of combining Gentoo tree with various overlays, including our flora and funtoo-overlay. When we want to change what overlays we merge, what packages we exclude as a matter of policy (such as stale packages in some overlays), we make changes to this file.
http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge_utils.py
python module that contains classes and methods that implement the merging functionality.

Forking an Ebuild

In general, we fork ebuilds from Gentoo that we want to modify in some way. Before you fork an ebuild, it's important to understand that in general we fork entire packages, not just a single ebuild. This means that if you want to make some changes to sys-foo/bar, you are going to fork all sys-foo/bar ebuilds, and then Funtoo will be responsible for continuing to maintain these ebuilds until the package is unforked. Here are the steps we would use to fork sys-foo/bar:

  1. Find sys-foo/bar in you regular Portage tree. Make sure you have run emerge --sync recently to ensure it is up-to-date. If you want to fork from very recent changes that are not yet in our tree, you may need to grab the most recent Gentoo Portage tree to serve as your source for sys-foo/bar (this typically isn't necessary.)
# alias to recursively grab latest from Gentoo Portage tree WITHOUT history
# usage: getgen gentoo-x86/dev-db/mongodb
alias getgen="cvs -d :pserver:anonymous@anoncvs.gentoo.org:/var/cvsroot export -D$(date '+%Y-%m-%d')"
  1. Copy the sys-foo/bar directory in its entirety to funtoo-overlay/sys-foo/bar.
  2. Make any necessary modifications to funtoo-overlay/sys-foo/bar.
  3. Perform some funtoo-ification steps prior to commit.
  4. Add and commit the changes to funtoo-overlay.
  5. Push changes to funtoo-overlay.

At this point, the forked sys-foo/bar package will be part of funtoo-overlay. The next time our unified Portage tree is generated by merge.py (the one that users have in their /usr/portage and is updated via emerge --sync), your forked ebuild will be used in place of the Gentoo ebuild. Why is this? It is because our merge.py script has been defined with a policy that any ebuilds in funtoo-overlay will replace any existing Gentoo ebuilds if they exist. The mechanism of replacement is that our sys-foo/bar directory will be used in place of Gentoo's sys-foo/bar directory. So this is how the forking process works.

Funtoo-ification

When we fork a package from Gentoo, we perform the following tweaks to the package directory before committing:

  1. Removal of ChangeLog.
  2. Run ebuild foo-1.0.ebuild digest before committing. This will cause the Manifest file to be regenerated. Gentoo has a lot more entries in this file than we do, since we use mini-Manfiests that only include DIST listings (for distfiles only.) We want to commit our mini-Manifest (still called Manifest, just with less entries in it) rather than the one that came from Gentoo.
  3. Edit the top of each ebuild, and remove all Copyright and $Header: lines at the top of the file. We have a LICENSE.txt and COPYRIGHT.txt file in the root of our Portage tree, which is easier to maintain than keeping all the years up-to-date in each ebuild. Also, the $Header: line is there for the CVS version control system in Gentoo which Funtoo does not use. The only comment that should remain on the top of the ebuild is the one stating that it is distributed under the GPLv2..
# If you find yourself doing this often, place this function in your .bashrc, .zshrc, etc
funtooize() {
    if [ -z "$1" ]; then
        search_path='.'
    else
        search_path=$1
    fi

    find $search_path -type f -exec sed -i -e '/^# Copyright\|^# \$Header/d' {} +
    find $search_path -type f -name "ChangeLog*" -delete
    find $search_path -type f -name '*.ebuild' -exec ebuild {} manifest \;
}

Here are a few additional changes that you are allowed to make to any forked ebuilds:

  1. Line length greater than 80 characters. Gentoo enforces an 80-character line length limit. We don't.
  2. KEYWORDS of * and ~*. Gentoo does not allow these shortcuts. We do. They allow you to say "all arches" and "all unstable arches" in a concise way. Gentoo doesn't allow these shortcuts because it's Gentoo's policy to have each arch team manually approve each package. We do not have this policy so we can use the shortcuts.
  3. Use of 4-python EAPI. We allow the use of this EAPI for enhanced python functionality.