Common Tasks

Table of Contents
Finding Historic Versions
Fetching Source from History
Building and Working With Source
Handling New Upstream Versions
Finalizing New Debian Versions

This chapter describes how to use tla-buildpackage to carry out regular, every-day development activities.


Finding Historic Versions

To find the versions available in your tla-buildpackage archive, first cd to its top level and then run:

$ ls configs/*/*
configs/debian/rdiff-backup:
0.12.3-1  0.12.5-1

configs/upstream/rdiff-backup:
0.12.3  0.12.5
      

This shows you that two Debian versions and two upstream versions of rdiff-backup are present.


Fetching Source from History

To fetch the source code from the tla-buildpackage archive, first cd into your top-level working copy. Then, using the name of the config file (see the Section called Finding Historic Versions), use the tla buildcfg command:

$ tla buildcfg debian/rdiff-backup/0.12.5-1
* from import revision: jgoerzen@complete.org--debian/rdiff-backup--head--1.0--base-0
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--head--1.0--patch-1
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--debian--1.0--base-0
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--debian--1.0--patch-1
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--debian--1.0--patch-2
* making pristine copy
* tree version set jgoerzen@complete.org--debian/rdiff-backup--debian--1.0
      

This command will have created the directory +packages/rdiff-backup/rdiff-backup-0.12.5 to contain the sources. Generating upstream sources works the same, and puts them into a directory ending in .orig.

If you don't know what version you want but just want the latest, you can simply use a command such as tla buildcfg debian/rdiff-backup/latest.


Building and Working With Source

Before you start working on any source package with tla-buildpackage, first check it out as described in the Section called Fetching Source from History to make sure it is in its proper location. Then, as you work, you will use tla commit to commit your changes to the Debian repository. (If you just want to build an old package, there's no need to do this.)

When you're ready to build a package, just run tla-buildpackage to build it. The tla-buildpackage command takes the same arguments as debuild, and passes them on to debuild, so give it your usual set. tla-buildpackage will use your existing orig.tar.gz file for source generation, if it exists; otherwise, it will take care of automatically building it from the upstream sources if necessary.

Here's an example:

~/tree/debian$ cd +packages/rdiff-backup/rdiff-backup-0.12.5
~/tree/debian/+packages/rdiff-backup/rdiff-backup-0.12.5$ tla-buildpackage \
        -rfakeroot -us -uc
...
Building .orig from archive.
 * tla buildcfg upstream/rdiff-backup/0.12.5
* from import revision: jgoerzen@complete.org--debian/rdiff-backup--head--1.0--base-0
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--head--1.0--patch-1
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--head--1.0--patch-2
* making pristine copy
* tree version set jgoerzen@complete.org--debian/rdiff-backup--head--1.0
 * tla inventory -s "rdiff-backup-0.12.5.orig" | tar -cSpf - -T- | gzip -9 > "rdiff-backup_0.12.5.orig.tar.gz"
 *** Running build program
Running:  debuild ['-i\\+\\+pristine-trees|,,*|\\{arch\\}|\\.arch-ids', '-rfakeroot', '-us', '-uc']
...
      

In this case, I had not checked out the upstream source and did not have my orig.tar.gz file handy. Therefore, tla-buildpackage checked out the upstream sources for me, generated the tar.gz file, and then called debuild to do the rest.

If you are building for Debian, you will want to keep your orig.tar.gz around so that future source uploads use the same MD5 sum in the .dsc file.

For more details, please see the manpage for tla-buildpackage(1).


Handling New Upstream Versions

A common scenario for a Debian developer to deal with is that of a new upstream release. The Debian patches from the most recent Debian release must be merged into the upstream one.

There have been a few tools to do that: uupdate is one. However, now that you are using Arch, you can use its built-in commands to make this easier: update and replay.

The first thing that you will do is to import the new upstream sources into your tla-buildpackage archive. Please see the Section called Importing Upstream Sources in the Chapter called Importing Packages for instructions.

Next, check out the latest Debian version if you don't already have it (see the Section called Fetching Source from History) and then cd into the Debian source directory.

[ Note: I anticipate writing a program to automate the following steps. ]


Merging In Upstream

Now, you are ready to merge in the new upstream. Run ONE of tla replay or tla update.

The difference between the two is how they apply changes. tla replay will apply the upstream changes atop your Debian tree by first essentially applying patches made by diffing the upstream version onto your tree. tla update, on the other hand, will revert all your Debian changes, copy over the upstream version, and then re-apply your Debian changes. This is usually the best option, but in tla 1.0, tla replay is easier. The difference between the two only matters if there are conflicts; otherwise, the end result is identical.


Using tla replay

$ tla replay --new --in-place . rdiff-backup--head--1.0
          

Just replace rdiff-backup with the name of your package. This command will automatically merge all the changes from the upstream into your Debian tree.


Using tla update

$ tla update --in-place . rdiff-backup--head--1.0
* setting aside local changes temporarily
what-changed: no local copies to compare to (jgoerzen@complete.org--debian/rdiff-backup--head--1.0--patch-2)
  consider `add-prisitine --help'
* linting the source tree
$ tla add-pristine rdiff-backup--head--1.0--patch-2
...
$ tla update --in-place . rdiff-backup--head--1.0
          

First, you run tla update. If you are missing any pristine versions, you have to run add-pristine, using the version the first command gave you, and then run tla update again.


Examining the Merge

Now, you will want to examine the merge, especially of tla complained of any conflicts.

You'll also want to note the new version in debian/changelog and rename your directory based on the new version. I find it easy to run a command like debchange -v 0.13.3-1, then modify the changelog as appropriate. debchange will handle the rename for you.


Committing the Merge

Finally, you will want to commit the merge. If you want to just use a simple log message, a command like this will work:

$ tla commit -L "Merged in upstream 0.13.3"
...
* commited jgoerzen@complete.org--debian/rdiff-backup--debian--1.0--patch-3
        

The string supplied after the -L is the log message.

If you want to add a more detailed log, try this:

$ LOG=`tla make-log`
$ tla log-for-merge >> $LOG
$ emacs $LOG
$ tla commit
        

The log-for-merge will add information about the merge to the textual message for you. tla automatically records the information in its metadata; this just makes it nicer.

You can see what happened by using cat-log:

$ tla cat-log patch-3
...
New-patches: jgoerzen@complete.org--debian/rdiff-backup--debian--1.0--patch-3
    jgoerzen@complete.org--debian/rdiff-backup--head--1.0--patch-3
Removed-patches:

Merged in upstream 0.13.3

Patches applied:

 * jgoerzen@complete.org--debian/rdiff-backup--head--1.0--patch-3
   Import upstream rdiff-backup version 0.13.3
        

Slick -- it shows exactly which upstream patches you used.


Finalizing New Debian Versions

When you have uploaded a Debian package to the archive, you should ask tla-buildpackage to note this for you. That way, you can request this specific version later. Just run this:

$ tbp-markdeb
...
 *** Success: Noted Debian rdiff-backup version 0.13.3-1
 *** at jgoerzen@complete.org--debian/rdiff-backup--debian--1.0--patch-3
      

The reason for this is that you might make several commits during the course of hacking on a given Debian version. This command lets you note the final version, and to run it again, you must update the changelog.