Difference between pages "Overlay:Flora" and "Localpatch (Tutorial)"

From Funtoo
(Difference between pages)
Jump to: navigation, search
(Flora Main Ruleset: comments.gmane.org/gmane.linux.gentoo.funtoo.devel/5028)
 
 
Line 1: Line 1:
__TOC__
+
== Introduction ==
 +
'''''Localpatch''''' (known in gentoo as '''''epatch_user''''') is a feature that lets you, the user, add patches to official ebuilds without having to maintain the ebuild in question in a local overlay, thus avoiding the maintenance overhead associated with keeping your local overlay in sync with revision and version bumps.
  
== What is flora ==
+
Ebuilds can use this feature by calling <code>epatch_user</code> in their <code>src_prepare ()</code> function (preferrably after their own patching).
  
flora is Funtoo's overlay for user-contributed ebuilds. Why is it called flora? Let's have a look at the definition of flora.
+
For future reference, I'm going to document here how I used <code>epatch_user</code> to add a patch to <code>sys-kernel/gentoo-sources</code>.
  
# A group of plants, especially the indigenous plants of a particular time or region.
+
=== Motivation ===
# A book or treatise describing the plants of a particular region or time.
+
# Bacterial organisms, like those that naturally inhabit a bodily organ or appendage, e.g. intestinal flora.
+
  
We hope that only the first two definitions will be taken into account when submitting ebuilds to flora. We try to uphold Funtoo's high standards in ebuilds submitted to flora. It would be unrealistic to expect users not to make mistakes, however. As we are all humans (hopefully) and all humans make mistakes, just give us a call if you make a mistake so that we can take care of it as soon as possible. :)
+
I use the Open Source AMD/ATi Radeon KMS drivers with my funtoo boxes and was seeing random kernel OOPSes with Xorg and 3D applications (the flurry 3D screensaver and games mainly).
  
The following image gives you an overview on how the Funtoo Portage tree and especially flora is structured:
+
I asked in #radeon on the FreeNode IRC network and Dave Airlie was kind enough to link me to a commit that was merged in linux-3.0. However, as I am using 2.6.39-r3 w/aufs2 (which was not available for 3.0 at the time of this writing), I decided to apply the patch myself.
  
