Maemo Wiki Mirror - User contributions [en]

Packaging

2010-02-20T15:25:52Z

84.155.215.92: /* Finding your package in Debian */ following along recipe

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

* [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://python-modules.alioth.debian.org/python-modules-policy.htm Python Modules Policy]: Reference document.
* [http://showmedo.com/videos/video?name=linuxJensMakingDeb Creating debs on Ubuntu]: A great screencast and tutorial showing how to package a simple python application as a deb on Ubuntu!
* [https://wiki.ubuntu.com/PackagingGuide Ubuntu Packaging Guide]
* [[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
* [[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

=== 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 - rot13 =
== Prerequisites ==

We assume here that you have a software package which you have developed, and which can be installed from source using a standard <pre>./configure; make; sudo make install</pre> process.

For the purposes of our article, we will be packaging a simple command-lie utility called "rot13", which will perform a simple [http://en.wikipedia.org/wiki/ROT13 rot13] cipher on all text input from stdin.

== 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 rot13-0.1.tar.gz, and change the current directory to rot13-0.1.

$ tar xfz rot13-0.1.tar.gz
$ cd rot13-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 ../rot13-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 <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.

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

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;

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

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

=== Additional information ===

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

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

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

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

== Uploading to extras-devel ==

{{main|Uploading to Extras-devel}}

= Porting an existing Debian package =

== Finding your package in Debian ==

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.

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;

<pre>
$ echo "deb http://ftp.it.debian.org/debian/ unstable main contrib non-free" >> /etc/apt/sources.list
$ 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>

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

== Modifying a Debian package for Maemo ==

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.

The maintainer field (in the <code>debian/control</code> file) must be changed if the upstream package is modified, for example:
Maintainer: Tcl/Tk Debian Packagers <pkg-tcltk-devel@lists.alioth.debian.org>
should be replaced by
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:
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]

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

== Differences between Debian/Ubuntu and Maemo ==

The are a couple of important differences between a Debian system and Maemo:

* '''Busybox''': 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.

* Outdated '''build and configuration tools''': 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]]

* Directories for '''temporary files''': <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>).

* '''Optification''' may confuse programs: 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>.

* Installation in <code>/opt</code>: 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.

* Documentation: 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.

= Maemo-specific packaging information =

== Packaging policy ==

Maemo packages follow the Debian Policy, but there are some items where Maemo:
* 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.

== Sections ==

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

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

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

# 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.
# base64 encode the image. This can be done in many ways, depending on the platform, but assuming you are in scratchbox:
<pre>
apt-get update
apt-get install sharutils
uuencode -m <name of 48x48 image> <name of 48x48 image> > <name of 48x48 image>.base64
</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''')
# 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 ''===''
# 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)
<pre>
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=
</pre>

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

# Add the field ‘XSBC-Bugtracker’ to your debian/control, for example: <pre>XSBC-Bugtracker: https://bugs.maemo.org/enter_bug.cgi?product=mypackage</pre>

=== 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 '<code>XSBC-Maemo-Display-Name</code>' field in your <code>debian/control</code> file, for example:
XSBC-Maemo-Display-Name: My package name

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

== 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:

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

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

If you also need a more recent [http://build-common.alioth.debian.org/ CDBS], then use the package [http://maemo.org/packages/view/cdbs-dh7/ 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).

[[Category:Packaging]]

Packaging

2010-02-20T15:21:34Z

84.155.215.92: /* Finding your package in Debian */

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

* [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://python-modules.alioth.debian.org/python-modules-policy.htm Python Modules Policy]: Reference document.
* [http://showmedo.com/videos/video?name=linuxJensMakingDeb Creating debs on Ubuntu]: A great screencast and tutorial showing how to package a simple python application as a deb on Ubuntu!
* [https://wiki.ubuntu.com/PackagingGuide Ubuntu Packaging Guide]
* [[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
* [[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

=== 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 - rot13 =
== Prerequisites ==

We assume here that you have a software package which you have developed, and which can be installed from source using a standard <pre>./configure; make; sudo make install</pre> process.

For the purposes of our article, we will be packaging a simple command-lie utility called "rot13", which will perform a simple [http://en.wikipedia.org/wiki/ROT13 rot13] cipher on all text input from stdin.

== 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 rot13-0.1.tar.gz, and change the current directory to rot13-0.1.

$ tar xfz rot13-0.1.tar.gz
$ cd rot13-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 ../rot13-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 <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.

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

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;

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

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

=== Additional information ===

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

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

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

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

== Uploading to extras-devel ==

{{main|Uploading to Extras-devel}}

= Porting an existing Debian package =

== Finding your package in Debian ==

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.

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;

<pre>
$ echo "deb 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>

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

== Modifying a Debian package for Maemo ==

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.

The maintainer field (in the <code>debian/control</code> file) must be changed if the upstream package is modified, for example:
Maintainer: Tcl/Tk Debian Packagers <pkg-tcltk-devel@lists.alioth.debian.org>
should be replaced by
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:
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]

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

== Differences between Debian/Ubuntu and Maemo ==

The are a couple of important differences between a Debian system and Maemo:

* '''Busybox''': 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.

* Outdated '''build and configuration tools''': 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]]

* Directories for '''temporary files''': <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>).

* '''Optification''' may confuse programs: 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>.

* Installation in <code>/opt</code>: 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.

* Documentation: 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.

= Maemo-specific packaging information =

== Packaging policy ==

Maemo packages follow the Debian Policy, but there are some items where Maemo:
* 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.

== Sections ==

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

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

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

# 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.
# base64 encode the image. This can be done in many ways, depending on the platform, but assuming you are in scratchbox:
<pre>
apt-get update
apt-get install sharutils
uuencode -m <name of 48x48 image> <name of 48x48 image> > <name of 48x48 image>.base64
</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''')
# 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 ''===''
# 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)
<pre>
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=
</pre>

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

# Add the field ‘XSBC-Bugtracker’ to your debian/control, for example: <pre>XSBC-Bugtracker: https://bugs.maemo.org/enter_bug.cgi?product=mypackage</pre>

=== 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 '<code>XSBC-Maemo-Display-Name</code>' field in your <code>debian/control</code> file, for example:
XSBC-Maemo-Display-Name: My package name

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

== 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:

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

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

If you also need a more recent [http://build-common.alioth.debian.org/ CDBS], then use the package [http://maemo.org/packages/view/cdbs-dh7/ 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).

[[Category:Packaging]]