Managing Debian packages with cme

Managing Debian package files with cme

Quick summary

cme provides a set of tools to help you maintain Debian package files.

To check your package files, run the following command in the package source directory:

cme check dpkg

If some warnings are still displayed, you can try this command to fix the warnings (but create a backup before as the automatic fixes may not be what you want):

cme fix dpkg

If you want an interactive way to edit or fix your files, run:

cme edit dpkg

You will get a GUI like:

These commands can be applied also to part of your files:

cme edit dpkg-control
cme check dpkg-copyright
cme check dpkg-patches
cme edit dpkg-patch my-patch

Bash completion is available for all commands and sub-commands.

Installation

Run:

sudo apt-get install cme libconfig-model-dpkg-perl libconfig-model-tkui-perl

GUI main structure

The tree on the left is a structured view of Debian package files where

• control represents debian/control file
• likewise, copyright represents the content of debian/copyright file
• patches represents the content of debian/patches directory
• compat shows the content of debian/compat

In the GUI, you can use the menu with:

• "File -> check" to check for errors
• "File -> wizard" to check for warnings (you may want to set the ''stop on warnings'' button)

Maintaining Debian control file

To view control Testsuite parameter from control file, open control then source and click on Testsuite. You will get a screen like:

The right part of the window is dedicated to view or edit the content of a tree element. The example above shows the Testsuite parameter which is empty.

The example below shows the view of Build-Depends field (which is a hash item in Config::Model words). The orange icon indicates a warning with the moarvm dependency.

Now let's check what going on with this moarvm parameter. After a right-click on the line of this parameter, you will see:

The text in orange give more details about the warning. This one can be fixed by clicking on "Apply 1 fixes" button or by editing the value in the widget above "Reset" and "Delete" buttons. The Store button checks and stores the edited value in the tree on the left side of the window (not yet in the Debian package files).

To add or remove a dependency, right-click on Build-Depends:

Then:

• to remove a dependency, select an entry and click on the eraser icon
• to add a dependency, type the package name in the entry under the row of buttons, and click on either insert item to append the new dependency
• you can also edit a dependency: select this dependency, edit it in the entry, and click on set selected

Maintaining patches

The header of patches can also be edited according to DEP-3 specification. Open the patches element and one of the patches. You will get something like:

Then right-click on Synopsis or Description to update the patch information.

You can document the upstream bug number by cut'n'paste: copy the URL in the cut buffer and middle click on Bug item. This step can be done several times to store several URLs.

You can use a similar trick to document Debian bug URL in Bug-Debian field (requires libconfig-model-perl >= 2.069)

Dep-3 also allows the syntax Bug-<vendor> to save a vendor specific URL. First right-click on the patch name. You will get something like:

Then enter Bug-Something in the entry below accept: /^Bug-.*/ and hit Return. A new line will show up below Bug:

Then, you can cut'n'paste the vendor bug URL on this new line.

Maintaining Debian copyright file

Debian copyright file can be maintained in a similar fashion:

Because of the checks done by cme, you cannot fill the license short_name in the Files entry before doing either:

• create the License in the global license section (highlighted above)
• fill the full_license text

To create a new global license, right-click on License, add a new license in the Item: field:

and then click on the green plus icon. If the license is well know (i.e. known by Software::License ;-) ), the license text will be filled automatically. Otherwise, you can cut-n-paste the license in the text item.

Maintenance with command lines

Check a file

If you're interested only in checking or updating debian copyright file (i.e. debian/copyright) for DEP-5 syntax, you can run:

cme check dpkg-copyright

Likewise, all the package files can be checked with:

cme check dpkg

Fix most warnings

Most of the warnings can be automatically fixed with:

cme fix dpkg

Once caveat though: cme imposes an ordering of fields which matches the order of Debian documentation (except for control file). The first time you use this command may result in a diff bigger than you expected. You can mitigate this problem by running first cme modify dpkg -save (with cme 1.008). This command re-orders the content of the files, but it may also fill-in default values or choke on errors in dpkg files.

Update a package

Warning: this part is still experimental. Always check the result.

When package is upgraded, you need also to update the content of the copyright file:

cme update dpkg-copyright

Currently, only debian/copyright file is modified during update. The command cme update dpkg will achieve the same result.

Update results can be improved by tweaking some files in debian directory. See Updating debian copyright file with cme.

Cme command line

cme can be used as a command line modify a value in Debian package file. For instance, this command adds a Comment field in debian/copyright:

cme modify dpkg-copyright 'Comment="Modified with cme"'

You can also append text to an existing field:

cme modify dpkg-copyright 'Comment.=" dpkg control"'

Or modify in place a field with a Perl substitution:

cme modify dpkg-copyright 'Comment=~s/control/copyright/'

If you don't like the above comment, you can also remove it:

cme modify dpkg-copyright 'Comment~'

In all cases, you can use the -verbose option to see what the modify command is doing to the files:

cme  modify dpkg-copyright 'Comment~' --verbose
command 'Comment~': Deleting leaf 'Comment'.

Changes applied to dpkg-copyright configuration:
- Comment deleted value: 'bson files uses headers from yajl which are not part of the [...]'

