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 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.

DEBFULLNAME and DEBEMAIL

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. You will also need to add a .desktop file.

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

• 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 <myname@example.com>
License: GPL-3.0+

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

control file

• Change the Section: to the short name of one of the sections in the list of sections. For most ARB apps this will be "games", "utils", or occasionally "graphics".

• Change the Homepage: to link to the app's web page (or delete the line if the app doesn't have a web page).

• List any Ubuntu packages needed to build your app on the Build-Depends: line.

• List any Ubuntu packages needed to run your app on the Depends: line.

• Add a short description on the Description: line, and a longer description on the few lines after the short description.

The finished file will look something like:

Source: myapp
Section: utils
Priority: extra
Maintainer: My Name <myname@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

• The comment lines aren't necessary, you can delete them or leave them in.

• 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

extras-myapp.desktop file

Add a file named extras-<appname>.desktop to the top-level directory of your app.

• Icon is the full path to your app icon to display in the Dash or Launcher.

• Exec is the full path to where you installed your app. This will run whenever your app icon is clicked in the Dash or Launcher.

• Categories is from the list of registered categories for desktop apps.

The finished file will look something like:

[Desktop Entry]
Version=0.1
Type=Application
Terminal=false
Exec=/opt/extras.ubuntu.com/myapp/bin/myapp
Icon=/opt/extras.ubuntu.com/myapp/icons/myapp.svg
Name=My App
Comment=Short description
Categories=Utility

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.