[[File:Funtoo-overlay-structure2.png]]
+
'''UPDATE:''' The patch has landed upstream in [http://www.kernel.org/pub/linux/kernel/v2.6/ChangeLog-2.6.39.4 the vanilla linux-2.6.39.4 kernel].
  
== How to... ==
+
=== How it works ===
 +
{{fancyimportant|localpatch feature removed form recent portage, available in foobashrc.}}
 +
<console># emerge foobashrc</console>
 +
Reviewing the <code>/usr/portdir/sys-kernel/gentoo-sources</code> ebuilds reveals that they inherit the <code>kernel-2.eclass</code>. Looking at <code>/usr/portage/eclass/kernel-2.eclass</code>, I noticed that it included a reference to <code>epatch_user</code> in the function <code>kernel-2_src_unpack()</code>.  
  
=== ... work with flora ===
+
<code> /usr/portage/eclass # grep epatch_user * </code> revealed that the <code>epatch_user</code> bash function is currently defined as follows in <code>/usr/portage/eclass/eutils.eclass</code>:
 
+
==== Core Team ====
+
Core Members can push directly to flora as they already have the appropriate rights. Just do:
+
  
 
<pre>
 
<pre>
cd <your dir for overlays>
+
epatch_user() {
git clone repos@git.funtoo.org:flora.git
+
        [[ $# -ne 0 ]] && die "epatch_user takes no options"
</pre>
+
  
You will now be able to push/pull to and from flora. For development in git I would advise all members to use git-flow, since it ensures a clean working copy without any development stuff left over and pushed to the overlay. See the [[Git Guide]] and [[flora#... git-flow]] for more information on git-flow.
+
        # don't clobber any EPATCH vars that the parent might want
 
+
        local EPATCH_SOURCE check base=${PORTAGE_CONFIGROOT%/}/etc/portage/patches
===== merging in Upstream User Contributions =====
+
        for check in {${CATEGORY}/${PF},${CATEGORY}/${P},${CATEGORY}/${PN}}; do
The workflow is splitted into some easy steps just follow the next instructions:
+
                EPATCH_SOURCE=${base}/${CTARGET}/${check}
 
+
                [[ -r ${EPATCH_SOURCE} ]] || EPATCH_SOURCE=${base}/${CHOST}/${check}
* Add the forks to our flora clone:<br>The general syntax to add a remote clone for flora is:<pre>git remote add <username> git://github.com/<username>/flora.git</pre>so far the following forks are known and can be added if you copy the context:<pre>git remote add timoahummel git://github.com/timoahummel/flora.git&#10;git remote add leprosys git://github.com/leprosys/flora.git&#10;git remote add init6 git://github.com/init6/flora.git&#10;git remote add tarsius git://github.com/tarsius/flora.git&#10;git remote add tobert git://github.com/tobert/flora.git&#10;git remote add stasikos git://github.com/stasikos/flora.git&#10;git remote add trq git://github.com/trq/flora.git&#10;git remote add keenblade git://github.com/keenblade/flora.git&#10;git remote add edwtjo git://github.com/edwtjo/flora.git&#10;git remote add strowi git://github.com/strowi/flora.git&#10;git remote add ipalaus git://github.com/ipalaus/flora.git&#10;git remote add N4th4 git://github.com/N4th4/flora.git&#10;git remote add jmarcet git://github.com/jmarcet/flora.git&#10;git remote add drzayer git://github.com/drzayer/flora.git&#10;git remote add cvantassle git://github.com/cvantassle/flora.git&#10;git remote add wishstudio git://github.com/wishstudio/flora.git&#10;git remote add Saint0fCloud git://github.com/Saint0fCloud/flora.git&#10;git remote add The-Judge git://github.com/The-Judge/flora.git&#10;git remote add kpacheco git://github.com/kpacheco/flora.git&#10;git remote add modethirteen git://github.com/modethirteen/flora.git&#10;git remote add sandikata git://github.com/sandikata/flora.git&#10;git remote add synchris git://github.com/synchris/flora.git&#10;git remote add vadmeste git://github.com/vadmeste/flora.git&#10;git remote add rh1 git://github.com/rh1/flora.git&#10;git remote add just1602 git://github.com/just1602/flora.git&#10;git remote add mozgwar git://github.com/mozgwar/flora.git&#10;git remote add rem7 git://github.com/rem7/flora.git&#10;git remote add akiress git://github.com/akiress/flora.git&#10;git remote add ereslibre git://github.com/ereslibre/flora.git&#10;git remote add dangergrrl git://github.com/dangergrrl/flora.git&#10;git remote add crazyfraggle git://github.com/crazyfraggle/flora.git&#10;git remote add nakaran git://github.com/nakaran/flora.git&#10;git remote add PaddyMac git://github.com/PaddyMac/flora.git&#10;git remote add deferi git://github.com/deferi/flora.git&#10;git remote add ozon git://github.com/ozon/flora.git&#10;git remote add mmtk git://github.com/mmtk/flora.git&#10;git remote add alexjp git://github.com/alexjp/flora.git&#10;git remote add funkycode git://github.com/funkycode/flora.git&#10;git remote add limansky git://github.com/limansky/flora.git&#10;git remote add fearedbliss git://github.com/fearedbliss/flora.git&#10;git remote add lebel git://github.com/lebel/flora.git&#10;git remote add SaThero git://github.com/SaThero/flora.git&#10;git remote add soulthreads git://github.com/soulthreads/flora.git</pre>
+
                [[ -r ${EPATCH_SOURCE} ]] || EPATCH_SOURCE=${base}/${check}
 
+
                if [[ -d ${EPATCH_SOURCE} ]] ; then
* Pull the changed/added files into your copy of flora, where username is the repo of the user that wants to add stuff to flora<pre>git fetch username</pre>
+
                        EPATCH_SOURCE=${EPATCH_SOURCE} \
 
+
                        EPATCH_SUFFIX="patch" \
* Merge the branches into flora<pre>git merge username/master</pre>
+
                        EPATCH_FORCE="yes" \
 
+
                        EPATCH_MULTI_MSG="Applying user patches from ${EPATCH_SOURCE} ..." \
* Push to username's git<pre>git push</pre>
+
                        epatch
 
+
                        return 0
* Close the pull request on github, and no worry it will show you problems if you view the code again, as we already included the patch of the user :)
+
                fi
 
+
        done
If you as a coreteam member do not have rights to edit issues on flora at github anymore please give [[User:drobbins]] or [[User:golodhrim]] a ping, so that you can close the request when you merged it... :)
+
        return 1
 
+
}
==== User Contribution ====
+
 
+
For normal users that like to contribute it is a bit more complicated but we will walk you through it.
+
 
+
First you need to have a GitHub account; you can follow our [[Git Guide]] to get one.
+
 
+
Visit [https://github.com/funtoo/flora https://github.com/funtoo/flora] and use the fork button on the top to fork the repository to your own account so that you can push to it later.
+
 
+
Now you should create a directory to contain the local copy of the overlay repository on your local disk. We'll use <tt>/root/.git</tt> for this example, but you can use whatever you want to.
+
 
+
<pre>
+
cd /root/.git
+
git clone git@github.com:{your github username}/flora.git
+
 
</pre>
 
</pre>
  
Now you are nearly ready to contribute. Since you now have flora cloned to /root/.git/flora, you need to go in and make a few changes so that you can begin your work.
+
From the [http://devmanual.gentoo.org/ebuild-writing/variables/index.html Gentoo Development Guide] we can deduce that the following paths are valid (using <code>sys-kernel/gentoo-sources-2.6.39-r3</code> as an example):
 
+
=== ... work with git-flow ===
+
 
+
Since this is a very helpful tool, you should emerge it and git-flow-completion, as they will support you in your work.
+
  
 
<pre>
 
<pre>
# emerge -avt gitflow git-flow-completion
+
/etc/portage/patches/sys-kernel/gentoo-sources-2.6.39-r3 # ${CATEGORY}/${PF}
 +
/etc/portage/patches/sys-kernel/gentoo-sources-2.6.39    # ${CATEGORY}/${P}
 +
/etc/portage/patches/sys-kernel/gentoo-sources          # ${CATEGORY}/${PN}
 
</pre>
 
</pre>
  
Once it is installed, move to your flora directory and initialize git-flow. In the following example we suppose that you used /root/.git/flora for your overlay directory.
+
For my particular use case, I added the radeon kms patch titled [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=498c555f56a02ec1059bc150cde84411ba0ac010 drm/radeon: fix oops in ttm reserve when pageflipping (v2)]:
  
<pre>
+
<code>/etc/portage/patches/sys-kernel/gentoo-sources-2.6.39-r3/linux-2.6.git-498c555f56a02ec1059bc150cde84411ba0ac010.patch</code>
# cd /root/.git/flora
+
# git-flow init
+
No branches exist yet. Base branches must be created now.
+
Branch name for production releases: [master] <ENTER>
+
Branch name for "next release" development: [develop] <ENTER>
+
  
How to name your supporting branch prefixes?
+
== Testing it ==
Feature branches? [feature/] <ENTER>
+
Release branches? [release/] <ENTER>
+
Hotfix branches? [hotfix/] <ENTER>
+
Support branches? [support/] <ENTER>
+
Version tag prefix? [] <ENTER>
+
#
+
</pre>
+
  
Your main work will now be done in the "develop" branch. When you want to add a feature or a hotfix:
+
Let's test that it works as expected:
  
 
<pre>
 
<pre>
# git-flow feature start <name of feature>
+
# cd /usr/portage/sys-kernel/gentoo-sources/
</pre>
+
# ebuild gentoo-sources-2.6.39-r3.ebuild clean
 
+
# ebuild gentoo-sources-2.6.39-r3.ebuild prepare
You may switch at any time to the development branch again with:
+
* linux-2.6.39.tar.bz2 RMD160 SHA1 SHA256 size ;-) ...                                      [ ok ]
 
+
* genpatches-2.6.39-5.base.tar.bz2 RMD160 SHA1 SHA256 size ;-) ...                          [ ok ]
<pre>
+
* genpatches-2.6.39-5.extras.tar.bz2 RMD160 SHA1 SHA256 size ;-) ...                        [ ok ]
# git checkout develop
+
* checking ebuild checksums ;-) ...                                                        [ ok ]
</pre>
+
* checking auxfile checksums ;-) ...                                                        [ ok ]
 
