Packaging

(Prerequisites)
(Autotools)
 
(50 intermediate revisions not shown)
Line 1: Line 1:
-
= Creating Packages for Maemo =
+
== Creating Packages for Maemo ==
Since Maemo is based on the Debian operating system, creating packages for Maemo borrows a lot of tools and techniques from Debian.
Since Maemo is based on the Debian operating system, creating packages for Maemo borrows a lot of tools and techniques from Debian.
-
== Further reading ==
+
=== Further reading ===
The following list of resources gives in-depth information on packaging in Debian and Maemo. These links largely discuss packaging Python apps but can be used for any programming language.  
The following list of resources gives in-depth information on packaging in Debian and Maemo. These links largely discuss packaging Python apps but can be used for any programming language.  
 +
*  [http://www.openismus.com/documents/linux/automake/automake Using automake and autoconf with C++]: A great beginner's tutorial on using autotools to create an easily packagable application
*  [http://www.debian.org/doc/maint-guide/ Debian New Maintainers Guide]: The best place for information if you have never built a .deb before
*  [http://www.debian.org/doc/maint-guide/ Debian New Maintainers Guide]: The best place for information if you have never built a .deb before
*  [http://wiki.debian.org/Teams/PythonModulesTeam Debian's Python Modules Team]: definitive documentation for packaging Python modules for Debian
*  [http://wiki.debian.org/Teams/PythonModulesTeam Debian's Python Modules Team]: definitive documentation for packaging Python modules for Debian
Line 14: Line 15:
* [[Documentation/Maemo 5 Developer Guide/Packaging, Deploying and Distributing | Deploying and distributing software on Maemo 5]]: Detailed documentation on packaging for Maemo, including how to ship your software afterwards
* [[Documentation/Maemo 5 Developer Guide/Packaging, Deploying and Distributing | Deploying and distributing software on Maemo 5]]: Detailed documentation on packaging for Maemo, including how to ship your software afterwards
* [http://www.forum.nokia.com/Tools_Docs_and_Code/Documentation/Maemo.xhtml Forum Nokia developer documentation]: General developer documentation reference
* [http://www.forum.nokia.com/Tools_Docs_and_Code/Documentation/Maemo.xhtml Forum Nokia developer documentation]: General developer documentation reference
 +
* [[Port an existing Debian package]]
* [[Packaging a Qt application]] and how it differs from the packaging described here
* [[Packaging a Qt application]] and how it differs from the packaging described here
* [[User:Jebba]] has created a [[User:Jebba/Package Building HOWTO | package building howto]] with details on every step
* [[User:Jebba]] has created a [[User:Jebba/Package Building HOWTO | package building howto]] with details on every step
-
=== Checking Maemo Packages ===
+
==== Checking Maemo Packages ====
 +
 
Lintian dissects Debian packages and reports bugs and policy violations.  
Lintian dissects Debian packages and reports bugs and policy violations.  
It contains automated checks for many aspects of Debian policy as well as some checks for common errors. Unfortunately it does not check conformance to the additional Maemo policy.
It contains automated checks for many aspects of Debian policy as well as some checks for common errors. Unfortunately it does not check conformance to the additional Maemo policy.
Line 23: Line 26:
Currently Maemo is creating [[Maemian]] to check its policy.
Currently Maemo is creating [[Maemian]] to check its policy.
-
= A concrete example - rot13 =
+
== A concrete example - hello ==
-
== Prerequisites ==
+
-
For the purposes of our article, we will be packaging a simple command-line utility called "rot13", which will perform a simple [http://en.wikipedia.org/wiki/ROT13 rot13] cipher on all text input from stdin. This will be a standard source tarball using autotools.
+
=== Prerequisites ===
-
=== rot13.c ===
+
For the purposes of our article, we will be packaging a simple [[Hildon]] hello-world application. This will be a standard source tarball using [[Documentation/Maemo 5 Developer Guide/GNU Build System#GNU Autotools|autotools]]. For further information, you can follow [http://www.openismus.com/documents/linux/automake/automake this detailed tutorial] on using Autotools for C++ projects.
-
The only C file in our project is rot13.c:
+
You will need a working [[Documentation/Maemo 5 Final SDK Installation|Maemo 5 SDK]] and the <code>libhildon1-dev</code> package, version 2.2 or greater, which can be installed in Scratchbox with the command:
 +
 
 +
fakeroot apt-get install libhildon1-dev
 +
 
 +
==== hello.c ====
 +
 
 +
The only C file in our project is <code>hello.c</code>:
<source lang="c">
<source lang="c">
-
#include <stdio.h>
+
#include <hildon/hildon.h>
-
int main(void)
+
int main(int argc, char *argv[])
{
{
-
   int a;
+
   GtkWidget *window;
-
   /* If we have a command line, rot13 it. Otherwise, read stdin & rot13 it */
+
   GtkWidget *label;
-
   while ((a = getchar()) != -1)
+
   hildon_gtk_init(&argc, &argv);
-
  {
+
-
    if ((a >= 'A' && a <= 'M') || (a >= 'a' && a <= 'm'))
+
-
      putchar(a+13);
+
-
    else if ((a >= 'N' && a <= 'Z') || (a >= 'n' && a <= 'z'))
+
-
      putchar (a-13);
+
-
    else
+
-
      putchar (a);
+
-
  }
+
 +
  window = hildon_window_new();
 +
  label = gtk_label_new("Hello world!");
 +
 +
  g_signal_connect(G_OBJECT (window), "destroy", G_CALLBACK (gtk_widget_destroy), NULL);
 +
  gtk_container_add(GTK_CONTAINER(window), label);
 +
  gtk_widget_show_all(window);
 +
 +
  gtk_main();
   return 0;
   return 0;
}
}
</source>
</source>
-
To allow us to concentrate on the packaging, we dropped any input error checking, command line options or anything else.
+
==== Autotools ====
-
 
+
-
=== Autotools ===
+
{{main|Documentation/Maemo 5 Developer Guide/GNU Build System}}
{{main|Documentation/Maemo 5 Developer Guide/GNU Build System}}
-
The rest of the project is a small number of files to allow us to make a standard "./configure && make && make install" project with automake, aclocal and autoconf.
+
The rest of the project is a small number of files to allow us to make a standard "<code>./configure && make && make install</code>" project with automake, aclocal and autoconf.
Using the autotools for packaging is quite simple for small projects. You need two files to define the structure of your project, <code>Makefile.am</code> and <code>configure.ac</code>.
Using the autotools for packaging is quite simple for small projects. You need two files to define the structure of your project, <code>Makefile.am</code> and <code>configure.ac</code>.
-
<code>Makefile.am</code> defines the source structure of your project, listing the files to be installed, the binaries and object files to be generated, and the relationship between the binaries and source files.
+
<code>configure.ac</code> is a file used by automake and autoconf to generate the configure script, define the version of the resulting .tar.gz and include the tests which we need to ensure the presence of the appropriate versions of dependencies. Since <code>hello.c</code> is so simple, we only need to check for the standard C library and a C compiler, and for the Hildon library. The Hildon library check is done by <code>pkg-config</code>, which makes it easy to check the library version, and get the right compiler and linker flags. The only output file generated by the configure script will be <code>Makefile</code>, from the input file <code>Makefile.in</code>, which is in turn generated from <code>Makefile.am</code>
-
You can see that our <code>Makefile.am</code> is very simple, defining one source file, and one binary file. The "_SOURCES" line must start with a binary name from "bin_PROGRAMS" to make the link between the source file and the executable.
+
<source lang="text">
-
 
+
AC_INIT([hello], [0.1])
-
bin_PROGRAMS = rot13
+
AM_INIT_AUTOMAKE([foreign])
-
rot13_SOURCES = rot13.c
+
AC_PROG_CC
 +
PKG_CHECK_MODULES([HILDON], [hildon-1 >= 2.2])
 +
AC_CONFIG_FILES([Makefile])
 +
AC_OUTPUT
 +
</source>
 +
<code>Makefile.am</code> defines the source structure of your project, listing the files to be installed, the binaries and object files to be generated, and the relationship between the binaries and source files.
-
<code>configure.ac</code> is a file used by automake and autoconf to generate the configure script, define the version of the resulting .tar.gz and include the tests which we need to ensure the presence of the appropriate versions of dependencies. Since <code>rot13.c</code> is so simple, we do not need anything except the standard C library and a C compiler. The only output file generated by the configure script will be <code>Makefile</code>, from the input file <code>Makefile.in</code>, which is in turn generated from <code>Makefile.am</code>
+
You can see that our <code>Makefile.am</code> is very simple, defining one source file, and one binary file. The "_SOURCES" line must start with a binary name from "bin_PROGRAMS" to make the link between the source file and the executable. The "_CPPFLAGS" and "_LDADD" lines take the Hildon preprocessor and library flags that are provided by <code>pkg-config</code> in <code>configure.ac</code>.
-
  AC_INIT([rot13.c], [0.1])
+
  bin_PROGRAMS = hello
-
  AM_INIT_AUTOMAKE([foreign])
+
hello_SOURCES = hello.c
-
  AC_PROG_CC
+
  hello_CPPFLAGS = $(HILDON_CFLAGS)
-
AC_PROG_INSTALL
+
  hello_LDADD = $(HILDON_LIBS)
-
AC_OUTPUT([Makefile])
+
Once we have these files, we simply need to initialise our project, defining its license, and generating all of the required files for automake to do its thing. We do this by running:
Once we have these files, we simply need to initialise our project, defining its license, and generating all of the required files for automake to do its thing. We do this by running:
Line 98: Line 108:
  make dist
  make dist
-
which will create a file ''rot13-0.1.tar.gz'', which you can use for the rest of this packaging tutorial.
+
which will create a file ''<code>hello-0.1.tar.gz</code>'', which you can use for the rest of this packaging tutorial.
-
== Packaging a .deb ==
+
=== Packaging a .deb ===
The easiest way to package a .deb file is to use Debian's build helpers.
The easiest way to package a .deb file is to use Debian's build helpers.
-
Package your application as you would distribute it in a .tar.gz (when using autotools, this is done with "make distcheck"). In our example, we uncompress rot13-0.1.tar.gz, and change the current directory to rot13-0.1.
+
Package your application as you would distribute it in a .tar.gz (when using autotools, this is done with "<code>make distcheck</code>"). In our example, we uncompress <code>hello-0.1.tar.gz</code>, and change the current directory to <code>hello-0.1</code>.
-
  $ tar xfz rot13-0.1.tar.gz
+
  $ tar xfz hello-0.1.tar.gz
-
  $ cd rot13-0.1
+
  $ cd hello-0.1
-
Then we run dh_make, which initialises the Debian package management file structure (among other things):
+
Then we run <code>dh_make</code>, which initialises the Debian package management file structure (among other things):
-
  $ dh_make -e <my email address> -f ../rot13-0.1.tar.gz -c GPL
+
  $ dh_make -e <my email address> -f ../hello-0.1.tar.gz -c GPL
You can of course choose a different licence for your package.
You can of course choose a different licence for your package.
Line 118: Line 128:
We can now edit the files in the <code>debian/</code> directory which has been created to their desired values, before packaging the software. In fact, we can delete many of these files. All of the files ending in “.ex” or “.EX” are example files, intended to help you package different types of software.
We can now edit the files in the <code>debian/</code> directory which has been created to their desired values, before packaging the software. In fact, we can delete many of these files. All of the files ending in “.ex” or “.EX” are example files, intended to help you package different types of software.
-
If you use a standard configure script, you do not need to modify any files in here at all.
+
If you use a standard configure script, you do not need to modify any files except <code>debian/control</code>, where the Hildon build-time dependency should be added. Change the <code>Build-Depends</code> line to read (by adding "<code>libhildon1</code>" at the end):
 +
 
 +
Build-Depends: debhelper (>= 5), autotools-dev, libhildon1 (>= 2.2)
Before creating a .deb, you should set a changelog entry. .deb changelogs follow a special format, so rather than editing the files by hand, use the dch helper application. This will allow you to add what new features went into this application, give credit, and so on. It is an especially important file because it sets the version and revision of the source and binary packages. On saving, a syntax check is performed which ensures that the resulting file is OK. The file format is completely documented in the [http://www.debian.org/doc/maint-guide/ Debian packaging guide].
Before creating a .deb, you should set a changelog entry. .deb changelogs follow a special format, so rather than editing the files by hand, use the dch helper application. This will allow you to add what new features went into this application, give credit, and so on. It is an especially important file because it sets the version and revision of the source and binary packages. On saving, a syntax check is performed which ensures that the resulting file is OK. The file format is completely documented in the [http://www.debian.org/doc/maint-guide/ Debian packaging guide].
Line 127: Line 139:
You should now have several files created in the parent directory to where you unpacked the source code. I have;
You should now have several files created in the parent directory to where you unpacked the source code. I have;
-
  rot13_0.1.orig.tar.gz
+
  hello_0.1.orig.tar.gz
-
  rot13_0.1-1_i386.deb
+
  hello_0.1-1_i386.deb
-
  rot13_0.1-1.diff.gz
+
  hello_0.1-1.diff.gz
-
  rot13_0.1-1.dsc
+
  hello_0.1-1.dsc
-
  rot13_0.1-1_i386.changes
+
  hello_0.1-1_i386.changes
-
Now change the target architecture to ARMEL and rebuild it, to generate rot13_0.1-1_arm.deb
+
Now change the target architecture to <code>ARMEL</code> and rebuild it, to generate <code>hello_0.1-1_arm.deb</code>:
-
=== Additional information ===
+
sb-conf se FREMANTLE_ARMEL
 +
dpkg-buildpackage -sa -rfakeroot -k<my email address>
 +
 
 +
==== Additional information ====
 +
 
 +
===== Ignoring git metadata =====
If you use git then you may not want to include the entire git repo in your source bundle. With dpkg-source version 1.13.25 the -i option is not git-aware so you can do:
If you use git then you may not want to include the entire git repo in your source bundle. With dpkg-source version 1.13.25 the -i option is not git-aware so you can do:
Line 141: Line 158:
   dpkg-buildpackage -rfakeroot -sa  -i -I.git
   dpkg-buildpackage -rfakeroot -sa  -i -I.git
-
You may verify that your <code>Build-Depends</code> field in debian/control is complete by running:
+
===== Adding build-time dependencies =====
-
dpkg-depcheck -m dpkg-buildpackage -rfakeroot -b
+
If your program uses another library, such as Hildon in the above example, then both the Debian package and the configure script must depend on the library.
 +
Otherwise, since the autobuilder only installs packages explicitly required to build your package, the build will fail.
-
in the source tree. (You will need to <code>fakeroot apt-get install devscripts</code> for this to work).
+
Often, the Debian package has a different name to the pkg-config file, just like in the Hildon example. One way to check which package owns a pkg-config file is to use <code>dpkg-query</code> on the pkg-config file, for example the <code>mafw</code> pkg-config file (notice the extra <code>.pc</code> file extension):
 +
dpkg-query --search mafw.pc
 +
which looks through the installed packages and finds:
 +
libmafw0-dev: /usr/lib/pkgconfig/mafw.pc
 +
Then you know that you must add <code>libmafw0-dev</code> to the <code>Build-Depends</code> line in <code>debian/control</code> if you use the <code>mafw</code> pkg-config file in <code>configure.ac</code>.
-
== Uploading to extras-devel ==
+
===== Checking build-time dependencies =====
-
{{main|Uploading to Extras-devel}}
+
You may verify that your <code>Build-Depends</code> field in debian/control is complete by running:
-
= Porting an existing Debian package =
+
dpkg-depcheck -m dpkg-buildpackage -rfakeroot -b
-
== Finding your package in Debian ==
+
in the source tree. (You will need to <code>fakeroot apt-get install devscripts</code> for this to work).
-
If you want to port a Debian package to Maemo, you should check and see if it is already packaged for Debian and use that package if you can - this will save you time and effort. You can search in Debian's [http://www.debian.org/distrib/packages Package Tracking System (PTS)] to see if it is there. There is a search system on the PTS page, under the "distribution" drop-down, select 'any', this will search throughout Debian's repositories to find the package. Debian has more than 20,000 packages just in its stable distribution so your application is likely already packaged.
+
=== Adding an icon and desktop file ===
-
If you find the package already exists in Debian, you can get the source, including the packaging source, with apt-get. To do this, you'll have to edit your /etc/apt/sources.list, you can follow this recipe;
+
To ensure that your package shows up in the application menu, you will need to install an icon and a .desktop file with your package.
 +
The icon can be in a number of formats. To keep things simple, you can use [[:Image:Hello.png | this 48x48 .png]] as your icon for now.
-
$ echo "deb http://ftp.it.debian.org/debian/ unstable main contrib non-free" >> /etc/apt/sources.list
+
The format of .desktop files is specified by the [http://standards.freedesktop.org/desktop-entry-spec/1.0/ freedesktop.org desktop entry spec], with a number of [[Desktop file format | Maemo specific extensions]]. The simplest possible .desktop file for Maemo contains a "Desktop Entry" group containing an indicator that it refers to an application, the application name, the icon to use, and a path to the executable which will launch the application. Other standard keys can be found [http://standards.freedesktop.org/desktop-entry-spec/1.0/ar01s05.html in the spec].
-
$ echo "deb-src http://ftp.it.debian.org/debian/ unstable main contrib non-free" >> /etc/apt/sources.list
+
-
$ apt-get update
+
-
$ apt-cache search "application name"
+
-
$ apt-get source "application name"
+
 +
<pre>
 +
[Desktop Entry]
 +
Type=Application
 +
Name=Hello!
 +
Icon=hello
 +
Exec=/usr/bin/hello
 +
</pre>
-
''To learn more about the <code>/etc/apt/sources.list</code> you can do a 'man sources.list' if you are running Debian or a Debian-based GNU/Linux distro.''
+
Pixmaps referenced without an absolute path in the desktop file can be installed in a number of locations, specified in the [http://freedesktop.org/wiki/Specifications/icon-theme-spec freedesktop.org icon theme spec]. The simplest place to put the icon is in <code>/usr/share/icons</code>. The Icon entry above will thus match <code>/usr/share/icons/hello.png</code>.
-
== Modifying a Debian package for Maemo ==
+
Once you have created these files in your source directory, you will need to add the following to <code>Makefile.am</code> to ensure that they are distributed in the tarball (created during <code>make dist</code>) installed in the right place, and packaged correctly, and you should re-run <code>autoreconf</code>, <code>configure</code>, <code>make dist</code> and <code>dpkg_buildpackage</code> once you have done so.
-
Once you have the source of the Debian package, you will need to make some modifications to that package for it to build under Maemo. See the [[#Packaging_policy|Maemo packaging policy]] for more information.
+
<source lang="make">
 +
icondir = $(datadir)/icons
 +
dist_icon_DATA = hello.png
-
The maintainer field (in the <code>debian/control</code> file) must be changed if the upstream package is modified, for example:
+
desktopdir = $(datadir)/applications/hildon
-
Maintainer: Tcl/Tk Debian Packagers <pkg-tcltk-devel@lists.alioth.debian.org>
+
dist_desktop_DATA = hello.desktop
-
should be replaced by
+
</source>
-
Maintainer: My Name <my@email.com>
+
-
XSBC-Original-Maintainer: Tcl/Tk Debian Packagers <pkg-tcltk-devel@lists.alioth.debian.org>
+
-
You must add a new entry to <code>debian/changelog</code> and append <code>maemo1</code> to the version, for example:
+
To make the package installable using Hildon Application Manager (which will get launched when you select the package), you should follow the [[#Maemo-specific packaging information]] below. In particular, you must set the "Section" to one of the valid sections below in the "<code>debian/control</code>" file.
-
tk8.5 (8.5.8-1) unstable; urgency=low
+
-
becomes:
+
-
tk8.5 (8.5.8-1maemo1) fremantle; urgency=low
+
-
This indicates that there have been Maemo-specific changes to the packaging. If you upload new changes, you must add a new changelog entry and increment the version number, for example <code>maemo2</code>).
+
-
The "Debian way" is to keep all modifications to the package in the <code>package.version.diff.gz</code> file and to leave the <code>.orig.tar.gz</code> file untouched. There are several ways to apply patches with Debian packaging, and some are described in the [http://www.debian.org/doc/maint-guide/ch-build.en.html#s-dpatch patching section of the New Maintainer's Guide]
+
=== Testing your package ===
-
However, the <code>.diff.gz</code> cannot store binary files like icons. A possible workaround is to uuencode the binary file, for example (in <code>debian/</code>):
+
The first place you can test your app is in Scratchbox. Start Xephyr and the Maemo GUI as described in [[Documentation/Maemo 5 Final SDK Installation | the Maemo 5 SDK instructions]], then run your application by hand from within Scratchbox.
-
uuencode -m icon.png icon.png  > icon.png.b64
+
-
and in the rules file decode the file to debian/icon.png before installation
+
-
uudecode debian/icon.png.b64
+
-
For this solution you have to add <code>sharutils</code> to the <code>Build-Depends</code>.
+
-
If the package should be visible in the Application Manager, the Section field should begin with <code>user/</code>, with the [[#Sections|valid sections listed below]]. You should also add and install a <code>.desktop</code> file for starting the application, if one does not already exist.
+
Once you have created .deb packages of your application for x86 and armel, you can also test the installation process and test your application on your N900.
-
== Differences between Debian/Ubuntu and Maemo ==
+
To test the installation on Xephyr, you can either install it from the command line with <pre>dpkg -i hello_0.1-1_i386.deb</pre>, or copy the i386 .deb files to the <pre>/home/<username>/MyDocs</pre> directory, and click on it to install it.
-
The are a couple of important differences between a Debian system and Maemo:
+
To test on your device, copy the armel .deb file to the .documents directory on your device, and install it by selecting it in the file manager. You will need to ensure that the OS version on your device is compatible with the development environment in your Scratchbox.
-
* '''Busybox''':<br/>Maemo uses busybox to replace most of bsdutils, coreutils, findutils and bash, therefore most of the extended options for the commands and shell are not available. Check the postinstall and other package scripts for such options and try to replace or emulate them.
+
Once the package is installed, you will be able to launch it directly from the command line in the [[terminal|X terminal]] application. To get the application to appear in the application list, you will need to include an icon and desktop file in the package as described in [[/Guidelines | the packaging policy]].
-
* Outdated '''build and configuration tools''':<br/>the SDK and autobuilder provide only outdated versions of gcc, dpkg, debhelper, cdbs, debconf, ucf and other build tools. Try to replace the <code>Build-Depends</code> in the <code>debian/control</code> file with older versions or use backports like [[#Debhelper_7|debhelper7]]
+
=== Uploading to extras-devel ===
-
* Directories for '''temporary files''':<br/><code>/tmp</code> is only 900 kB and should only be used for very small temporary files. <code>/var/tmp</code> on the NAND is larger. A new temporary directory in <code>/home/user/</code> could be even larger. Replace constructs like <code>${TMP-/tmp}</code> in shell scripts with <code>${TMP-/var/tmp}</code> (the same applies to <code>mktemp -p /tmp</code>).
+
{{main|Uploading to Extras-devel}}
-
* '''Optification''' may confuse programs:<br/>some programs try to find their data files relative to the binary location. Such a program stored in <code>/opt/maemo/usr/bin/program</code> would search, for instance, in <code>/opt/maemo/usr/share</code> while the actual data may be in <code>/usr/share</code>.
+
== Maemo-specific packaging information ==
-
* Installation in <code>/opt</code>:<br/>if you want to perform manual optification (e.g. using <code>configure --prefix=/opt/package</code>) you should store "none" in <code>debian/optify</code> and add some to the postinst script which symlinks the binaries and libraries of the package to <code>/usr/bin</code> and <code>lib</code>, respectively.
+
=== Packaging policy ===
-
* Documentation:<br/>do not install documentation in <code>/usr/share/doc</code> or <code>/usr/share/info</code> - docpurge will remove it. You may install it in the <code>/opt</code> hierarchy, however.
+
{{main|Packaging/Guidelines}}
-
= Maemo-specific packaging information =
+
Maemo packages follow the Debian Policy, but there are some items where Maemo is more strict, since it is an embedded distribution, and other areas where it is more relaxed, since it supports only one user at a time on a single target device and UI framework. In other areas, the policy differs from Debian because we have different objectives and maintainers, and because we have provided different infrastructure for packaging and distributing software.
-
== Packaging policy ==
+
Most of the specifics for Maemo packaging are outlined in the [[/Guidelines|Maemo packaging guidelines]].
-
Maemo packages follow the Debian Policy, but there are some items where Maemo:
+
=== Sections ===
-
* Is more strict (it is an embedded distribution)
+
-
* Is more relaxed:
+
-
** A single target device (per release)
+
-
** A single specified UI (Hildon)
+
-
** A single user
+
-
* Differs from Debian because Maemo has different:
+
-
** Objectives
+
-
** Maintainers
+
-
** Infrastructure
+
-
Most of the specifics for Maemo packaging are outlined in the [http://maemo.org/forrest-images/pdf/maemo-policy.pdf Maemo packaging policy]. The policy is still in the draft stage, so certain parts are still incomplete or not entirely up to date.
+
For applications to be installable throughh Hildon Application Manager, the "Secton:" field in the <code>debian/control</code> file must conform to certain naming conventions.
-
== Sections ==
+
The conformant section names are [[Packaging/Guidelines#Sections|outlined in the packaging guidelines]], and are listed below.
-
This is the list used in Fremantle/Maemo5 and is the same as the [http://lists.maemo.org/pipermail//maemo-developers/2008-October/035437.html final] list for Diablo as [[Task:Package_categories|discussed in the task]].
+
{| class="wikitable sortable"
-
 
+
|+ Maemo section names
-
{| class="wikitable"
+
|-
! Key
! Key
-
! Example English i18n
+
! class="unsortable" | Example English i18n
-
! Example apps
+
! class="unsortable" | Example apps
|-
|-
-
| user/desktop
+
| <code>user/desktop</code>
| Desktop
| Desktop
| Home, statusbar and taskbar applets
| Home, statusbar and taskbar applets
|-
|-
-
| user/development
+
| <code>user/development</code>
| Programming
| Programming
| py2deb
| py2deb
|-
|-
-
| user/education
+
| <code>user/education</code>
| Education
| Education
| Flashcard apps
| Flashcard apps
|-
|-
-
| user/games
+
| <code>user/games</code>
| Games
| Games
| Doom, Duke Nukem 3D
| Doom, Duke Nukem 3D
|-
|-
-
| user/graphics
+
| <code>user/graphics</code>
| Graphics
| Graphics
| Photo apps, GIMP, Inkscape, fonts
| Photo apps, GIMP, Inkscape, fonts
|-
|-
-
| user/multimedia
+
| <code>user/multimedia</code>
| Multimedia ''or'' Sound & Video
| Multimedia ''or'' Sound & Video
| Canola, mplayer, Kagu, UKMP, MediaBox
| Canola, mplayer, Kagu, UKMP, MediaBox
|-
|-
-
| user/navigation
+
| <code>user/navigation</code>
| (Location &) Navigation
| (Location &) Navigation
| maemo-mapper, Navit
| maemo-mapper, Navit
|-
|-
-
| user/network
+
| <code>user/network</code>
| Internet & Networking
| Internet & Networking
| Web browsers, Samba clients, OpenAFS, Transmission
| Web browsers, Samba clients, OpenAFS, Transmission
|-
|-
-
| user/office
+
| <code>user/office</code>
| Office
| Office
| GPE, Claws, AbiWord
| GPE, Claws, AbiWord
|-
|-
-
| user/science
+
| <code>user/science</code>
| Science
| Science
| gnuplot, Octave
| gnuplot, Octave
|-
|-
-
| user/system
+
| <code>user/system</code>
| System
| System
| rotation-support, enhanced kernels, themes
| rotation-support, enhanced kernels, themes
|-
|-
-
| user/utilities
+
| <code>user/utilities</code>
| Utilities ''or'' Accessories
| Utilities ''or'' Accessories
| Calculators, terminals, text editors
| Calculators, terminals, text editors
-
|-
 
|}
|}
If the package's section starts "user/", but is not any of the above, the ''Application Manager'' forces them into an "Other" section.
If the package's section starts "user/", but is not any of the above, the ''Application Manager'' forces them into an "Other" section.
-
== Desktop files ==
+
=== Desktop files ===
{{main|Desktop file format}}
{{main|Desktop file format}}
-
Desktop files are used for application icons in menus on the Linux desktop. The Maemo application menu uses the same desktop files, but installs them to a slightly different location; <code>/usr/share/applications/hildon</code> instead of <code>/usr/share/applications</code>. You can add the desktop file to the <code>.install</code> file for your application so that it is installed to the correct place, for example, if you have <code>debian/application.install</code>, adding the line:
+
Desktop files are used to launch applications from the main application menu. Their format is standardised and documented in the [http://standards.freedesktop.org/desktop-entry-spec/1.0/ freedesktop.org desktop file spec]. The Maemo application menu uses the same desktop files, but looks for them to a slightly different location; <code>/usr/share/applications/hildon</code> instead of <code>/usr/share/applications</code>.
-
application.desktop usr/share/applications/hildon
+
The location of the directory in which to install .desktop files can also be obtained using <code>pkg-config</code>:
-
 
+
-
would install <code>application.desktop</code> to the correct location. The location is also available with <code>pkg-config</code>, for example:
+
  pkg-config --variable=desktopentrydir osso-af-settings
  pkg-config --variable=desktopentrydir osso-af-settings
-
which can be used in a Makefile to install the desktop file to the correct location.
+
The returned value can be used in a Makefile to install the desktop file to the correct location.
There is some official documentation on [[Documentation/Maemo_5_Developer_Guide/Application_Development/Writing_a_new_maemo_application#Adding_application_to_menu|desktop files for Maemo applications]].
There is some official documentation on [[Documentation/Maemo_5_Developer_Guide/Application_Development/Writing_a_new_maemo_application#Adding_application_to_menu|desktop files for Maemo applications]].
-
== Maemo-specific fields ==
+
=== Maemo-specific fields ===
-
There are a number of Maemo-specific package fields that are handled by Application manager. The Application manager documentation [http://hildon-app-mgr.garage.maemo.org/packaging-stable.html outlines] them.
+
There are a number of Maemo-specific Debian packaging fields that are handled by Application manager. The Application manager documentation [http://hildon-app-mgr.garage.maemo.org/packaging-stable.html outlines] them.
-
=== Displaying an icon in the Application Manager next to your package ===
+
==== Displaying an icon in the Application Manager next to your package ====
Displaying an icon in the Application Manager next to your package makes it look pretty and makes your package stand out, and it is not that hard to do.
Displaying an icon in the Application Manager next to your package makes it look pretty and makes your package stand out, and it is not that hard to do.
-
# Make an image that is '''48x48''' pixels. The image can be saved in any format that is supported by GdkPixbufLoader on Maemo, but PNG is commonly used.
+
<ol>
-
# base64 encode the image. This can be done in many ways, depending on the platform, but assuming you are in scratchbox:
+
<li>
 +
Make an image that is '''48×48''' pixels. The image can be saved in any format that is supported by <code>GdkPixbufLoader</code> on Maemo, but PNG is commonly used.
 +
</li>
 +
<li>
 +
base64 encode the image. This can be done in many ways, depending on the platform, but assuming you are in Scratchbox:
 +
<pre>
 +
fakeroot apt-get update
 +
fakeroot apt-get install sharutils
 +
uuencode -m <name of 48×48 image> <name of 48×48 image> > <name of 48×48 image>.base64
 +
</pre>
 +
</li>
 +
<li>
 +
Add the field <code>XB-Maemo-Icon-26</code> to your <code>debian/control</code> (in Maemo4 the size of the icons was 26×26 pixels, hence the name of the field, '''which has not changed''' in Maemo 5)
 +
</li>
 +
<li>
 +
Open the base64 version of your image and copy from the line under ''begin-base64 644 <name of 48×48 image>'' to the line above the ''===''
 +
</li>
 +
<li>
 +
Add this to the <code>XB-Maemo-Icon-26</code> field
 +
</li>
 +
<li>
 +
Add a space in front of every line of the encoded icon. You can do that automatically using sed when you base64 encode the image:
<pre>
<pre>
-
apt-get update
+
uuencode -m <name of 48×48 image> <name of 48×48 image> | sed -e s,^,\ ,  > <name of 48×48 image>.base64
-
apt-get install sharutils
+
-
uuencode -m <name of 48x48 image> <name of 48x48 image> > <name of 48x48 image>.base64
+
</pre>
</pre>
-
# Add the field ''XB-Maemo-Icon-26'' to your <code>debian/control</code> (in Maemo4 the size of the icons was 26x26, hence the name of the field, '''which has not changed''')
+
</li>
-
# Open the base64 version of your image and copy from the line under ''begin-base64 644 <name of 48x48 image>'' to the line above the ''===''
+
</ol>
-
# Add this to the ''XB-Maemo-Icon-26'' field
+
-
# Add a space in front of every line of the encoded icon
+
Here is an example of a properly formatted Maemo-Icon-26: (of wrong image size)
Here is an example of a properly formatted Maemo-Icon-26: (of wrong image size)
Line 349: Line 372:
Please note that if you are packaging a command-line only program that can be executed by the user, you should use the [[User:Tanner#CLI_icon|CLI icon]] only.
Please note that if you are packaging a command-line only program that can be executed by the user, you should use the [[User:Tanner#CLI_icon|CLI icon]] only.
-
=== Bugtracker location ===
+
==== Bugtracker location ====
-
As a requirement for your package being promoted from [[Extras-testing]] to [[Extras]], your <code>debian/control</code> file must have a link to a bugtracker, which is visible in the [http://maemo.org/packages/ maemo.org packages interface]. It is possible to [[Bugs:Adding Extra products|request a component at bugs.maemo.org]] or use a [[Getting_started_with_Maemo_Garage#Trackers_and_tasks|Garage project bugtracker]], or even an email address.
+
<del>As a requirement</del>[http://wiki.maemo.org/Extras-testing/QA_checklist#Blockers] Is strongly recommended for your package being promoted from [[Extras-testing]] to [[Extras]], your <code>debian/control</code> file must have a link to a bugtracker, which is visible in the [http://maemo.org/packages/ maemo.org packages interface]. It is possible to [[Bugs:Adding Extra products|request a component at bugs.maemo.org]] or use a [[Getting_started_with_Maemo_Garage#Trackers_and_tasks|Garage project bugtracker]], or even, for simple packages, an email address .
Add the field ‘XSBC-Bugtracker’ to your <code>debian/control</code>, for example:
Add the field ‘XSBC-Bugtracker’ to your <code>debian/control</code>, for example:
Line 359: Line 382:
  XSBC-Bugtracker: mailto:yourname@example.com
  XSBC-Bugtracker: mailto:yourname@example.com
-
=== Pretty names ===
+
==== Pretty names ====
A package can specify a pretty name for itself. This name is displayed in the Application manager UI instead of the real package name.
A package can specify a pretty name for itself. This name is displayed in the Application manager UI instead of the real package name.
The pretty name is specified with the '<code>XSBC-Maemo-Display-Name</code>' field in your <code>debian/control</code> file, for example:
The pretty name is specified with the '<code>XSBC-Maemo-Display-Name</code>' field in your <code>debian/control</code> file, for example:
-
  XB-Maemo-Display-Name: My package name
+
  XSBC-Maemo-Display-Name: Hello, world!
-
=== Maemo revision string ===
+
==== Maemo revision string ====
If an upstream package is re-packaged or modified for Maemo, the Maemo revision string should be appended to the upstream revision, in the <code>debian/changelog</code> file. So if in Debian the package name was something like "Myapp-0.4-2" in maemo this package will be called "Myapp-0.4-2maemo0". The number after the "maemo" string is a progressive number.
If an upstream package is re-packaged or modified for Maemo, the Maemo revision string should be appended to the upstream revision, in the <code>debian/changelog</code> file. So if in Debian the package name was something like "Myapp-0.4-2" in maemo this package will be called "Myapp-0.4-2maemo0". The number after the "maemo" string is a progressive number.
-
=== Maemo upgrade description ===
+
==== Maemo upgrade description ====
 +
 
Tell users what changed in the update:
Tell users what changed in the update:
  XB-Maemo-Upgrade-Description: Formatted like "Description".  
  XB-Maemo-Upgrade-Description: Formatted like "Description".  
Line 379: Line 403:
As with all Maemo-specific fields, the "XB-" prefix is needed so the field will remain in the binary package.
As with all Maemo-specific fields, the "XB-" prefix is needed so the field will remain in the binary package.
-
=== Translations of text fields ===
+
==== Translations of text fields ====
 +
 
The following fields can be translated to the end user's local language: Maemo-Display-Name, Description and Maemo-Upgrade-Description. It is strongly recommended to make use of this possibility so that end users understand what the application does for them while browsing through the Application Manager.
The following fields can be translated to the end user's local language: Maemo-Display-Name, Description and Maemo-Upgrade-Description. It is strongly recommended to make use of this possibility so that end users understand what the application does for them while browsing through the Application Manager.
Line 393: Line 418:
Note how "Description" becomes "XB-Description-xx_YY" when a locale suffix is added. This is because it's not a standard Debian field any longer.
Note how "Description" becomes "XB-Description-xx_YY" when a locale suffix is added. This is because it's not a standard Debian field any longer.
-
== Debhelper 7 ==
+
=== Debhelper 7 ===
-
A backport of Debhelper 7 for Fremantle is available in extras-devel. It works transparently and can coexist with debhelper 5 in the SDK. It even works on the autobuilder, if the package specifies the correct build-dependency of <code>debhelper7</code>. The following lines in <code>debian/rules</code> are necessary to use the new debhelper:
+
Since the Autobuilder's [http://www.gossamer-threads.com/lists/maemo/developers/60704 use] of the Squeeze devkit, debhelper 7 is supported natively by it.
 +
 
 +
Follow the steps on that link to also make your FREMANTLE_* target use the Squeeze devkit.
 +
 
 +
Note: dh_make doesn't seem to be provided by the Squeeze devkit, so you'll have to run it outside of Scratchbox to get a debian/ folder based on debhelper 7.
 +
 
 +
----
 +
 
 +
A backport of Debhelper 7 for Fremantle is available in extras-devel.  
 +
 
 +
$ fakeroot apt-get install debhelper7
 +
 
 +
It works transparently and can coexist with debhelper 5 in the SDK. It even works on the autobuilder, if the package specifies the correct build-dependency of <code>debhelper7</code>. The following lines in <code>debian/rules</code> are necessary to use the new debhelper:
  PATH:=/usr/bin/dh7:/usr/bin:$(PATH)
  PATH:=/usr/bin/dh7:/usr/bin:$(PATH)
Line 401: Line 438:
  SBOX_REDIRECT_IGNORE=/usr/bin/perl
  SBOX_REDIRECT_IGNORE=/usr/bin/perl
  export SBOX_REDIRECT_IGNORE
  export SBOX_REDIRECT_IGNORE
 +
 +
In debian/control change:
 +
 +
Build-Depends: debhelper (>= 7) [...]
 +
 +
to
 +
 +
Build-Depends: debhelper'''7''' (>= 7) [...]
Further information about the updated debhelper is available at [[User:Tanner#debhelper7]].
Further information about the updated debhelper is available at [[User:Tanner#debhelper7]].
Line 412: Line 457:
Things might get complex if the packaging already uses some new features of level 7, like CDBS-style helper rules. In such cases, looking at versions of packages written prior to the compatibility level upgrade might help doing the downgrade (and most Debian packages are kept in public SCMs like svn.debian.org).
Things might get complex if the packaging already uses some new features of level 7, like CDBS-style helper rules. In such cases, looking at versions of packages written prior to the compatibility level upgrade might help doing the downgrade (and most Debian packages are kept in public SCMs like svn.debian.org).
 +
 +
=== Ovi Store publishing ===
 +
 +
{{main|Ovi Store publishing}}
[[Category:Packaging]]
[[Category:Packaging]]

Latest revision as of 18:25, 13 October 2014

Contents

Creating Packages for Maemo

Since Maemo is based on the Debian operating system, creating packages for Maemo borrows a lot of tools and techniques from Debian.

Further reading

The following list of resources gives in-depth information on packaging in Debian and Maemo. These links largely discuss packaging Python apps but can be used for any programming language.

Checking Maemo Packages

Lintian dissects Debian packages and reports bugs and policy violations. It contains automated checks for many aspects of Debian policy as well as some checks for common errors. Unfortunately it does not check conformance to the additional Maemo policy.

Currently Maemo is creating Maemian to check its policy.

A concrete example - hello

Prerequisites

For the purposes of our article, we will be packaging a simple Hildon hello-world application. This will be a standard source tarball using autotools. For further information, you can follow this detailed tutorial on using Autotools for C++ projects.

You will need a working Maemo 5 SDK and the libhildon1-dev package, version 2.2 or greater, which can be installed in Scratchbox with the command:

fakeroot apt-get install libhildon1-dev

hello.c

The only C file in our project is hello.c:

#include <hildon/hildon.h>
 
int main(int argc, char *argv[])
{
  GtkWidget *window;
  GtkWidget *label;
 
  hildon_gtk_init(&argc, &argv);
 
  window = hildon_window_new();
  label = gtk_label_new("Hello world!");
 
  g_signal_connect(G_OBJECT (window), "destroy", G_CALLBACK (gtk_widget_destroy), NULL);
  gtk_container_add(GTK_CONTAINER(window), label);
  gtk_widget_show_all(window);
 
  gtk_main();
  return 0;
}

Autotools

Main article: Documentation/Maemo 5 Developer Guide/GNU Build System


The rest of the project is a small number of files to allow us to make a standard "./configure && make && make install" project with automake, aclocal and autoconf.

Using the autotools for packaging is quite simple for small projects. You need two files to define the structure of your project, Makefile.am and configure.ac.

configure.ac is a file used by automake and autoconf to generate the configure script, define the version of the resulting .tar.gz and include the tests which we need to ensure the presence of the appropriate versions of dependencies. Since hello.c is so simple, we only need to check for the standard C library and a C compiler, and for the Hildon library. The Hildon library check is done by pkg-config, which makes it easy to check the library version, and get the right compiler and linker flags. The only output file generated by the configure script will be Makefile, from the input file Makefile.in, which is in turn generated from Makefile.am

AC_INIT([hello], [0.1])
AM_INIT_AUTOMAKE([foreign])
AC_PROG_CC
PKG_CHECK_MODULES([HILDON], [hildon-1 >= 2.2])
AC_CONFIG_FILES([Makefile])
AC_OUTPUT

Makefile.am defines the source structure of your project, listing the files to be installed, the binaries and object files to be generated, and the relationship between the binaries and source files.

You can see that our Makefile.am is very simple, defining one source file, and one binary file. The "_SOURCES" line must start with a binary name from "bin_PROGRAMS" to make the link between the source file and the executable. The "_CPPFLAGS" and "_LDADD" lines take the Hildon preprocessor and library flags that are provided by pkg-config in configure.ac.

bin_PROGRAMS = hello
hello_SOURCES = hello.c
hello_CPPFLAGS = $(HILDON_CFLAGS)
hello_LDADD = $(HILDON_LIBS)

Once we have these files, we simply need to initialise our project, defining its license, and generating all of the required files for automake to do its thing. We do this by running:

autoreconf --force --install

The arguments to autoreconf copy required files to the project (including generic install instructions and a license).

Pay attention during the execution of autoreconf, the execution should be entirely silent if it runs correctly. If there are messages, read them and do what is required to address the issues.

Now to build your software, you have a standard configure script and can simply run

./configure
make
make install

and to build a distribution file, you have

make dist

which will create a file hello-0.1.tar.gz, which you can use for the rest of this packaging tutorial.

Packaging a .deb

The easiest way to package a .deb file is to use Debian's build helpers.

Package your application as you would distribute it in a .tar.gz (when using autotools, this is done with "make distcheck"). In our example, we uncompress hello-0.1.tar.gz, and change the current directory to hello-0.1.

$ tar xfz hello-0.1.tar.gz
$ cd hello-0.1

Then we run dh_make, which initialises the Debian package management file structure (among other things):

$ dh_make -e <my email address> -f ../hello-0.1.tar.gz -c GPL

You can of course choose a different licence for your package.

Answer the resulting questions - in this case, we are packaging a single binary.

We can now edit the files in the debian/ directory which has been created to their desired values, before packaging the software. In fact, we can delete many of these files. All of the files ending in “.ex” or “.EX” are example files, intended to help you package different types of software.

If you use a standard configure script, you do not need to modify any files except debian/control, where the Hildon build-time dependency should be added. Change the Build-Depends line to read (by adding "libhildon1" at the end):

Build-Depends: debhelper (>= 5), autotools-dev, libhildon1 (>= 2.2)

Before creating a .deb, you should set a changelog entry. .deb changelogs follow a special format, so rather than editing the files by hand, use the dch helper application. This will allow you to add what new features went into this application, give credit, and so on. It is an especially important file because it sets the version and revision of the source and binary packages. On saving, a syntax check is performed which ensures that the resulting file is OK. The file format is completely documented in the Debian packaging guide.

Finally, we generate a .deb from the source code using the command:

dpkg-buildpackage -sa -rfakeroot -k<my email address>

You should now have several files created in the parent directory to where you unpacked the source code. I have;

hello_0.1.orig.tar.gz
hello_0.1-1_i386.deb
hello_0.1-1.diff.gz
hello_0.1-1.dsc
hello_0.1-1_i386.changes

Now change the target architecture to ARMEL and rebuild it, to generate hello_0.1-1_arm.deb:

sb-conf se FREMANTLE_ARMEL
dpkg-buildpackage -sa -rfakeroot -k<my email address>

Additional information

Ignoring git metadata

If you use git then you may not want to include the entire git repo in your source bundle. With dpkg-source version 1.13.25 the -i option is not git-aware so you can do:

 dpkg-buildpackage -rfakeroot -sa  -i -I.git
Adding build-time dependencies

If your program uses another library, such as Hildon in the above example, then both the Debian package and the configure script must depend on the library. Otherwise, since the autobuilder only installs packages explicitly required to build your package, the build will fail.

Often, the Debian package has a different name to the pkg-config file, just like in the Hildon example. One way to check which package owns a pkg-config file is to use dpkg-query on the pkg-config file, for example the mafw pkg-config file (notice the extra .pc file extension):

dpkg-query --search mafw.pc

which looks through the installed packages and finds:

libmafw0-dev: /usr/lib/pkgconfig/mafw.pc

Then you know that you must add libmafw0-dev to the Build-Depends line in debian/control if you use the mafw pkg-config file in configure.ac.

Checking build-time dependencies

You may verify that your Build-Depends field in debian/control is complete by running:

dpkg-depcheck -m dpkg-buildpackage -rfakeroot -b

in the source tree. (You will need to fakeroot apt-get install devscripts for this to work).

Adding an icon and desktop file

To ensure that your package shows up in the application menu, you will need to install an icon and a .desktop file with your package.

The icon can be in a number of formats. To keep things simple, you can use this 48x48 .png as your icon for now.

The format of .desktop files is specified by the freedesktop.org desktop entry spec, with a number of Maemo specific extensions. The simplest possible .desktop file for Maemo contains a "Desktop Entry" group containing an indicator that it refers to an application, the application name, the icon to use, and a path to the executable which will launch the application. Other standard keys can be found in the spec.

[Desktop Entry]
Type=Application
Name=Hello!
Icon=hello
Exec=/usr/bin/hello

Pixmaps referenced without an absolute path in the desktop file can be installed in a number of locations, specified in the freedesktop.org icon theme spec. The simplest place to put the icon is in /usr/share/icons. The Icon entry above will thus match /usr/share/icons/hello.png.

Once you have created these files in your source directory, you will need to add the following to Makefile.am to ensure that they are distributed in the tarball (created during make dist) installed in the right place, and packaged correctly, and you should re-run autoreconf, configure, make dist and dpkg_buildpackage once you have done so.

icondir = $(datadir)/icons
dist_icon_DATA = hello.png
 
desktopdir = $(datadir)/applications/hildon
dist_desktop_DATA = hello.desktop

To make the package installable using Hildon Application Manager (which will get launched when you select the package), you should follow the #Maemo-specific packaging information below. In particular, you must set the "Section" to one of the valid sections below in the "debian/control" file.

Testing your package

The first place you can test your app is in Scratchbox. Start Xephyr and the Maemo GUI as described in the Maemo 5 SDK instructions, then run your application by hand from within Scratchbox.

Once you have created .deb packages of your application for x86 and armel, you can also test the installation process and test your application on your N900.

To test the installation on Xephyr, you can either install it from the command line with
dpkg -i hello_0.1-1_i386.deb
, or copy the i386 .deb files to the
/home/<username>/MyDocs
directory, and click on it to install it.

To test on your device, copy the armel .deb file to the .documents directory on your device, and install it by selecting it in the file manager. You will need to ensure that the OS version on your device is compatible with the development environment in your Scratchbox.

Once the package is installed, you will be able to launch it directly from the command line in the X terminal application. To get the application to appear in the application list, you will need to include an icon and desktop file in the package as described in the packaging policy.

Uploading to extras-devel

Main article: Uploading to Extras-devel


Maemo-specific packaging information

Packaging policy

Main article: Packaging/Guidelines


Maemo packages follow the Debian Policy, but there are some items where Maemo is more strict, since it is an embedded distribution, and other areas where it is more relaxed, since it supports only one user at a time on a single target device and UI framework. In other areas, the policy differs from Debian because we have different objectives and maintainers, and because we have provided different infrastructure for packaging and distributing software.

Most of the specifics for Maemo packaging are outlined in the Maemo packaging guidelines.

Sections

For applications to be installable throughh Hildon Application Manager, the "Secton:" field in the debian/control file must conform to certain naming conventions.

The conformant section names are outlined in the packaging guidelines, and are listed below.

Maemo section names
Key Example English i18n Example apps
user/desktop Desktop Home, statusbar and taskbar applets
user/development Programming py2deb
user/education Education Flashcard apps
user/games Games Doom, Duke Nukem 3D
user/graphics Graphics Photo apps, GIMP, Inkscape, fonts
user/multimedia Multimedia or Sound & Video Canola, mplayer, Kagu, UKMP, MediaBox
user/navigation (Location &) Navigation maemo-mapper, Navit
user/network Internet & Networking Web browsers, Samba clients, OpenAFS, Transmission
user/office Office GPE, Claws, AbiWord
user/science Science gnuplot, Octave
user/system System rotation-support, enhanced kernels, themes
user/utilities Utilities or Accessories Calculators, terminals, text editors

If the package's section starts "user/", but is not any of the above, the Application Manager forces them into an "Other" section.

Desktop files

Main article: Desktop file format


Desktop files are used to launch applications from the main application menu. Their format is standardised and documented in the freedesktop.org desktop file spec. The Maemo application menu uses the same desktop files, but looks for them to a slightly different location; /usr/share/applications/hildon instead of /usr/share/applications.

The location of the directory in which to install .desktop files can also be obtained using pkg-config:

pkg-config --variable=desktopentrydir osso-af-settings

The returned value can be used in a Makefile to install the desktop file to the correct location.

There is some official documentation on desktop files for Maemo applications.

Maemo-specific fields

There are a number of Maemo-specific Debian packaging fields that are handled by Application manager. The Application manager documentation outlines them.

Displaying an icon in the Application Manager next to your package

Displaying an icon in the Application Manager next to your package makes it look pretty and makes your package stand out, and it is not that hard to do.

  1. Make an image that is 48×48 pixels. The image can be saved in any format that is supported by GdkPixbufLoader on Maemo, but PNG is commonly used.
  2. base64 encode the image. This can be done in many ways, depending on the platform, but assuming you are in Scratchbox:
    fakeroot apt-get update
    fakeroot apt-get install sharutils
    uuencode -m <name of 48×48 image> <name of 48×48 image> > <name of 48×48 image>.base64
    
  3. Add the field XB-Maemo-Icon-26 to your debian/control (in Maemo4 the size of the icons was 26×26 pixels, hence the name of the field, which has not changed in Maemo 5)
  4. Open the base64 version of your image and copy from the line under begin-base64 644 <name of 48×48 image> to the line above the ===
  5. Add this to the XB-Maemo-Icon-26 field
  6. Add a space in front of every line of the encoded icon. You can do that automatically using sed when you base64 encode the image:
    uuencode -m <name of 48×48 image> <name of 48×48 image> | sed -e s,^,\ ,  > <name of 48×48 image>.base64
    

Here is an example of a properly formatted Maemo-Icon-26: (of wrong image size)

Description: Chess...
XB-Maemo-Icon-26: 
 iVBORw0KGgoAAAANSUhEUgAAABoAAAAaCAYAAACpSkzOAAAABGdBTUEAAK/INwWK6QAAABl0
 RVh0U29mdHdhcmUAQWRvYmUgSW1hZ2VSZWFkeXHJZTwAAALxSURBVHja3FZNTBNREP669J/S
 XYxtKRWl1JOSFBIPhkitCQeNiaKBmzdj9Ggk0ZOBxHDWixcTjV6MF+WiIB40YEyMBMGYEqQK
 tLS2lG7pdre0pF3WtxslgJRuD2J0kpfdTN7O976Z782sRpIk7IZR2C2TGW1cv8xaY5WuXLy8
 iW5XV5fk8/kkr9e7ya/T6SSNRiOViikvbbmDDD590SusZBGYDiDwJbDud7vdvYIgIJfLYXV1
 tSwhrQrSfRX6/26N/j+gkjW6ce06HE4HGEctGuj9oEwUzFYz5ubmEA6HQVEUisUi8vn8b4rd
 zjRbNxCZrr+3t7XTzjrnvMfdxMi7xj6OIRaPIbWcQjabVdRWKBTkrX4SZ2SjvCtKXf+tkxxD
 M5MetwfHj/lwwueHy+WCVqvdehdHKq7R6JvbpfNMAGiGhs1mg9ls3sS+4hodbDqCwef9mA9P
 7vhhVVWV3BGUOomiaCSufEWMxNwimlweMFYbpoMfyp70J6t8xanLZgWs8Ak07N0Hau0P3qOs
 wIHnl5FJx2E1WlUFuXrzIS713KusRplMCoLAgl2O4N34ODQ4VRaot6cbUzMRNNQ/w/uJWXWM
 eH5JARkYHsLQMIe1NZEpB7Sn1uKFhkL3maO4cL5NHVAo+hkPnrzEq2HqQIf/3ICzvr7FXmeH
 3qBXlslkgtFoVBS3YfbcKRRFfJpagE6vUwd0//FbjI7mkcvnGoNfg51ORx3sNju+hWYxMxsk
 jHlF2jJgdXU1DAaDrDx/kQAVRREJlldXo8kJoPlQ8wHSevosFgs5MmE5H0IingDP8eAzPAQC
 tkJakDz05Hsks+poPzwg6+Luo9chVb2O3Hilv7V6W5nO02cVX3wxjsj3CMKRBUSjUcQWY0iy
 SQVoi6XJaiQxubKpI02yj2xk6BoaBr0BqXRKCZpYSiCZlIXCguM4pWtvY0ypyUtt87PSIj/t
 pJ/JICzLKiBLySTYVArpdFrp3DuMhRZVqfvnJ+wPAQYA1hdr5EDqltYAAAAASUVORK5CYII=

Please note that if you are packaging a command-line only program that can be executed by the user, you should use the CLI icon only.

Bugtracker location

As a requirement[1] Is strongly recommended for your package being promoted from Extras-testing to Extras, your debian/control file must have a link to a bugtracker, which is visible in the maemo.org packages interface. It is possible to request a component at bugs.maemo.org or use a Garage project bugtracker, or even, for simple packages, an email address .

Add the field ‘XSBC-Bugtracker’ to your debian/control, for example:

XSBC-Bugtracker: https://bugs.maemo.org/enter_bug.cgi?product=mypackage

Alternatively for e-mail addresses, you can use the following format:

XSBC-Bugtracker: mailto:yourname@example.com

Pretty names

A package can specify a pretty name for itself. This name is displayed in the Application manager UI instead of the real package name.

The pretty name is specified with the 'XSBC-Maemo-Display-Name' field in your debian/control file, for example:

XSBC-Maemo-Display-Name: Hello, world!

Maemo revision string

If an upstream package is re-packaged or modified for Maemo, the Maemo revision string should be appended to the upstream revision, in the debian/changelog file. So if in Debian the package name was something like "Myapp-0.4-2" in maemo this package will be called "Myapp-0.4-2maemo0". The number after the "maemo" string is a progressive number.

Maemo upgrade description

Tell users what changed in the update:

XB-Maemo-Upgrade-Description: Formatted like "Description". 
 Will be displayed if user upgrades to new version and clicks
 on "Details".
 .
 Human-readable and translatable.

As with all Maemo-specific fields, the "XB-" prefix is needed so the field will remain in the binary package.

Translations of text fields

The following fields can be translated to the end user's local language: Maemo-Display-Name, Description and Maemo-Upgrade-Description. It is strongly recommended to make use of this possibility so that end users understand what the application does for them while browsing through the Application Manager.

The translation is done by adding a suffix like "-de_DE" to the respective field name, where "de_DE" is the locale the translated text is for. For example, if LC_MESSAGES equals de_DE, the Application Manager first tries "Description-de_DE" to find the description of a package and then falls back to "Description".

Here's an example:

Description: Chess...
XB-Maemo-Display-Name: My package name
XB-Maemo-Upgrade-Description: Formatted like "Description". 
XB-Description-de_DE: Schach...
XB-Maemo-Display-Name-de_DE: Mein Packetname
XB-Maemo-Upgrade-Description-de_DE: Formatiert wie "Description". 

Note how "Description" becomes "XB-Description-xx_YY" when a locale suffix is added. This is because it's not a standard Debian field any longer.

Debhelper 7

Since the Autobuilder's use of the Squeeze devkit, debhelper 7 is supported natively by it.

Follow the steps on that link to also make your FREMANTLE_* target use the Squeeze devkit.

Note: dh_make doesn't seem to be provided by the Squeeze devkit, so you'll have to run it outside of Scratchbox to get a debian/ folder based on debhelper 7.


A backport of Debhelper 7 for Fremantle is available in extras-devel.

$ fakeroot apt-get install debhelper7 

It works transparently and can coexist with debhelper 5 in the SDK. It even works on the autobuilder, if the package specifies the correct build-dependency of debhelper7. The following lines in debian/rules are necessary to use the new debhelper:

PATH:=/usr/bin/dh7:/usr/bin:$(PATH)
export PATH
SBOX_REDIRECT_IGNORE=/usr/bin/perl
export SBOX_REDIRECT_IGNORE

In debian/control change:

Build-Depends: debhelper (>= 7) [...]

to

Build-Depends: debhelper7 (>= 7) [...]

Further information about the updated debhelper is available at User:Tanner#debhelper7.

If you also need a more recent CDBS, then use the package cdbs-dh7, which conflicts with the standard CDBS and does not work on autobuilder yet.

Alternatively, you can try to use debhelper 5. Debian packages that require level 7 need some changes, for example:

  • debian/compat: 7 -> 5
  • debian/control: Build-Depends: debhelper (>= 7) -> debhelper (>= 5)
  • Possibly, comment out a few dh_* calls from debian/rules, which might not exist on level 5

Things might get complex if the packaging already uses some new features of level 7, like CDBS-style helper rules. In such cases, looking at versions of packages written prior to the compatibility level upgrade might help doing the downgrade (and most Debian packages are kept in public SCMs like svn.debian.org).

Ovi Store publishing

Main article: Ovi Store publishing