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.

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. 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 Software Center needs a few extra lines of information:

  • "XB-AppName:" is the full name of the app.

  • "XB-Icon:" is the filename of the app icon. (This must exactly match the icon filename added to the package meta-data in the debian/rules file.)

  • "XB-Screenshot-Url:" is the URL to a screenshot image. This is the screenshot image you upload with your review request, and the URL should be on https://software-center.ubuntu.com.

  • "XB-Category:" is one of the registered categories for desktop apps. For most ARB apps this is "Game", "Utility", or occasionally "Graphics".

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
XB-AppName: My App
XB-Icon: myapp.png
XB-Screenshot-Url: https://software-center.ubuntu.com/site_media/appmedia/2012/02/screenshot.jpg
XB-Category: Utility;
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 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. The name of the file added to the package meta-data must exactly match the "XB-Icon" filename in the debian/control file. 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 -

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 same list of registered categories for desktop apps as "XB-Category" in the debian/control file.

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.