Thu, 10 Aug 2006

Working with svn-buildpackage

Start by creating a svn repository.  I'm presuming you'll be working from your
home directory --

    svnadmin create svn-repo 
    
... where svn-repo can be any name you want.

Note that this repository [svn-repo or whatever you name it] will be where 
svn manages all of its work.  It is not an area that you will edit.

Next, create a directory where you will do your work.   For me it was --

    mkdir debian-dev
    cd debian-dev

Download the appropriate files:  package.dsc, package.orig.tar.gz, and
package.diff.gz

Now we'll inject an existing source file into the repository --

    svn-inject bbtime_0.1.5-9.dsc file:///home/kevin/svn-repo

You'll see a lot of stuff scroll by, the last line of which should say
something like 

"Your working directory is /home/kevin/debian-dev/bbtime - have fun!"

The svn-inject command actually makes your working directory for you.

For most purposes you'll want to work out of the directory, although you can
create other working directories if you like with the command --

    svn co file:///home/kevin/svn-repo/bbtime

Wherever you execute this command is where the working directory will be
built.  When it is built, you'll see the following tree built:

    bbtime
      |----- branches
      |----- tags
      |----- trunk

You'll want to descend into trunk, where you'll see all of the source files
and a debian/ directory with all of the rules/control files.  Later, when you
execute the svn-buildpackage command, you'll want to do so from this trunk
directory. 

Return back to /home/kevin/debian-dev (or your equivalent).  Make a directory
in here as follows --

    mkdir tarballs
    
... so you should now have:

    home/kevin/debian-dev
        |------------------- bbtime
        |------------------- tarballs

Into the tarballs directory copy the original source tarballs, which should
have a name like bbtime_0.1.5.orig.tar.gz.  You should have been able to
download a copy of this file from the same place you downloaded the .dsc file
(most likely the Package area on Debian.org).

At this point you are ready to do some work.   Remember that svn-inject did
the original checking out of the bbtime working files for you, so you can
simply go to them and start your editing --

    cd /home/kevin/debian-dev/bbtime

... and do your work, most of which will probably be in the debian/ directory.

Once you've done your editing, you'll need to execute various svn commands,
all of which should be executed from the working directory, which is
/home/kevin/debian-dev/bbtime.  Examples of some of these commands:

    svn add debian/newfile
    svn delete debian/oldfile
    svn status
    svn log
    svn diff
    svn commit

This last command - svn commit - must be executed before you can do any
building.  As you execute it, you'll be given a chance to write notes about
the changes you made.

The next step is the actual building.  The command is --

    svn-buildpackage -k8CE11941 -rfakeroot

where -k is your GnuPG key ID and -r sets up fakeroot, which you should have
installed.  

You'll see plenty of screen action, which should end with a few lines that
tell you where everything was built.  If you move up a level in the directory,
you'll now find a new sub-directory called build-area.  This is where all of
the built files are put.  So you should now have a tree like this:

    home/kevin/debian-dev
        |------------------- bbtime
        |--------------------build-area
        |------------------- tarballs

In the build-area you'll find all of your newly generated files:

    bbtime_0.8.3-3.diff.gz
    bbtime_0.8.3-3.dsc
    bbtime_0.8.3-3_i386.changes
    bbtime_0.8.3-3_i386.deb
    bbtime_0.8.3.orig.tar.gz

Obviously you'll want to test everything, including running lintian and linda.

You'll probably want to build a few times as you work out your bugs.  Each
time you change something in bbtime/debian, you'll have to svn commit it to
the repository before you can execute svn-buildpackage again.  And each time
you build, svn-buildpackage will automatically overwrite the files in the
build-area directory, so don't worrying about cleaning that out.

When you are finally happy with your results, you need to tag it as a final
build.  You can do this with one of two commands --

    svn-buildpackage -k8CE11941 -rfakeroot --svn-tag
    or
    svn-buildpackage -k8CE11941 -rfakeroot --svn-tag-only

The first command will build the package and tag it, while the latter command
will just tag it (presumes your earlier builds were satisfactory).

When you tag it, you'll also be making a new debian/changelog entry, which
essentially is preparation for the next time you rebuild the package and
release a new version.

At this point you are basically done.  Make sure you don't delete the working
copy of your package that you have in /home/kevin/debian-dev.  Leave it there
for future versions. 

Before ending this, here's a couple more things to think about that may hang
you up.

First, let's say you've just finished building, are happy with the package,
and you've tagged it, which puts a copy into the repository trunk.  You
send it to your upload sponsor, but he spots a bug and wants you to correct
it.  But you've already finalized and tagged your build.  No problem.  Go to
your working copy - /home/kevin/debian-dev/bbtime - and execute the command --

    svn update

This will refresh your working copy from the repository.  It probably already
is the latest copy, but just in case, update it anyway.  Next go into
debian/changelog and remove the next version entry that the tagging process
created for you.  Make any other bug corrections.  And then execute your svn
commit and then you can build again and eventually tag it.  Your versioning
will still be preserved.

The second hang up that may get you is if you checkout a copy of a package
into a different working area.  Say for instance that you are in /tmp and you
execute --

    svn co file:///home/kevin/svn-repo/bbtime

This will create the following tree for you:

    /tmp/bbtime
        |------- branches
        |------- tags
        |------- trunk

You can descend into trunk, where you'll find all the source files and the
debian/ directory.  You can do all the editing you need and commit all of the
changes back to the repository.  And you can even build a deb by executing the
svn-buildpackage command from the trunk/ directory.  It will create a
build-area directory for like this:

    /tmp/bbtime
        |------- branches
        |------- build-area
        |------- tags
        |------- trunk

... and in this build-area directory you'll find the results of your build.
What you won't find is a .diff.gz file.  That file is only generated if you
are working from the originally created working directory from when you
executed svn-inject.

If you, or someone else, works on a copy of the package checked out from the
repository to a working area not in the original /home/kevin/debian-dev and
commits changes, then make sure next time you work in the original work area -
/home/kevin/debian-dev/bbtime - that you execute svn update to incorporate
their changes into your working copy.   This is basic svn stuff but may be
helpful to those new to all of this.

Good luck!

Posted at: 21:27 | category: /dev | Comments ()