[Debian Wiki] Update of "BOINC/Development/GitUsage" by SteffenMoeller
Debian Wiki
debian-www at lists.debian.org
Sun Mar 25 20:56:56 UTC 2012
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Debian Wiki" for change notification.
The "BOINC/Development/GitUsage" page has been changed by SteffenMoeller:
http://wiki.debian.org/BOINC/Development/GitUsage?action=diff&rev1=38&rev2=39
Comment:
Some maintenance and improvement of the writing.
----
= Packaging BOINC with git =
- This page is work in progress. Please contact us if you are keen to receive an update. Such external stimuli often help :)
+ Whenever something on this page does not work as expected, or you had difficulties to understand the one or other bit, tell us. Such external stimuli are so very helpful, they should not be missed.
<<TableOfContents(3)>>
<<Anchor(Overview)>>
== Overview ==
- The general workflow for using the repository is to first have all upstream code in the collaboratively maintained remote branch 'upstream'. Several parallel efforts are kept on the server. The one last uploaded is always in the branch 'master'. One checks out the branch one wants to work with for performing the Debian packaging (maybe 'master') and merges all of upstream into it. Git-buildpackage will then perform the building.
+ The general workflow for using the repository is to first have all upstream code in the branch 'upstream'. That 'upstream' branch and the 'master' branch, which is upstream plus the debian folder, are the two main branches. They are kept on a particular server, git.debian.org, and everyone contributing to the pkg-boinc project can update them. The text below presents an overview on branches and how to invoke the tool 'git-buildpackage' to build the Debian packages from those branches alone.
+
== Branches ==
@@ -22, +23 @@
* upstream - the branch holding the upstream sources
* master - the branch holding the Debian directory that shall be packaged, one must have checked this one out when invoking git-buildpackage
- There are many more branches, which are somewhat historic, representing various attempts to be very current or very feature-rich. The server package never made it into Debian, sadly, mostly because none of us Debian package maintainers needs it and we are too busy to just play with it more.
+ There are many more branches, which are somewhat historic, representing various attempts to be very current or very feature-rich. The most imminent urge to work on are the branches for past releases of Debian, i.e. the 'stable' release and also 'old-stable'. As a Debian developer one commonly works with a newer release of Debian, like 'testing' or 'unstable', over which one forgets to feed the current official and older distributions with the latest end user software.
* debian/experimental
* debian/<codename>
* debian/backports/<codename>
- And there is this special branch here
+ Formerly, we used this special branch here
* pristine-tar
- which is not really required if one is only interested in the very latest source tree (as we are for boinc) but which plays into our hands once we support many different versions. Let's ignore this for now but find the 'pristine-tar' section below at a later time.
+ which helps with provisioning the source tarballs for the building of Debian packages. These are not really required since one gets those either directly from the Debian distribution or, if not yet uploaded, can also create them from the upstream branch.
After a first checkout of the repository (cloning in git terminology, described below) a list of branches available on the server is made visible with {{{
git branch -r
@@ -58, +59 @@
And to build the package, also install the following build-dependencies
{{{
apt-get install dh-buildinfo docbook2x automake1.9 autoconf libssl-dev libcurl4-openssl-dev freeglut3-dev libxmu-dev libxi-dev libwxgtk2.8-dev libsqlite3-dev libtool libnotify-dev libmysqlclient-dev libfcgi-dev libjpeg-dev libxss-dev
- }}}. This list is not unlikely to be outdated, since this page is not expected to be kept in complete sync. But don't worry, you will receive respective instructions should anything be missing.
+ }}}. This list is not unlikely to be outdated, since this page is not expected to be kept in complete sync. But don't worry, you will receive respective instructions when running git-buildpackage should anything be missing.
<<Anchor(AccessingRepositories)>>
@@ -71, +72 @@
git clone ssh://<alioth-login>@git.debian.org/git/pkg-boinc/<package>.git
cd *boinc*
}}}
- where <package> is one of 'boinc', 'boinc-app-seti' and 'kboincspy' as inspectable via http://git.debian.org.
+ where <package> is typically 'boinc' or 'boinc-scripts'. The Open Source SETI client is currently unmaintained and maintained in 'boinc-app-seti', also there is no longer a maintainer for 'kboincspy'. The repositories of pkg-boinc are inspectable via [[http://anonscm.debian.org/gitweb/|http://git.debian.org]] (long).
If you do not have an Alioth account, you can check out the repositories read-only:
{{{
git clone git://git.debian.org/git/pkg-boinc/<package>.git
cd *boinc*
}}}
+ But there is hope that we can get you actively involved.
That directory includes all the source code already, and it even shows a debian directory, all information seems available:
@@ -103, +105 @@
We will (optionally) be using git-buildpackage to build packages. That tool also helps with the initial setup o of it all: {{{
gbp-clone ssh://<alioth-login>@git.debian.org/git/pkg-boinc/<package>.git
}}}
- is a one line version of the prior manual creation of the Debian-associated packages. (Many thanks go to Guido for pointing this out.)
+ is a one line version of the prior manual creation of the Debian-associated packages. (Many thanks go to Guido for pointing this out.) Just, we have not been using the pristine-tar branch anymore for a couple of releases. Hence, feel free to 'git branch -d pristine-tar' if that pops in the 'git branch' list.
- == Upstream ==
+ == Upstream and the Upstream branch ==
+ "Upstream" is what was available before Debian packaging started. This is typically a tarball from the software developers' web pages. With BOINC, it is slightly different.
+
- We are interested in the differences between that "everything we need locally" master and the original upstream version. git is very good at determining such differences since difference between source trees is what source code management systems are all about. We just need another branch, ''upstream'' to keep the original. And that ''upstream'' branch remains untouched until there is a new upstream version.
+ We are interested in the differences between that "everything we need locally" master and the original upstream version. git is very good at determining such differences since differences between source trees is what source code management systems are all about. We just need another branch, ''upstream'' to keep the original. And that ''upstream'' branch remains untouched until there is a new upstream version.
- What cannot be stressed enough: The only branch that is edited is the master branch and/or a branch that was derived from it. When there is a new upstream release, then we overwrite the upstream branch with that new version completely. The changes to upstream we then merge with the master branch. The only differences between the master branch and the upstream branch should be in the debian folder. If you want to edit what upstream has done, then use the quilt system to prepare a patch. That patch should be communicated to upstream.
+ What cannot be stressed enough: The only branch that is edited is the master branch and/or a branch that was derived from it. When there is a new upstream release, then we overwrite the upstream branch with that new version completely. The changes to upstream we then merge with the master branch. The only differences between the master branch and the upstream branch should be in the debian folder. If you want to edit what upstream has done, then use the [[quilt]] system to prepare a patch. That patch should be communicated to upstream.
For an initial run of the packaging, nothing needs to be done. If this is your first contact with this page and/or git, then just proceed directly with the section 'Build Package'.
- <<Anchor(RegeneratingTarballs)>>
-
- === Regenerating upstream tarballs ===
-
- ''If you are only interested in the latest version
- that is in Debian, then you can easily skip this section. Just use the tool [[DebPkg:git-buildpackage]]
- and the {{{orig.tar.gz}}} will be created from your
- upstream branch.''
-
- Upstream {{{.orig.tar.gz}}} tarballs can be regenerated with the {{{pristine-tar}}} tool directly from the repositories. To do so create a local {{{pristine-tar}}} branch from the remote {{{origin/pristine-tar}}} branch first:
-
- {{{
- git checkout -b pristine-tar origin/pristine-tar
- }}}
- As a clarification to those new to git, when cloning, the source of our clone is referred to as "origin". The "checkout" when given the "-b" option creates a new branch, which happens to have the same name as the branch on the remote git server. Normally, one would branch from the local master, i.e. one adds or changes a series of files relative to what is already available. The "origin/" prefix above informs git to branch from the remote side, i.e. a completely new environment is established that is independent from the previously checked out code:
- {{{
- $ ls
- boinc_6.2.14.orig.tar.gz.delta boinc_6.2.18.orig.tar.gz.id boinc_6.6.10.orig.tar.gz.delta
- boinc_6.2.14.orig.tar.gz.id boinc_6.4.5.orig.tar.gz.delta boinc_6.6.10.orig.tar.gz.id
- boinc_6.2.18.orig.tar.gz.delta boinc_6.4.5.orig.tar.gz.id
- }}}
- All other files disappear.
-
- The new branch is now listed next to the previously cloned master branch:
- {{{
- git branch
- }}}
- Now to regenerate for example the {{{boinc_6.2.18.orig.tar.gz}}} tarball from the {{{boinc}}} repository run:
-
- {{{
- pristine-tar checkout boinc_6.2.18.orig.tar.gz
- }}}
- This pristine-tar is some magic on its own. The idea is to share upstream's resources and have them nicely integrated with the git and git-buildpackage functionalities. See this link http://www.eyrie.org/~eagle/notes/debian/git.html for a nice summary on what is going on.
-
- To find out which tarballs can be regenerated with the tool {{{pristine-tar}}}, check out what files there are in the branch with the same name:
-
- {{{
- git ls-tree pristine-tar
- }}}
=== Update the 'upstream' branch ===
@@ -160, +125 @@
of that branch should be performed once you are
familiar with the regular build process.''
- It is fairly likely that the latest branch in the upstream branch is older than the one we would like to work with. Upstream should then be updated. There are several ways to achieve that. Here the traditional way, which is the most intuitive (for the old folks here).
+ It is fairly likely that the latest branch in the upstream branch is older than the one you would like to work with. The upstream branch should then be updated. There are several ways to achieve that. Here the traditional way, which is the most intuitive (for the old folks here).
- 1. check out the source code with the right tag of the latest version. As explained in the debian/README.source, [[http://git.debian.org/?p=pkg-boinc/scripts.git;a=blob_plain;f=export-boinc;hb=HEAD|this script]] performs the checkout for us and removes some non-DFSG compatible material
+ 1. check out the source code with the right tag of the latest version. You can read about it in [[http://anonscm.debian.org/gitweb/?p=pkg-boinc/boinc.git;a=blob_plain;f=debian/README.source;hb=HEAD|debian/README.source]], which will point you to [[http://git.debian.org/?p=pkg-boinc/scripts.git;a=blob_plain;f=export-boinc;hb=HEAD|a script]] to perform the checkout and remove some non-DFSG compatible material by the side. But effectively, all you need to do is {{{
+ ./debian/rules get-orig-source
+ }}} which retrieves and executes that script.
1. use the git-import-orig tool to perform the actual import {{{
- git-import-orig ../boinc_6.10.44.orig.tar.gz
+ git-import-orig ../boinc_7.0.23+dfsg.orig.tar.gz
}}}. That tool already performs the merging of the the upstream branch with the master branch.
+ 1. $EDITOR debian/changelog and adjust it for the version now downloaded.
+ 1. {{{
+ git commit -m "Bumped to new upstream version" debian/changelog
+ }}}
To inspect the upstream branch, perform {{{
git checkout upstream
@@ -177, +148 @@
git status
}}}.
- The general concept is that git shows only those files that are assigned to the current branch, that have been already present when the branch was created, or that are assigned to no branch at all. Thus, once you compile the code, all the object files belong to no branch and will stay even when you go to the pristine-tar branch again. This is somewhat annoying at times.
+ The general concept is that git shows only those files that are assigned to the current branch, i.e. that have been already present when the branch was created, or that are assigned to no branch at all. Thus, once you compile the code, all the object files belong to no branch and will stay even when you go to the 'upstream' branch again. This is somewhat annoying at times.
Files that should be ignored by git, e.g. because they are generated by the build process and changes to them hence mostly neglectable are added to the file {{{.gitignore}}}.
@@ -187, +158 @@
Make sure you are in the master branch, if unsure, run 'git checkout master'. You will notice the directory named 'debian'.
Building packages with {{{git-buildpackage}}} is now as easy as running: {{{
- git buildpackage -rfakeroot
+ git-buildpackage -rfakeroot
}}}. One could improve that just a bit by not requesting signatures {{{
- git buildpackage -rfakeroot -uc -us
+ git-buildpackage -rfakeroot -uc -us
}}}. And if you are still evaluating bits here or there without having them checked in or the source tree was not properly cleaned from side-effects of the build, then run {{{
- git buildpackage -rfakeroot -uc -us --git-ignore-new
+ git-buildpackage -rfakeroot -uc -us --git-ignore-new
}}}.
- git-buildpackage will learn about the version to pack from the debian/changelog file. And since no .orig.tar.gz file is present, it will be recreated from the upstream branch. Once this was done, the remainder works as with dpkg-buildpackage, with no further involvement of the package maintainer.
+ git-buildpackage will learn about the version to pack from the debian/changelog file. If no .orig.tar.gz file is present, it will be recreated from the upstream branch. Once this was done, the remainder works as with dpkg-buildpackage, with no further involvement of the package maintainer.
- The annoying thing with git- or dpkg-buildpackage is that those start the packaging from scratch since they call "fakeroot ./debian/rules clean" by default. If that is not desired then consider calling "fakeroot ./debian/rules binary", instead. It may also help to add the "-nc" (no clean) option to the *-buildpackage tools. Once the packages are brought to pristine shape, then run git-buildpackage again for a clean picture.
+ The annoying thing with git- or dpkg-buildpackage is that those start the packaging from scratch since they call "fakeroot ./debian/rules clean" by default. If that is not desired then consider calling "fakeroot ./debian/rules binary", instead. It may also help to add the "-nc" (no clean) option to the *-buildpackage tools. Once the packages are brought to pristine shape, i.e. the packaging works reliably, run git-buildpackage again to be certain everything is prepared properly.
=== Variants for the invocation of git buildpackage ===
+ The following saves the generation of the orig.tar.gz from upstream. But this is not supported for the latest versions while this is written.
{{{
git buildpackage --git-pristine-tar
}}}
- or if you already have the {{{.orig.tar.gz}}} tarball in ''<path/to/tarballs/>'':
+ If the tarball is not in ".." but elsewhere, set it as in
{{{
git buildpackage --git-tarball-dir=<path/to/tarballs/>
}}}
+
<<Anchor(TrackingUpstream)>>
== Typical workflow in git development ==
@@ -244, +217 @@
git branch -d new_unique_branchname
}}}
- The local master branch is now "ahead of 1 commit" of the origin/master branch, i.e. the branch on the remote server
+ The local master branch is now "ahead of 1 commit" of the origin/master branch, i.e. the branch on the remote server that the master branch was cloned from.
- that the master branch was cloned from.
If the idea of yours that is represented by the branch would be generally applicable, then merge it from multiple branches, i.e. from debian/etch and debian/sarge, prior to deleting it.
@@ -317, +289 @@
export PS1="\[\033[01;37m\]${debian_chroot:+($debian_chroot)}\u@\h:\w\[\033[00;35m\]$(parse_git_branch)\[\033[00m\] \$"
}}}
+
== See Also ==
* [[Alioth/Git]] - Instructions on "Using Git on Alioth"
@@ -328, +301 @@
* [[http://www.kernel.org/pub/software/scm/git/docs/user-manual.html|Git User Manual]]
* [[http://www.gitready.com/|GitReady]] a community web site
+
+
+ = Removed from main text =
+
+ <<Anchor(RegeneratingTarballs)>>
+
+ === Regenerating upstream tarballs ===
+
+ ''If you are only interested in the latest version
+ that is in Debian, then you can easily skip this section. Just use the tool [[DebPkg:git-buildpackage]]
+ and the {{{orig.tar.gz}}} will be created from your
+ upstream branch.''
+
+ Upstream {{{.orig.tar.gz}}} tarballs can be regenerated with the {{{pristine-tar}}} tool directly from the repositories. To do so create a local {{{pristine-tar}}} branch from the remote {{{origin/pristine-tar}}} branch first:
+
+ {{{
+ git checkout -b pristine-tar origin/pristine-tar
+ }}}
+ As a clarification to those new to git, when cloning, the source of our clone is referred to as "origin". The "checkout" when given the "-b" option creates a new branch, which happens to have the same name as the branch on the remote git server. Normally, one would branch from the local master, i.e. one adds or changes a series of files relative to what is already available. The "origin/" prefix above informs git to branch from the remote side, i.e. a completely new environment is established that is independent from the previously checked out code:
+ {{{
+ $ ls
+ boinc_6.2.14.orig.tar.gz.delta boinc_6.2.18.orig.tar.gz.id boinc_6.6.10.orig.tar.gz.delta
+ boinc_6.2.14.orig.tar.gz.id boinc_6.4.5.orig.tar.gz.delta boinc_6.6.10.orig.tar.gz.id
+ boinc_6.2.18.orig.tar.gz.delta boinc_6.4.5.orig.tar.gz.id
+ }}}
+ All other files disappear.
+
+ The new branch is now listed next to the previously cloned master branch:
+ {{{
+ git branch
+ }}}
+ Now to regenerate for example the {{{boinc_6.2.18.orig.tar.gz}}} tarball from the {{{boinc}}} repository run:
+
+ {{{
+ pristine-tar checkout boinc_6.2.18.orig.tar.gz
+ }}}
+ This pristine-tar is some magic on its own. The idea is to share upstream's resources and have them nicely integrated with the git and git-buildpackage functionalities. See this link http://www.eyrie.org/~eagle/notes/debian/git.html for a nice summary on what is going on.
+
+ To find out which tarballs can be regenerated with the tool {{{pristine-tar}}}, check out what files there are in the branch with the same name:
+
+ {{{
+ git ls-tree pristine-tar
+ }}}
+
More information about the pkg-boinc-commits
mailing list