+
* checking miscfile checksums ;-) ...                                                      [ ok ]
To see which features you currently have open:
+
* checking linux-2.6.39.tar.bz2 ;-) ...                                                    [ ok ]
 
+
* checking genpatches-2.6.39-5.base.tar.bz2 ;-) ...                                        [ ok ]
<pre>
+
* checking genpatches-2.6.39-5.extras.tar.bz2 ;-) ...                                      [ ok ]
# git-flow feature [list]
+
* Package:    sys-kernel/gentoo-sources-2.6.39-r3
</pre>
+
* Repository: gentoo
 
+
* Maintainer: kernel@gentoo.org
Once your feature is finished:
+
* USE:        amd64 elibc_glibc kernel_linux multilib userland_GNU
 
+
* FEATURES:  fakeroot installsources preserve-libs sandbox splitdebug userpriv usersandbox
<pre>
+
>>> Preparing to unpack ...
# git-flow feature finish <name>
+
>>> Unpacking source...
</pre>
+
>>> Unpacking linux-2.6.39.tar.bz2 to /home/portage/tmp/portage/sys-kernel/gentoo-sources-2.6.39-r3/work
 
+
>>> Unpacking genpatches-2.6.39-5.base.tar.bz2 to /home/portage/tmp/portage/sys-kernel/gentoo-sources-2.6.39-r3/work/patches
For a hotfix to any of your ebuilds:
+
>>> Unpacking genpatches-2.6.39-5.extras.tar.bz2 to /home/portage/tmp/portage/sys-kernel/gentoo-sources-2.6.39-r3/work/patches
 
+
* Applying 1000_linux-2.6.39.1.patch (-p0+) ...                                            [ ok ]
<pre>
+
* Applying 1001_linux-2.6.39.2.patch (-p0+) ...                                            [ ok ]
# git-flow hotfix start <version>
+
* Applying 1002_linux-2.6.39.3.patch (-p0+) ...                                            [ ok ]
</pre>
+
* Applying 2900_disable-wunused-but-set-var-gcc-4-6-0.patch (-p0+) ...                      [ ok ]
 
+
* Applying 2910_gnu-make-3.80-compat-fix.patch (-p0+) ...                                  [ ok ]
After applying the appropriate fixes:
+
* Applying 4200_fbcondecor-0.9.6.patch (-p0+) ...                                          [ ok ]
 
+
* Applying user patches from /etc/portage/patches/sys-kernel/gentoo-sources-2.6.39-r3 ...
<pre>
+
*  linux-2.6.git-498c555f56a02ec1059bc150cde84411ba0ac010.patch ...                        [ ok ]
# git-flow hotfix finish <version>
+
* Done with patching
</pre>
+
>>> Source unpacked in /home/portage/tmp/portage/sys-kernel/gentoo-sources-2.6.39-r3/work
 
+
>>> Preparing source in /home/portage/tmp/portage/sys-kernel/gentoo-sources-2.6.39-r3/work/linux-2.6.39-gentoo-r3 ...
Now that you know how to add features, hotfixes, and support work, you still need to know how to make a release.
+
>>> Source prepared.
 
+
<pre>
+
# git add <directory or file>
+
# git commit
+
Your editor will appear if you followed our Git Guide)
+
# git-flow release start <name>
+
Switched to a new branch 'release/<name>'
+
 
+
Summary of actions
+
- A new branch 'release/<name>' was created, based on 'develop'
+
- You are now on branch 'release/<name>'
+
 
+
Follow-up actions:
+
- Bump the version number now!
+
- Start committing last-minute fixes in preparing your release
+
- When done, run:
+
 
+
    git-flow release finish <name>
+
 
#
 
#
(Do what is noted above if needed)
 
# git-flow release finish <name>
 
Switched to branch 'master'
 
Merge made by recursive
 
X files changed, X insertions(+), X deletions(-)
 
create mode aaaaaa README
 
Deleted branch release/<name> (was <githash>)
 
 
(Your editor will come up so you can write a release note, save and close your editor afterwards.)
 
 
Summary of actions:
 
- Latest objects have been fetched from 'origin'
 
- Release branch has been merged into 'master'
 
- The release was tagged '<name>'
 
- Release branch has been back-merged into 'develop'
 
- Release branch 'release/<name>' has been deleted
 
 
#
 
(As you are now on the master branch, you can do the push and go back to the development branch.)
 
# git push
 
# git checkout develop
 
 
</pre>
 
</pre>
  
You should now have an overview of how we like to work in flora and keep its contents clean.
+
Et voilà -- a cleanly patched kernel.
 
+
This workflow model will then look like the following graph:
+
 
+
[[File:funtoo-struct-overlay-gitflow.png]]
+
 
+
=== ... keeping in sync with upstream ===
+
 
+
To keep in sync with upstream Funtoo flora just do the following steps.
+
 
+
First you need to add a new remote to your configuration, it is really easy and you should sync with upstream from time to time again.
+
 
+
So change to your clone of flora and execute the following commands:
+
 
