New Developer/Maintainer guide
From ProAudioOverlay
(New page: Some hints for new Developer/Maintainer =get a account at tuxfamily.org= You need to get a account at http://tuxfamily.org (they provide the svn-repo and Webspace) ==request svn write ...) |
(→example proaudio / proaudio-dev overlays setup) |
||
(15 intermediate revisions not shown) | |||
Line 15: | Line 15: | ||
==checkout the overlay== | ==checkout the overlay== | ||
- | also read 4.0 and 4.1 before doing this step | + | also read [[New_Developer/Maintainer_guide#overlay hierarchy:|4.0]] and [[New_Developer/Maintainer_guide#example proaudio / proaudio-dev overlays setup|4.1]] before doing this step |
svn co svn+ssh://<your_tuxfamily_login>@svn.tuxfamily.org/svnroot/proaudio/proaudio | svn co svn+ssh://<your_tuxfamily_login>@svn.tuxfamily.org/svnroot/proaudio/proaudio | ||
or | or | ||
Line 62: | Line 62: | ||
==move files around (e.g bumping) (if former version is obsolete)== | ==move files around (e.g bumping) (if former version is obsolete)== | ||
svn mv foo/foobar-123.ebuild foo/foobar-124.ebuild | svn mv foo/foobar-123.ebuild foo/foobar-124.ebuild | ||
- | + | If not obsolete you could also bump with svn cp | |
svn cp foo/foobar-123.ebuild foo/foobar-124.ebuild | svn cp foo/foobar-123.ebuild foo/foobar-124.ebuild | ||
or of course with just 'cp' and adding new files afterwards with | or of course with just 'cp' and adding new files afterwards with | ||
svn add foo/foobar-124.ebuild | svn add foo/foobar-124.ebuild | ||
- | + | Make sure to adjust dependencies (DEPEND RDEPEND) if needed | |
- | If you | + | If you have trouble with the right syntax, look at point 3.1 |
- | + | If you are bumping, make sure to redigest, and also to add | |
- | the digest of the ebuild to the overlay | + | the digest of the ebuild to the overlay. |
- | + | For above example: | |
svn st # gives you this | svn st # gives you this | ||
? files/digest-foobar-124 | ? files/digest-foobar-124 | ||
Line 77: | Line 77: | ||
so the following step is also needed before a commit | so the following step is also needed before a commit | ||
svn add files/digest-foobar-124 | svn add files/digest-foobar-124 | ||
- | + | now svn st shows | |
A files/digest-foobar-124 | A files/digest-foobar-124 | ||
<snip> | <snip> | ||
- | ready for | + | ready for committing |
- | + | ||
==reverse your local changes to an ebuild/folder== | ==reverse your local changes to an ebuild/folder== | ||
Line 101: | Line 100: | ||
- | ==generate patches | + | ==generate patches to review some change == |
eg. local modification to last checkout | eg. local modification to last checkout | ||
svn diff foo/foobar-123.ebuild | svn diff foo/foobar-123.ebuild | ||
or a diff to a specific revision | or a diff to a specific revision | ||
svn diff -r 3 foo/foobar-123.ebuild | svn diff -r 3 foo/foobar-123.ebuild | ||
- | |||
==login automatically to svn-server== | ==login automatically to svn-server== | ||
Line 138: | Line 136: | ||
- | ==check your ebuilds if they are | + | ==check your ebuilds if they are actually working (repoman) == |
- | + | To ensure correct ebuilds, you could run repoman which checks for invalid syntax, missing vars. | |
- | for invalid syntax, missing vars, . | + | |
- | + | To do this, cd into your package directory and run repoman. | |
+ | |||
+ | cd ${overlay_dir}/media-sound/foobar | ||
+ | repoman | ||
+ | |||
+ | Or if you want to really get stuck in, run it in the top level directory of an overlay. | ||
+ | |||
+ | cd ${overlay_dir} | ||
+ | repoman | ||
==ebuild archs (KEYWORDS)== | ==ebuild archs (KEYWORDS)== | ||
- | + | For adding/removing keywords use (man ekeyword): | |
+ | ekeyword | ||
+ | |||
+ | Add the your working archs into KEYWORDS. I prefer mostly stable keywords | ||
but if a new version of a pkg could break things do ~arch | but if a new version of a pkg could break things do ~arch | ||
- | or if known to not work | + | or if known to not work |
- | ALL snapshot/live (cvs/svn/...) ebuilds should have KEYWORDS="" | + | KEYWORDS="-*" |
- | --> this | + | ALL snapshot/live (cvs/svn/...) ebuilds should have: |
+ | KEYWORDS="" | ||
+ | --> this means not known if it will work as it could change quickly | ||
Use -9999 for the ebuild filename: | Use -9999 for the ebuild filename: | ||
foobar-9999.ebuild | foobar-9999.ebuild | ||
Line 163: | Line 174: | ||
==update the package list== | ==update the package list== | ||
- | + | Please execute both scripts before committing some bumped or new | |
ebuilds to the overlay. | ebuilds to the overlay. | ||
- | Execute | + | Execute these scripts inside the overlay root. They modify two |
files inside the overlay. | files inside the overlay. | ||
./prepare_tree # checks for some digest breakage and | ./prepare_tree # checks for some digest breakage and | ||
Line 172: | Line 183: | ||
./generate-detailed-packages-list # generate 00-DETAILED-PACKAGES-LIST | ./generate-detailed-packages-list # generate 00-DETAILED-PACKAGES-LIST | ||
- | + | ==add missing apps to [[TODO]]== | |
- | ==add missing apps to | + | If you have found a nice-to-have app which is not already in the overlay |
- | + | and you think there should be a ebuild but have no time and before | |
- | and you think there should be a ebuild but | + | you forget about it, add an entry about there. |
- | you forget about it add | + | |
For every missing app with have a "block" which needs some details | For every missing app with have a "block" which needs some details | ||
- | NAME: | + | NAME: |
- | + | EBUILD_STATE: none/working/ | |
+ | WHERE_TO_FETCH_EBUILD: <location if an ebuilds already exists> | ||
DEVELOPER: <maybe your name> | DEVELOPER: <maybe your name> | ||
DESCR: <info about the app> | DESCR: <info about the app> | ||
HOMEPAGE: http://foo.bar | HOMEPAGE: http://foo.bar | ||
- | If you | + | If you have added an ebuild that is listed in the todo file |
please remove its entry | please remove its entry | ||
Line 223: | Line 234: | ||
PORTDIR_OVERLAY="/home/evermind/svn-checkouts/proaudio/trunk/overlays/proaudio /home/evermind/svn-checkouts/proaudio/trunk/overlays/proaudio-dev <other overlays>" | PORTDIR_OVERLAY="/home/evermind/svn-checkouts/proaudio/trunk/overlays/proaudio /home/evermind/svn-checkouts/proaudio/trunk/overlays/proaudio-dev <other overlays>" | ||
+ | The main issue to understand is we cannot use /var/lib/layman/pro-audio to commit change to the repository. This path is managed by layman, and for subversion, this is not a working copy but a read-only copy. | ||
+ | |||
+ | Another setup is to use 3 copies, the svn checkout as before, the layman managed copy in /var/lib/layman/pro-audio (install it as usual with layman: | ||
+ | layman -a pro-audio | ||
+ | this is the copy that will be used by portage), and a test overlay that will be used to test new ebuilds and changes to the overlay. You can use it too for personal ebuilds. | ||
+ | I placed it into /var/lib/layman/test. Edit /var/lib/layman/make.conf and add the overlay: | ||
+ | PORTDIR_OVERLAY="whatever you have | ||
+ | /var/lib/layman/test" | ||
+ | |||
+ | It will not be managed by layman but portage will find and use it. By placing the test overlay at the end of the list, it will take precedence: if portage find 2 different ebuilds with the same filename, it will use the one from the test overlay. | ||
+ | |||
+ | With this last setup, we have a 3 steps workflow: | ||
+ | 1) create or modify an ebuild into the test overlay | ||
+ | 2) copy it into the working copy in $HOME | ||
+ | 3) commit the changes | ||
+ | |||
+ | The advantage of this setup is that now, we can synchronise the layman overlay (layman -s pro-audio), remove the ebuild from the test overlay and test the result with portage (emerge -a my_new_audio_soft). | ||
+ | |||
+ | =adding files to the overlay= | ||
+ | We do have a distfiles repository where we can add files: | ||
+ | ftp://ftp.tuxfamily.org/proaudio/proaudio-repository/distfiles | ||
+ | You can use your favourite ftp client to uplaod files. Use your tuxfamily username and password. | ||
+ | |||
+ | From an ebuild, it can be accessed with: | ||
+ | http://download.tuxfamily.org/proaudio/distfiles/ | ||
=feel free to ask= | =feel free to ask= | ||
if you've questions problems you could always ask on the ml | if you've questions problems you could always ask on the ml | ||
- | Communication is everything | + | Communication is everything |
- | + | ||
=testing ebuilds on different archs= | =testing ebuilds on different archs= | ||
Line 238: | Line 273: | ||
so rekeyword if it builds AND works and check it into the svn repository | so rekeyword if it builds AND works and check it into the svn repository | ||
(some ebuilds might only work on the given arch) | (some ebuilds might only work on the given arch) | ||
+ | [[Category:Howto]] |
Latest revision as of 14:15, 8 March 2013
Some hints for new Developer/Maintainer
get a account at tuxfamily.org
You need to get a account at http://tuxfamily.org (they provide the svn-repo and Webspace)
request svn write access
Just write to Thomas or me (Frieder) gain write accesss
basic subversion commands
You've to know how to checkout/commit the overlay repository: So here some basics:
checkout the overlay
also read 4.0 and 4.1 before doing this step
svn co svn+ssh://<your_tuxfamily_login>@svn.tuxfamily.org/svnroot/proaudio/proaudio
or
svn co --username <your_tuxfamily_login> svn+ssh://svn.tuxfamily.org/svnroot/proaudio/proaudio
for me the subversion server asked me three times before accepting my password
howto add a new ebuild to the tree
go inside your repository checkout eg into media-sound
cd ~/path/to/proaudio/media-sound mkdir foo cd foo vi foo-0.1.ebuild ebuild foo-0.1.ebuild digest cd .. svn st|status # see the changes made to local repository # ? - means not added to the tree (svn ci ignore those files) # A - means freshly added to the overlay but not commited # C - means conflicting with a previous revision # to avoid this: do a "svn up" to make sure # you edit the latest version of a ebuild # D - means files gets deleted with next commit # U - means updated
svn add foo # adds directory foo recurively to the overlay (only local) svn ci|commit # until commit nothing changes in the repository on the # svn-server svn ci -m 'what this commit changes' # you could add just in one line what # your commit actually changes instead of using a vim/nano/...
just change a ebuild
1. close the your prefered editor 2. redigest your ebuild
svn st # displays the changes made to the overlay svn ci # commit changes
delete some files/directories
svn del foo # this changes are just local on your copy of the repository # sometimes svn don't allow to delete things so try with --force svn ci # commit changes
move files around (e.g bumping) (if former version is obsolete)
svn mv foo/foobar-123.ebuild foo/foobar-124.ebuild
If not obsolete you could also bump with svn cp
svn cp foo/foobar-123.ebuild foo/foobar-124.ebuild
or of course with just 'cp' and adding new files afterwards with
svn add foo/foobar-124.ebuild
Make sure to adjust dependencies (DEPEND RDEPEND) if needed If you have trouble with the right syntax, look at point 3.1 If you are bumping, make sure to redigest, and also to add the digest of the ebuild to the overlay. For above example:
svn st # gives you this ? files/digest-foobar-124 <snip>
so the following step is also needed before a commit
svn add files/digest-foobar-124
now svn st shows
A files/digest-foobar-124 <snip>
ready for committing
reverse your local changes to an ebuild/folder
svn revert path/to/file_which_you_want_to_revert # revert a file svn revert -R foo/ # revert recursively all changes made in foo/
display the subversion log
svn log # diplays the logfile
edit the logfile if your message was not correct
and you feel you should correct it
svn propedit svn:log --revprop -r <revision-number>
change the repository server location (JFYI) :)
svn switch --relocate svn://svn.tuxfamily.org/svnroot/ckpp/proaudio svn://svn.tuxfamily.org/svnroot/proaudio/proaudio/
generate patches to review some change
eg. local modification to last checkout
svn diff foo/foobar-123.ebuild
or a diff to a specific revision
svn diff -r 3 foo/foobar-123.ebuild
login automatically to svn-server
put your id_rsa.pub key to the root of your (generate one if you don't have already one)
--> ssh-keygen -t rsa
ftp-account at ftp.tuxfamily.org you can use ncftpput (emerge ncftp) or any other ftp-client
ncftpput -u <your_tuxfamily_login> -C ftp.tuxfamily.org ~/.ssh/id_rsa.pub ssh_keys
our policy/rules
read the ebuild documentation at
http://proaudio.tuxfamily.org/wiki/index.php?title=Contribute_ebuilds # and the also the gentoo ebuild manuals :)
run svn up
to avoid double-work always work on the latest checkout with
svn up
ebuild license
All commited ebuild must have to be licensed gnu gpl v2 so contribute with proper header eg.
Copyright 1999-2007 Gentoo Foundation Distributed under the terms of the GNU General Public License v2 $Header: $
check your ebuilds if they are actually working (repoman)
To ensure correct ebuilds, you could run repoman which checks for invalid syntax, missing vars.
To do this, cd into your package directory and run repoman.
cd ${overlay_dir}/media-sound/foobar repoman
Or if you want to really get stuck in, run it in the top level directory of an overlay.
cd ${overlay_dir} repoman
ebuild archs (KEYWORDS)
For adding/removing keywords use (man ekeyword):
ekeyword
Add the your working archs into KEYWORDS. I prefer mostly stable keywords but if a new version of a pkg could break things do ~arch or if known to not work
KEYWORDS="-*"
ALL snapshot/live (cvs/svn/...) ebuilds should have:
KEYWORDS=""
--> this means not known if it will work as it could change quickly Use -9999 for the ebuild filename:
foobar-9999.ebuild
more infos about KEYWORDS available at: http://dev.gentoo.org/~genone/docs/KEYWORDS.stupid and http://bugs.gentoo.org/show_bug.cgi?id=160519
redigest your ebuild
try to assure that you've redigest your ebuild before commit and also make sure that there are no temporary files laying around which cause digest failures for other people
update the package list
Please execute both scripts before committing some bumped or new ebuilds to the overlay. Execute these scripts inside the overlay root. They modify two files inside the overlay.
./prepare_tree # checks for some digest breakage and # generates 00-PACKAGES-LIST
and generate with
./generate-detailed-packages-list # generate 00-DETAILED-PACKAGES-LIST
add missing apps to TODO
If you have found a nice-to-have app which is not already in the overlay and you think there should be a ebuild but have no time and before you forget about it, add an entry about there. For every missing app with have a "block" which needs some details
NAME: EBUILD_STATE: none/working/ WHERE_TO_FETCH_EBUILD: <location if an ebuilds already exists> DEVELOPER: <maybe your name> DESCR: <info about the app> HOMEPAGE: http://foo.bar
If you have added an ebuild that is listed in the todo file please remove its entry
00-README 00-OVERLAY-INFO
this both files gives a bit of introduction to the overlay should be updated (feel free to edit them)
change the rules/scripts/ebuilds/readme's/...
you're free to change other peoples ebuilds if you could improve/fix You could also fix/enhance all scripts at point 3.5
hope this are not to much rules
overlay hierarchy:
for absolute experimental ebuild we have a dev branch in this branch ebuilds could really be broken. This is also a place where we can collaborate in developing new ebuilds (add this overlay also to your other overlays see 4.1) If you put a new ebuild here and the category is missing create it.
svn.tuxfamily.org/svnroot/proaudio/trunk/overlays/proaudio-dev
this is our main overlay in which only "working" ebuilds should be placed
svn.tuxfamily.org/svnroot/proaudio/trunk/overlays/proaudio
example proaudio / proaudio-dev overlays setup
this is how I've organized the proaudio overlay on my box I've placed the svn checkout in ~/svn-checkouts/
cd ~/svn-checkouts/
fetch the tree as developer
svn co svn+ssh://<your_tuxfamily_login>@svn.tuxfamily.org/svnroot/proaudio/proaudio
edit /etc/make.conf and add both overlays proaudio and proaudio-dev
PORTDIR_OVERLAY="/home/evermind/svn-checkouts/proaudio/trunk/overlays/proaudio /home/evermind/svn-checkouts/proaudio/trunk/overlays/proaudio-dev <other overlays>"
The main issue to understand is we cannot use /var/lib/layman/pro-audio to commit change to the repository. This path is managed by layman, and for subversion, this is not a working copy but a read-only copy.
Another setup is to use 3 copies, the svn checkout as before, the layman managed copy in /var/lib/layman/pro-audio (install it as usual with layman:
layman -a pro-audio
this is the copy that will be used by portage), and a test overlay that will be used to test new ebuilds and changes to the overlay. You can use it too for personal ebuilds. I placed it into /var/lib/layman/test. Edit /var/lib/layman/make.conf and add the overlay:
PORTDIR_OVERLAY="whatever you have /var/lib/layman/test"
It will not be managed by layman but portage will find and use it. By placing the test overlay at the end of the list, it will take precedence: if portage find 2 different ebuilds with the same filename, it will use the one from the test overlay.
With this last setup, we have a 3 steps workflow: 1) create or modify an ebuild into the test overlay 2) copy it into the working copy in $HOME 3) commit the changes
The advantage of this setup is that now, we can synchronise the layman overlay (layman -s pro-audio), remove the ebuild from the test overlay and test the result with portage (emerge -a my_new_audio_soft).
adding files to the overlay
We do have a distfiles repository where we can add files:
ftp://ftp.tuxfamily.org/proaudio/proaudio-repository/distfiles
You can use your favourite ftp client to uplaod files. Use your tuxfamily username and password.
From an ebuild, it can be accessed with:
http://download.tuxfamily.org/proaudio/distfiles/
feel free to ask
if you've questions problems you could always ask on the ml Communication is everything
testing ebuilds on different archs
ebuild which are not already tested on a specific arch could be found with the below script which is inside the proaudio overlay root
./check_ebuild_unstable-untested arch # eg ./check_ebuild_unstable-untested amd64
above script reveals all ebuilds without 'arch' --> this ebuilds needs testing so rekeyword if it builds AND works and check it into the svn repository (some ebuilds might only work on the given arch)