Ubuntu Wiki

There are many ways to do packaging for Debian/Ubuntu. This guide provides one simple way to package new applications to meet the ARB guidelines. For more complete details on Debian/Ubuntu packaging, we suggest reading the Ubuntu Packaging Guide. Depending on what kind of app you're submitting, you may also want to read our tips for Makefiles, Python apps, or Unity Lenses.

Create the Package Files

The dh_make utility is a quick way to start up a new package. (If you don't have it installed yet, just run 'sudo apt-get install dh-make'.) Change into the top-level directory for your source code and run dh_make.

• The --native option makes this a simple package (no patches or tarball)
• The --packagename option specifies the package name and version
• The --copyright option specifies the license of your package (gpl2, gpl3, lgpl2, lgpl3, artistic, apache, bsd, or x11)

  cd myappdir
  dh_make --native --packagename=myapp_0.1 --copyright=gpl3 

When it asks for the "Type of package", choose 'i' (for "architecture independent") if your app is written in a language like Python, Perl, or Ruby that doesn't need to be compiled. Choose 's' (for "single binary") if your app is written in a language like C, C++, or Vala.

Review the summary it gives you, and then <Enter> to confirm.

Running dh_make will create a directory myappdir/debian, with a bunch of packaging files. Most of these files are just templates (named with .ex and .EX), which you won't need, so start by cleaning up unnecessary files with:

  cd debian
  rm *.ex *.EX README* docs

This will leave you with six files in the debian/ directory: changelog, compat, control, copyright, rules, and source/format.

Extra Tip

If dh_make has any trouble figuring out your name or email, set the DEBFULLNAME and DEBEMAIL environment variables:

  export DEBFULLNAME="My Name"
  export DEBEMAIL=myname@example.com

Edit the Package Files

The compat file will contain a single number "8", and doesn't need any changes. The source/format file will contain a simple string "3.0 (native)", and doesn't need any changes. The other files will need some small changes.

changelog file

Edit the changelog file.

• Change the release target from "unstable" to the current Ubuntu release "oneiric".
• Add the ARB version string "-0extras11.10.1" to the package version.

The finished file will look something like:

myapp (0.1-0extras11.10.1) oneiric; urgency=low

  * Initial Release.

 -- My Name <myname@example.com>  Sun, 01 Apr 2012 13:20:56 -0700

copyright file

Edit the copyright file.

• Change the "Format:" line to the current recommended format http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/.

• Change the "Source:" line to link to your source control repository (or delete the line if you don't have one).
• If you made all the code, you only need one "Files: *" line (where the "*" means "all files"). You can delete the line with "Files: debian/*" and the two lines after it (you're creating the debian/* files now, so you own them just like the rest of the app).
• Update the "Copyright:" line to your name, email, and the years the files have existed.

• Update the "License:" line for any licenses other than gpl2, gpl3, lgpl2, lgpl3, artistic, apache, bsd, or x11. You can use any license Identifier from the SPDX license list.

The finished file will look something like:

Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: myapp
Source: <https://code.launchpad.net/~myname/+junk/extras-myapp-oneiric>

Files: *
Copyright: 2011-2012 My Name <myemail@example.com>
License: GPL-3.0+

License: GPL-3.0+
 This program is free software...

control file

Edit the control file.

The finished file will look something like:

Source: myapp
Section: unknown
Priority: extra
Maintainer: My Name <myemail@example.com>
Build-Depends: debhelper (>= 8.0.0), some-other-package
Standards-Version: 3.9.2
Homepage: http://myapp.example.com


Package: myapp
Architecture: all
Depends: ${misc:Depends}, some-other-package
Description: Short description
 Longer description, giving some details about what this
 app is for, and why someone might want to download it.
 
 Don't forget to indent each line of the long description
 with a space.

rules file

Edit the rules file.

• The comment lines aren't necessary, you can delete them or leave them in.
• You must add a small piece to set up the app icon in the Software Center. (It's a bit ugly, but there's no other way to do it at the moment.) Define an override_dh_gencontrol target that copies your image icon outside the top-level directory (to "../myapp.png"), and then adds the icon to the package meta-data. It has to be a PNG icon, and not SVG or some other format.

• You may need to make a few small changes to tell your app to install in /opt. There are several ways to do this, so take a look at our install path tips for various build systems. Most ways of setting the install path involve adding a simple override_dh_auto_install target to pass extra options to dh_auto_install.

The finished file will look something like:

 #!/usr/bin/make -f

 %:
        dh $@

 override_dh_auto_install:
        dh_auto_install -- PREFIX=/opt/extras.ubuntu.com/myapp

 override_dh_gencontrol:
        dh_gencontrol
        cp icons/myapp-64x64.png ../myapp.png
        dpkg-distaddfile myapp.png raw-meta-data -

myapp.desktop file

Build the Package

Change back to the top-level directory for your app. Try building your package with the command 'debuild'. You may have to debug a few errors, and if you need any guidance along the way, feel free to ask us questions at app-review-board@lists.ubuntu.com.

Once you have the package build working with no errors, you can build a source package with 'debuild -S' and then upload it to your PPA.