+
<pre>
+
$ cd <path/to/flora/>flora
+
$ git remote add upstream git://github.com/funtoo/flora.git
+
</pre>
+
 
+
That's all, was a one timer.
+
From now we just need to keep in sync from time to time.
+
 
+
That is nearly as easy as the above:
+
 
+
<pre>
+
$ git fetch upstream
+
$ git merge upstream/master
+
</pre>
+
 
+
Now you are in sync with our upstream version of flora again.
+
Please do the last two steps regulary (maybe cron?).
+
 
+
== Flora Main Ruleset ==
+
 
+
As we want to keep up the high standard for ebuilds in flora like we provide in our portage trees (portage, funtoo-overlay) you should write your ebuilds clean and with the needed care.
+
 
+
Please respect our following rules:
+
 
+
* Test your ebuilds before pushing them to us.
+
* generate the needed "Manifest" files for your ebuilds. If they are missing we will reject them and drop your request. The only exception to the previous rule is that your ebuild is a git-based ebuild, as the manifest would then be empty and so not pushed. All other ebuilds need to have one.
+
* If you write your ebuild please make sure you add the following to your header:
+
  <pre>
+
    # Distributed under the terms of the GNU General Public License v2
+
  </pre>
+
* push one ebuild-category at one request! if something is missing we won't need to reject all your requests.
+
* Add a metadata.xml fill too all your ebuilds, so we know who is responsible for the ebuild. the Syntax is like that:
+
  <pre>
+
    <?xml version="1.0" encoding="UTF-8"?>                                                         
+
    <!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+
    <pkgmetadata>
+
        <herd>no-herd</herd>
+
        <maintainer>
+
            <email>email1@domain.tld</email>
+
            <name>Name of Maintainer 1</name>
+
        </maintainer>
+
        <maintainer>
+
            <email>email2@domain.tld</email>
+
            <name>Name of Maintainer 2</name>
+
        </maintainer>
+
        <use>
+
            <flag name='USE-Variable-1'>Description of Variable 1</flag>
+
            <flag name='...'>...</flag>
+
            <flag name='USE-Variable-n'>Description of Variable n</flag>
+
        </use>
+
        <upstream>
+
            <changelog>URL to Online Changelogs</changelog>
+
        </upstream>
+
    </pkgmetadata>
+
  </pre>
+
* Add yourself as a Maintainer for your ebuild to our Page so we users have an option to easily find who is responsible and give him a ping in IRC for errors.
+
 
+
Thanks for following the rules. We appreciate your participation. Please don't forget to add yourself to the [[ebuild Maintainer list|Maintainer List]], as it would save us some work too.
+
 
+
== Notify us about your commit ==
+
 
+
To make us aware that you committed something go to your GitHub account and send us a Pull Request so we can perform a quick review of your push and include it into the main tree. If you started working on an ebuild, please let us know that you are responsible for it by adding your data to [[ebuild Maintainer list]].
+
 
+
== A day's work with flora ==
+
 
+
At this point you should already have a working copy of flora and you should be knowledgeable about git-flow. You should now be ready to start your daily work with flora.
+
 
+
First you need to make sure your copy of flora is synchronized with the main flora repository.
+
 