Other operations on simple parameters (aka "leaf" parameters) are possible. See leaf operation doc

More examples are documented in Config::Model::Dpkg man page.

Modification of items like Uploaders is slightly more complicated since this parameter is a list. Operation on a list are usually done using a numeric index but that's not very practical. Let's see other ways.

First example, let's add yourself to the list of uploaders. This is taken care of by the :.push() function. These 2 commands yield the same result:

cme modify dpkg-control "source Uploaders:.push($DEBEMAIL)"
cme modify dpkg "control source Uploaders:.push($DEBEMAIL)"

Note that operations on a list always begin with ":".

Removal is done with ":" operator and a pattern matching. In the example below, all uploader matching john are removed:

cme modify dpkg 'control source Uploaders:-~/john/i'

If you want to remove a guy named Ian, you'll have to be a little more specific to avoid removing all debian developers. The following command removes a specific value from a list:

cme modify dpkg-control 'source Uploaders:-="Ian Smith<iansmith@debian.org>"'

Add an uploader to a sorted list of Uploaders (yes, insort, with a 'o', not "insert" with a 'e'):

cme modify dpkg-control 'source Uploaders:.insort("John Doe<johndoe@foo.com>")'

The above command make sense only if the list is sorted. Let's sort the list of uploaders with either:

cme modify dpkg-control 'source Uploaders:@'
cme modify dpkg-control 'source Uploaders:.sort'

sort and insort commands can be combined:

cme modify dpkg-control 'source Uploaders:.sort Uploaders:.insort("John Doe<johndoe@foo.com>")'

Some other parameters like binary in control file are actually based on a hash. The binary package name is a key of this hash. Likewise the name of a patch if the key of "patches" hash. For instance, you can use one of these command to set up Debian bug number in a patch whose file is named fix-debci:

cme modify dpkg-patches 'patches:fix-debci Bug-Debian:="https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=785528"'
cme modify dpkg-patch fix-debci 'Bug-Debian:="https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=785528"'

Hash elements can also be removed. The following command will remove a binary package from control file:

cme modify dpkg-control 'binary:-libconfig-model-perl

For more systematic changes, the operator :~/<regexp>/ triggers a loop. The instructions after this operator are applied to all the element that matches the regexp. The following example can be handy next January to update copyright years for all Files entries in debian/copyright:

cme modify dpkg-copyright 'Files:~/./ Copyright=~"s/2015/2016/"'

One can be a little more subtle and apply a similar change to only debian files:

cme modify dpkg-copyright 'Files:~/^debian/ Copyright=~"s/2015/2016/"'

See also Config::Model::Dpkg man page on Debian.

The following examples sorts the dependency list in all binary packages. By default, cme saves a file only if the semantic content has changed. Sorting a list is not such a change, so the -save option must be used to force cme to save the file.

cme modify dpkg-control -save 'binary:~/.*/ Depends:.sort'

This example sorts all Files entries in the copyright file:

cme modify dpkg-copyright -save 'Files:.sort'

Fuse my files

For what it's worth, cme also provides a fuse interface. This may be useful if you want, for instance, to compare the content of a license text with the original license:

mkdir myfuse
cme fusefs dpkg-copyright -fuse-dir myfuse/
diff expat.txt myfuse/License/Expat/text

You can use your favourite editor to modify the license text:

emacs myfuse/License/Expat/text

To unmount the fuse file system (and save any changes), run:

fusermount -u myfuse

Reporting issues

In case of issues, enter a bug report. Depending of the kind of issue, several packages may be concerned:

• GUI: libconfig-model-tkui-perl BTS or upstream Config::Model::TkUI
• core issue: libconfig-model-perl BTS or upstream Config::Model
• Dpkg issues: libconfig-model-dpkg-perl BTS

In case of doubt where to log the bug, please use:

reportbug libconfig-model-dpkg-perl

How can you help ?

You can report issues or suggestions with github bug tracker

You can also improve the Dpkg functionality:

• install the software to modify Dpkg model:

  apt-get install libconfig-model-itself-perl
  

• clone Debian repository :

  git clone git://anonscm.debian.org/pkg-perl/packages/libconfig-model-dpkg-perl.git
  # or if you have an account on alioth:
  git clone ssh://git.debian.org/git/pkg-perl/packages/libconfig-model-dpkg-perl.git
  

• In the cloned repository:

  cme meta edit Dpkg
  

For more information on how to modify a model, please read:

• How to add a new parameter - OpenSsh example

For more information on what is a model:

• Introduction to model creation with Config::Model
• Element declaration in a node
• Value element properties

In case of issues, please:

• send a mail to debian-perl mailing list
• contact me on #perl channel on debian IRC.

Bugs

Formatting

cme imposes some formatting when saving files:

• lists are displayed one item per line and indented according to the field name
• fields are re-ordered according to the documentation (except for control file)

cme no longer imposes an ordering on the fields of the control file.

Comments

cme uses heuristic to attach comments to specific fields. It may get this wrong and attach comments to the wrong field. This may be confusing when fields are re-ordered.