+
{{shell
+
| Desc = Add an upstream branch to your working copy
+
| Input = $ git remote add upstream git://github.com/funtoo/flora.git
+
| Desc = Keeping flora up-to-date with upstream
+
| Input = $ git fetch upstream<br>
+
remote: Counting objects: 54, done.<br>
+
remote: Compressing objects: 100% (42/42), done.<br>
+
remote: Total 48 (delta 2), reused 47 (delta 1)<br>
+
Unpacking objects: 100% (48/48), done.<br>
+
From git://github.com/funtoo/flora<br>
+
&nbsp;  2c52d0d..af665e9  master    -> upstream/master<br>
+
$ git merge upstream/master<br>
+
Updating 2c52d0d..af665e9<br>
+
Fast-forward
+
<table style="border:none; background-color:#D8CCFF; color:#000000">
+
<tr><td>&nbsp; dev-java/asm/Manifest</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>2</td><td> <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; dev-java/asm/asm-3.3.1.ebuild</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>35</td><td>  <font color=#00a300>++</font></td></tr>
+
<tr><td>&nbsp; dev-java/lucene-analyzers/Manifest</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>3</td><td>  <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; dev-java/lucene-analyzers/files/manifest</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>10</td><td>  <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; .../lucene-analyzers/lucene-analyzers-2.9.4.ebuild</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>28</td><td>  <font color=#00a300>++</font></td></tr>
+
<tr><td>&nbsp; dev-java/sat4j-core/Manifest</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>3</td><td>  <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; dev-java/sat4j-core/sat4j-core-2.3.0.ebuild</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>59</td><td>  <font color=#00a300>+++</font></td></tr>
+
<tr><td>&nbsp; dev-java/sat4j-pseudo/Manifest</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>3</td><td>  <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; dev-java/sat4j-pseudo/sat4j-pseudo-2.3.0.ebuild</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>69</td><td>  <font color=#00a300>++++</font></td></tr>
+
<tr><td>&nbsp; dev-java/swt/Manifest</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>6</td><td>  <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; .../swt/files/as-needed-and-flag-fixes-3.6.patch</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>243</td><td>  <font color=#00a300>++++++++++++</font></td></tr>
+
<tr><td>&nbsp; dev-java/swt/files/build.xml</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>17</td><td>  <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; dev-java/swt/files/swt-3.7-manifest</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>17</td><td>  <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; dev-java/swt/swt-3.7.ebuild</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>205</td><td>  <font color=#00a300>++++++++++</font></td></tr>
+
<tr><td>&nbsp; dev-util/eclipse-sdk/Manifest</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>8</td><td>  <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; dev-util/eclipse-sdk/eclipse-sdk-3.7.0.ebuild</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>399</td><td>  <font color=#00a300>++++++++++++++++++++</font></td></tr>
+
<tr><td>&nbsp; dev-util/eclipse-sdk/files/3.7/eclipse-3.7</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>46</td><td>  <font color=#00a300>+++</font></td></tr>
+
<tr><td>&nbsp; dev-util/eclipse-sdk/files/3.7/eclipserc-3.7</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>20</td><td>  <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; dev-util/eclipse-sdk/files/3.7/gtk_makefile.patch</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>36</td><td>  <font color=#00a300>++</font></td></tr>
+
<tr><td>&nbsp; .../eclipse-sdk/files/3.7/hamcrest-junit-lib.patch</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>11</td><td>  <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; dev-util/eclipse-sdk/files/3.7/iterators.patch</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>70</td><td>  <font color=#00a300>++++</font></td></tr>
+
<tr><td>&nbsp; profiles/docs/README.eclipse-sdk</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>41</td><td>  <font color=#00a300>++</font></td></tr>
+
<tr><td>&nbsp; profiles/packages.mask/funtoo-flora-jeanfrancis</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>27</td><td>  <font color=#00a300>++</font><font color=#ff0000>-</font></td></tr>
+
<tr><td>&nbsp; profiles/sets/eclipse-sdk/eclipse-sdk.unmask</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>26</td><td>  <font color=#00a300>++</font></td></tr>
+
<tr><td>&nbsp; www-servers/jetty/Manifest</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>2</td><td>  <font color=#00a300>+</font></td></tr>
+
<tr><td>&nbsp; www-servers/jetty/jetty-6.1.24.ebuild</td><td>{{!}}&nbsp;&nbsp;</td><td align=right>45</td><td>  <font color=#00a300>+++</font></td></tr>
+
</table>
+
&nbsp; 26 files changed, 1430 insertions(+), 1 deletions(-)<br>
+
&nbsp; create mode 100644 dev-java/asm/Manifest<br>
+
&nbsp; create mode 100644 dev-java/asm/asm-3.3.1.ebuild<br>
+
&nbsp; create mode 100644 dev-java/lucene-analyzers/Manifest<br>
+
&nbsp; create mode 100644 dev-java/lucene-analyzers/files/manifest<br>
+
&nbsp; create mode 100644 dev-java/lucene-analyzers/lucene-analyzers-2.9.4.ebuild<br>
+
&nbsp; create mode 100644 dev-java/sat4j-core/Manifest<br>
+
&nbsp; create mode 100644 dev-java/sat4j-core/sat4j-core-2.3.0.ebuild<br>
+
&nbsp; create mode 100644 dev-java/sat4j-pseudo/Manifest<br>
+
&nbsp; create mode 100644 dev-java/sat4j-pseudo/sat4j-pseudo-2.3.0.ebuild<br>
+
&nbsp; create mode 100644 dev-java/swt/Manifest<br>
+
&nbsp; create mode 100644 dev-java/swt/files/as-needed-and-flag-fixes-3.6.patch<br>
+
&nbsp; create mode 100644 dev-java/swt/files/build.xml<br>
+
&nbsp; create mode 100644 dev-java/swt/files/swt-3.7-manifest<br>
+
&nbsp; create mode 100644 dev-java/swt/swt-3.7.ebuild<br>
+
&nbsp; create mode 100644 dev-util/eclipse-sdk/Manifest<br>
+
&nbsp; create mode 100644 dev-util/eclipse-sdk/eclipse-sdk-3.7.0.ebuild<br>
+
&nbsp; create mode 100644 dev-util/eclipse-sdk/files/3.7/eclipse-3.7<br>
+
&nbsp; create mode 100644 dev-util/eclipse-sdk/files/3.7/eclipserc-3.7<br>
+
&nbsp; create mode 100644 dev-util/eclipse-sdk/files/3.7/gtk_makefile.patch<br>
+
&nbsp; create mode 100644 dev-util/eclipse-sdk/files/3.7/hamcrest-junit-lib.patch<br>
+
&nbsp; create mode 100644 dev-util/eclipse-sdk/files/3.7/iterators.patch<br>
+
&nbsp; create mode 100644 profiles/docs/README.eclipse-sdk<br>
+
&nbsp; create mode 100644 profiles/sets/eclipse-sdk/eclipse-sdk.unmask<br>
+
&nbsp; create mode 100644 www-servers/jetty/Manifest<br>
+
&nbsp; create mode 100644 www-servers/jetty/jetty-6.1.24.ebuild<br>
+
$ git merge master develop
+
}}
+
 
+
This should always be done before you start working in flora. To make it easier you can write a short shell script to automate this, or copy our script here and place it in /root/bin/floraupdate
+
 
+
<pre>
+
#!/bin/sh
+
cd <path-to-your-flora-clone>
+
git fetch upstream
+
git merge upstream/master
+
git merge master develop
+
</pre>
+
 
+
When you would like to start a new ebuild for a package you want to add to flora sure you are on the development branch. You can check this with:
+
 
+
{{shell
+
| Input = $ git branch<br>
+
&nbsp;* <font color=#00a300>develop</font><br>
+
&nbsp;  master
+
}}
+
 
+
The asterisk tells you which branch is currently your active working branch. If it isn't "develop" you switch there with:
+
{{shell
+
| Input = $ git branch develop
+
}}
+
 
+
Now that you are in the right branch, you may begin your work as your tree should now be up-to-date. :)
+
 
+
=== Adding a new ebuild ===
+
 
+
{{shell
+
| Desc = Creating a feature branch for the work you do
+
| Input = $ git-flow feature start <name-of-ebuild>
+
}}
+
 
+
You will be now in the "feature/<name-of-ebuild>" branch, but be aware that git-flow doesn't like whitespace in the name-of-ebuild name.
+
 
+
Now you can work on the feature. When you are finished with doing all the additions and modifications of the ebuild you are going to push to flora, finish your work with:
+
 
+
{{shell
+
| Input = $ git-flow feature finish <name-of-ebuild><br>
+
Switched to branch 'develop'<br>
+
Already up-to-date.<br>
+
Deleted branch feature/<name-of-ebuild> (was af665e9).<br><br>
+
Summary of actions:<br>
+
- The feature branch 'feature/<name-of-ebuild>' was merged into 'develop'<br>
+
- Feature branch 'feature/<name-of-ebuild>' has been removed<br>
+
- You are now on branch 'develop'<br>
+
}}
+
 
+
Now you can start adding a new ebuild with the same above procedure. To go back to your development branch without closing the feature branch you can do:
+
 
+
{{shell
+
| Input = $ git checkout develop
+
}}
+
 
+
This way you will not have included your feature branch with your development branch. You can have several ebuilds developed simultaneously without having to worry about your development branch being compromised. If you want to delete a branch, for instance if the ebuild has already been added by somebody else, do:
+
 
+
{{shell
+
| Input = $ git branch -d <branch-name>
+
}}
+
 
+
Where in the example above, the <branch-name> would be "feature/<name-of-ebuild>". You should now be able to work on the development branch, and commit a new ebuild to your development branch. :)
+
 
+
=== Doing a hotfix ===
+
 
+
Let's say that a user of one of your ebuilds has encountered an issue with it, and you already know how to fix the problem. You'll need to use the following command to make a hotfix for your ebuild:
+
 
+
{{shell
+
| Desc = Starting a hotfix
+
| Input = $ git-flow hotfix start <ebuild-name-you-do-the-hotfix-for><br>
+
Switched to a new branch 'hotfix/<ebuild-name-you-do-the-hotfix-for>'<br><br>
+
Summary of actions:<br>
+
- A new branch 'hotfix/<ebuild-name-you-do-the-hotfix-for>' was created, based on 'master'<br>
+
- You are now on branch 'hotfix/<ebuild-name-you-do-the-hotfix-for>'<br><br>
+
Follow-up actions:<br>
+
- Bump the version number now!<br>
+
- Start committing your hot fixes<br>
+
- When done, run:<br><br>
+
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$ git-flow hotfix finish '<ebuild-name-you-do-the-hotfix-for>'
+
}}
+
 
+
When you are done, you will need to publish your hotfix:
+
 
+
{{shell
+
| Input = $ git-flow hotfix finish <ebuild-name-you-do-the-hotfix-for>
+
Deleted branch hotfix/<ebuild-name-you-do-the-hotfix-for> (was 2c52d0d).<br><br>
+
Summary of actions:<br>
+
- Latest objects have been fetched from 'origin'<br>
+
- Hotfix branch has been merged into 'master'<br>
+
- The hotfix was tagged '<ebuild-name-you-do-the-hotfix-for>'<br>
+
- Hotfix branch has been back-merged into 'develop'<br>
+
- Hotfix branch 'hotfix/<ebuild-name-you-do-the-hotfix-for>' has been deleted<br>
+
}}
+
 
+
Now your hotfix has been published. Your next step is to push it. Read [[flora#Submitting your release]] for more information.
+
 
+
=== Doing a release of your ebuild ===
+
 
+
Now that you are aware of how to add a new ebuild to your local fork of flora you need to learn how to make a release. It's as easy as doing the preparations itself :)
+
 
+
First prepare to push the release.
+
 
+
{{shell
+
| Desc = Preparing the release
+
| Input = $ git-flow release start <desc-of-release><br>
+
Switched to a new branch 'release/<desc-of-release>'<br><br>
+
Summary of actions:<br>
+
- A new branch 'release/<desc-of-release>' was created, based on 'develop'<br>
+
- You are now on branch 'release/<desc-of-release>'<br><br>
+
Follow-up actions:<br>
+
- Bump the version number now!<br>
+
- Start committing last-minute fixes in preparing your release<br><br
+
- When done, run:<br><br>
+
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$ git-flow release finish '<desc-of-release>'
+
}}
+
 
+
You should now make the final corrections for your release; if you find out that there are still any problems with your ebuild, fix it now. When you are finished, do:
+
 
+
{{shell
+
| Desc = Finish the release
+
| Input = $ git-flow release finish <desc-of-release><br>
+
Summary of actions:<br>
+
- Latest objects have been fetched from 'origin'<br>
+
- Release branch has been merged into 'master'<br>
+
- The release was tagged '<desc-of-release>'<br>
+
- Release branch has been back-merged into 'develop'<br>
+
- Release branch 'release/<desc-of-release>' has been deleted
+
}}
+
 
+
Now get ready to submit all of your changes :)
+
 
+
=== Submitting your release ===
+
 
+
This part is the easiest as you don't have to do anything special.
+
 
+
{{shell
+
| Desc = Submitting to your Fork of flora
+
| Input = $ git add .<br>
+
$git commit<br>
+
[master 8f9414a] committextsubject line<br>
+
&nbsp;&nbsp; 1 files changed, 1 insertions(+), 0 deletions(-)
+
&nbsp;&nbsp; create mode 100644 test-file <br>
+
$ git push<br>
+
Counting objects: 4, done.<br>
+
Delta compression using up to 2 threads.<br>
+
Compressing objects: 100% (2/2), done.<br>
+
Writing objects: 100% (3/3), 342 bytes, done.<br>
+
Total 3 (delta 1), reused 0 (delta 0)<br>
+
To git@github.com:golodhrim/flora.git<br>
+
&nbsp;&nbsp;&nbsp;&nbsp;7361f3f..8f9414a  master -> master
+
}}
+
 
+
That was it. :)
+
 
+
=== Make us aware of your additions ===
+
 
+
To make us aware of your additions to flora visit your flora overlay under [http://github.com/your-username/flora http://github.com/<your-username>/flora].
+
 
+
There you will find a link labeled "Pull Request". Look for the red circle in the following screenshot. :)
+
 
+
[[Image:pull-request.png|800px ]]
+
 
+
After clicking the Pull Request button, you will be presented with a preview page where you can enter a title and optional description, see exactly which commits will be included when your pull request is sent, and also see who will be notified about your pull request:
+
 
+
[[Image:pull-request2.png|800px]]
+
 
+
Markup is supported in the description, so you can embed images or use preformatted text blocks. Switch to the "Commits" tab to ensure that the correct set of changes is being sent:
+
 
+
[[Image:pullrequest-check1.png|800px]]
+
 
+
Review the diff of all changes by switching to the "Files Changed" tab:
+
 
+
[[Image:pullrequest-check2.png|800px]]
+
 
+
We should now be aware of your request and will decide how to handle it. It will usually be approved.
+
 
+
== Special stuff in flora ==
+
 
+
The following content is also available in "flora/profiles/doc/README"
+
 
+
We have added 3 folders to flora/profiles called 'package.mask', 'sets' and 'docs'. These folders are there for a special reason and you should be aware of some rules that need to be followed to allow all of us to live peacefully together.
+
 
+
=== What are the folders there for? ===
+
+
* flora/profiles/docs<br>This folder is there for docs if you require a special setup, like using sets for unmasking special stuff.
+
* flora/profiles/sets<br>This folder is there to define a special unmasking set or use flag set for packages you sent to flora. Your sets should be put into subfolders.
+
* flora/profiles/package.mask<br>As you might have already guessed, here you can set masks for packages you have submitted. Please don't mask packages that you haven't submitted yourself, as this can result in a great deal of trouble for the devs, and is something we would prefer to avoid.
+
 
+
=== rules for flora/profiles/docs ===
+
 
+
In 'flora/profiles/docs' you will insert docs for special instructions like unmasking your ebuilds if you masked them. While it is preferred to try avoiding the masking of ebuilds, sometimes it is not possible to avoid it. Your doc should be named README.<package> so that users can easily find it.
+
 
+
=== rules for flora/profiles/sets ===
+
 
+
In 'flora/profiles/sets' you will insert sets to unmask several ebuilds at a time, for example if you commit 5 packages that are needed to build for testing purposes, and you decide to mask them first. You can define a set here to unmask them. These sets go in subfolders of 'flora/profiles/sets' so you would end up with a structure like:
+
+
flora/profiles/sets/<packagename>/<packagename>.unmask
+
 
+
The content of such an unmask file might look like the following.
+
 
+
<pre> 
+
#############################################################
+
# unmask for <packagename>
+
#############################################################
+
=<category>/<packagename>-<version>
+
...
+
</pre>
+
 
+
In the docs you should then tell the user to link
+
 
+
<pre>'portage-path/profiles/sets/<packagename>/<packagename>.unmask'</pre>
+
 
+
into /etc/portage/package.unmask/<packagename> or add the contents of the file to /etc/portage/package.unmask depending on their setup. :)
+
 
+
=== Rules for flora/profiles/package.mask ===
+
 
+
Here we use the strongest rules that need to be followed!
+
+
* Do not mask any core packages! You are only allowed to mask packages that you are responsable for. If you try to commit core packages we could also get angry, so please talk with us first about these packages. We don't bite, but do get angry if you try to kill our core >:)
+
* Try to avoid masking packages if possible! :)
+
* Mask reasons have to be significant and should be explained in detail. Remember that you are responsible for your masks, as no Core Team member will remove them!
+
* Users that didn't set the mask are not allowed to remove it! Only the submitter is allowed to do so! :)
+
 
+
These are just four simple rules that you must follow so that we don't get into trouble.
+
+
For 'flora/profiles/package.mask' we recommend the following setup:
+
 
+
<pre>flora/profiles/package.mask/funtoo-flora-<username></pre>
+
 
+
That way we don't have to worry about 3 people editing the same file and giving us headaches when we merge. :)
+
 
+
If you follow these few rules we are positive that we will get on in a good manner here and live next to each other in peace.
+
 
+
 
+
== Special note for Flora contributors ==
+
 
+
All contributors to Flora, please edit your userpage.
+
 
+
* Create an account on our [http://www.funtoo.org/index.php?title=Special:UserLogin page here] if you do not have already, else login and
+
* go to your Userpage and edit/create it with the Form (Create with Form/Edit with Form Button at the top right) :)
+
* add all your ebuilds you added to Flora with that form in the format "sys-foo/bar"
+
* save your userpage.
+
 
+
This will help us to see who was responsible for which ebuild and who we should contact if there is a build failure or problems with the ebuild. Thanks for your help. :)
+
  
== Other Wiki Info for Flora ==
+
== References ==
  
All the above info can also be found on githubs wiki page for flora too, just have a view [https://github.com/funtoo/flora/wiki here]
+
[http://forums.funtoo.org/viewtopic.php?id=193 localpatch feature announcement on the funtoo forum]
  
[[Category:Projects]] [[Category:Portage]] [[Category:Featured]]
+
[[Category:Tutorial]]
 +
[[Category:Portage]]

Revision as of 03:20, 18 September 2012

Contents

Introduction

Localpatch (known in gentoo as epatch_user) is a feature that lets you, the user, add patches to official ebuilds without having to maintain the ebuild in question in a local overlay, thus avoiding the maintenance overhead associated with keeping your local overlay in sync with revision and version bumps.

Ebuilds can use this feature by calling epatch_user in their src_prepare () function (preferrably after their own patching).

For future reference, I'm going to document here how I used epatch_user to add a patch to sys-kernel/gentoo-sources.

Motivation

I use the Open Source AMD/ATi Radeon KMS drivers with my funtoo boxes and was seeing random kernel OOPSes with Xorg and 3D applications (the flurry 3D screensaver and games mainly).

I asked in #radeon on the FreeNode IRC network and Dave Airlie was kind enough to link me to a commit that was merged in linux-3.0. However, as I am using 2.6.39-r3 w/aufs2 (which was not available for 3.0 at the time of this writing), I decided to apply the patch myself.

UPDATE: The patch has landed upstream in the vanilla linux-2.6.39.4 kernel.

How it works

Important: localpatch feature removed form recent portage, available in foobashrc.
# emerge foobashrc

Reviewing the /usr/portdir/sys-kernel/gentoo-sources ebuilds reveals that they inherit the kernel-2.eclass. Looking at /usr/portage/eclass/kernel-2.eclass, I noticed that it included a reference to epatch_user in the function kernel-2_src_unpack().

/usr/portage/eclass # grep epatch_user * revealed that the epatch_user bash function is currently defined as follows in /usr/portage/eclass/eutils.eclass:

epatch_user() {
        [[ $# -ne 0 ]] && die "epatch_user takes no options"

        # don't clobber any EPATCH vars that the parent might want
        local EPATCH_SOURCE check base=${PORTAGE_CONFIGROOT%/}/etc/portage/patches
        for check in {${CATEGORY}/${PF},${CATEGORY}/${P},${CATEGORY}/${PN}}; do
                EPATCH_SOURCE=${base}/${CTARGET}/${check}
                [[ -r ${EPATCH_SOURCE} ]] || EPATCH_SOURCE=${base}/${CHOST}/${check}
                [[ -r ${EPATCH_SOURCE} ]] || EPATCH_SOURCE=${base}/${check}
                if [[ -d ${EPATCH_SOURCE} ]] ; then
                        EPATCH_SOURCE=${EPATCH_SOURCE} \
                        EPATCH_SUFFIX="patch" \
                        EPATCH_FORCE="yes" \
                        EPATCH_MULTI_MSG="Applying user patches from ${EPATCH_SOURCE} ..." \
                        epatch
                        return 0
                fi
        done
        return 1
}

From the Gentoo Development Guide we can deduce that the following paths are valid (using sys-kernel/gentoo-sources-2.6.39-r3 as an example):

/etc/portage/patches/sys-kernel/gentoo-sources-2.6.39-r3 # ${CATEGORY}/${PF}
/etc/portage/patches/sys-kernel/gentoo-sources-2.6.39    # ${CATEGORY}/${P}
/etc/portage/patches/sys-kernel/gentoo-sources           # ${CATEGORY}/${PN}

For my particular use case, I added the radeon kms patch titled drm/radeon: fix oops in ttm reserve when pageflipping (v2):

/etc/portage/patches/sys-kernel/gentoo-sources-2.6.39-r3/linux-2.6.git-498c555f56a02ec1059bc150cde84411ba0ac010.patch

Testing it

Let's test that it works as expected:

# cd /usr/portage/sys-kernel/gentoo-sources/
# ebuild gentoo-sources-2.6.39-r3.ebuild clean
# ebuild gentoo-sources-2.6.39-r3.ebuild prepare
 * linux-2.6.39.tar.bz2 RMD160 SHA1 SHA256 size ;-) ...                                      [ ok ]
 * genpatches-2.6.39-5.base.tar.bz2 RMD160 SHA1 SHA256 size ;-) ...                          [ ok ]
 * genpatches-2.6.39-5.extras.tar.bz2 RMD160 SHA1 SHA256 size ;-) ...                        [ ok ]
 * checking ebuild checksums ;-) ...                                                         [ ok ]
 * checking auxfile checksums ;-) ...                                                        [ ok ]
 * checking miscfile checksums ;-) ...                                                       [ ok ]
 * checking linux-2.6.39.tar.bz2 ;-) ...                                                     [ ok ]
 * checking genpatches-2.6.39-5.base.tar.bz2 ;-) ...                                         [ ok ]
 * checking genpatches-2.6.39-5.extras.tar.bz2 ;-) ...                                       [ ok ]
 * Package:    sys-kernel/gentoo-sources-2.6.39-r3
 * Repository: gentoo
 * Maintainer: kernel@gentoo.org
 * USE:        amd64 elibc_glibc kernel_linux multilib userland_GNU
 * FEATURES:   fakeroot installsources preserve-libs sandbox splitdebug userpriv usersandbox
>>> Preparing to unpack ...
>>> Unpacking source...
>>> Unpacking linux-2.6.39.tar.bz2 to /home/portage/tmp/portage/sys-kernel/gentoo-sources-2.6.39-r3/work
>>> Unpacking genpatches-2.6.39-5.base.tar.bz2 to /home/portage/tmp/portage/sys-kernel/gentoo-sources-2.6.39-r3/work/patches
>>> Unpacking genpatches-2.6.39-5.extras.tar.bz2 to /home/portage/tmp/portage/sys-kernel/gentoo-sources-2.6.39-r3/work/patches
 * Applying 1000_linux-2.6.39.1.patch (-p0+) ...                                             [ ok ]
 * Applying 1001_linux-2.6.39.2.patch (-p0+) ...                                             [ ok ]
 * Applying 1002_linux-2.6.39.3.patch (-p0+) ...                                             [ ok ]
 * Applying 2900_disable-wunused-but-set-var-gcc-4-6-0.patch (-p0+) ...                      [ ok ]
 * Applying 2910_gnu-make-3.80-compat-fix.patch (-p0+) ...                                   [ ok ]
 * Applying 4200_fbcondecor-0.9.6.patch (-p0+) ...                                           [ ok ]
 * Applying user patches from /etc/portage/patches/sys-kernel/gentoo-sources-2.6.39-r3 ...
 *   linux-2.6.git-498c555f56a02ec1059bc150cde84411ba0ac010.patch ...                        [ ok ]
 * Done with patching
>>> Source unpacked in /home/portage/tmp/portage/sys-kernel/gentoo-sources-2.6.39-r3/work
>>> Preparing source in /home/portage/tmp/portage/sys-kernel/gentoo-sources-2.6.39-r3/work/linux-2.6.39-gentoo-r3 ...
>>> Source prepared.
#

Et voilà -- a cleanly patched kernel.

References

localpatch feature announcement on the funtoo forum