View source for Packaging/Guidelines

=Introduction and processes=


==Target audience==

The target audience for this document are developers wanting either to develop for or port packages to the Maemo platform. The contents of these packages can be either open or proprietary, the rules are the same for both.


==Purpose==

This document describes the general rules agreed for creating Maemo packages. Following them makes package integration easier (non-compliance is a blocker or critical bug) and it will help maintaining the packages in the long run. Conforming packages should also install and behave better in the users’ devices.

For related documents, see:
* '''[[Documentation|Maemo Documentation]]''' An overview of the Maemo platform
* '''[http://www.debian.org/doc/debian-policy/ Debian Policy]''' Policy for Debian, the upstream distribution of Maemo
* '''[[Packaging|Maemo Packaging]]''' A guide for making packages installable in the Application Manager
* '''[[Packaging a Qt application]]'''

==Process for updating the guidelines==

The Maemo packaging guidelines are maintained by the Nokia Maemo team and the community. Proposals for guidelines changes and additions shall be documented on the discussion page in this wiki and discussed on the [mailto:maemo-developers@maemo.org maemo-developers@maemo.org] [[Community mailing lists|mailing list]]. Proposals can be accepted into the policy after a certain consensus is established. Rejected proposals are listed separately in the wiki.

==Relation to Debian Policy==

This document is modeled after the Debian Policy manual version 3.7.2.2. It lists only the differences between the Debian policy and the Maemo packaging policy, stating reasons for the differences and including some other notes on subjects discussed in the Debian policy.

In general Maemo packages should follow the Debian policy. However, there are some items where Maemo:
* Is more strict because it is an embedded distribution, aimed at consumer products with more limited resources and also e.g. different legal requirements
* Is more relaxed because the target (Nokia) devices are used only through a specific UI and do not have multiple simultaneous users
* Differs from Debian because each distribution has its own objectives, maintainers and infrastructure.

The lintian command (from the lintian package) on Debian (and derived) Linux distributions can be used to check packages against the Debian Policy and good packaging practices. Currently Maemo does not provide a utility to check conformance to the additional policies stated in this document.

== Conformance and handling packaging differences ==

The guidelines do not require that Maemo would have the same packages available (or the same versions of packages) as Debian. However, when the same software or functionality is available in both Maemo and Debian, it should be packaged similarly when possible, to improve compatibility and to reduce maintenance and porting overhead. This section describes the processes and general guidelines for ensuring compatibility and policy conformance.

=== Guidelines violations ===

If a package does not conform to the Maemo packaging guidelines, or to Debian Policy in issues not covered by the Maemo packaging policy, one of the following actions MUST be taken for the package to be acceptable for Maemo: 
* The package is fixed
* The Maemo packaging guidelines are updated to accept this exception
* The policy change is propagated to upstream (to Debian Policy) Bugs filed for policy violations should include the keyword “policy”.


=== Differences between corresponding Maemo and Debian packages ===

When a package in Maemo conforms to the policy, but the packaging differs from Debian in a way that could cause incompatibilities (and the difference is not because of something stated in this policy document), a bug with a “packaging” keyword SHOULD be filed. Here incompatibilities means anything that would cause problems using the package together with other packages, including e.g. the location of files, package naming, whether the package provides what is expected from it, that it doesn’t include conflicting files without declaring a conflict, etc.

If the bug is valid, the packaging SHOULD be changed to resolve the issue. (If the issue is minor or cannot be fixed now, that should only affect the severity or schedule, and the bug should remain open.) Reasons for WONTFIX could be e.g.:
* the constraints of the device environment,
* that changing the current packaging or behavior would break some specific product feature, or
* that the packaging change has already been promoted upstream or Debian is otherwise considering a similar packaging change.

Currently Maemo corresponds mostly to the Debian 4.0 (“Etch”) release, so packaging SHOULD be modeled after that or a newer Debian version.


=== Maemo packages that are not yet in Debian ===

When packaging new software, please note the correct use of the version string: If the package is native to Maemo (does not have an upstream), a revision part should not be used; [[#The version of a package|otherwise see the policy about packaging upstream sources]].

== Terminology ==

'''BTS Bug Tracking System.''' The public BTS for Maemo is at https://bugs.maemo.org/

'''Upstream sources''' The original, unpackaged source code for some software

'''Upstream distribution''' The distribution where packaged sources are taken from. The upstream distribution for Maemo is Debian. In some cases Maemo also packages upstream sources directly instead of using or modifying Debian source packages.

'''Upstream package''' A package in the upstream distribution.

The uppercase words “MUST”, “SHOULD” and “MAY” are used to distinguish the significance of the various guidelines in this policy document. Packages that do not conform to the guidelines denoted by “MUST” will generally not be considered acceptable for Maemo. Non-conformance with guidelines denoted by “SHOULD” will generally be considered a bug, but will not necessarily render a package unsuitable for distribution.


= The Maemo archives =

== Categories ==

Debian’s “main”, “contrib” and “non-free” categories are not used as such in Maemo packages. The directory structure of repositories may follow this model or something else, but that is not relevant to packaging and therefore not in the current scope of this document.

== Sections ==

Packages are grouped into sections as in Debian, but SHOULD NOT specify a category in the segment part. (However it is not a bug if a package taken from Debian and made available in Maemo retains its “contrib” or “non-free” segment.) Instead Maemo defines a user segment for controlling visibility in the Application Manager. Packages that are intended to be visible in the Application Manager MUST belong to the user segment, and packages that are not intended to be visible (such as libraries and other dependencies) MUST NOT belong to that segment.

The section of packages in the user segment MUST be one of the following:

{| class="wikitable sortable"
|+ Maemo package sections
|-
! Key
! class="unsortable" | Example English i18n
|-
| <code>user/desktop</code>
| Desktop
|-
| <code>user/development</code>
| Programming
|-
| <code>user/education</code>
| Education
|-
| <code>user/games</code>
| Games
|-
| <code>user/graphics</code>
| Graphics
|-
| <code>user/multimedia</code>
| Multimedia ''or'' Sound & Video
|-
| <code>user/navigation</code>
| (Location &) Navigation
|-
| <code>user/network</code>
| Internet & Networking
|-
| <code>user/office</code>
| Office
|-
| <code>user/science</code>
| Science
|-
| <code>user/system</code>
| System
|-
| <code>user/utilities</code>
| Utilities ''or'' Accessories
|}


The sections in this list will appear correctly localized in the Application Manager. As an example, to put a package into the Office section and make it visible to the user, the value of the Section field in the debian/control file should be user/office. Packages not in the user segment SHOULD use the sections listed in the Debian Policy (http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections).

== Priorities ==

Maemo doesn’t currently use package priorities for anything. For future compatibility, please conform to the Debian policy.


= Binary packages =


== Package naming ==

Any use of the word “Maemo” is subject to the trademark policies and guidelines set forth at maemo.org (see [http://maemo.org/legal/terms_of_use/trademarks/ Maemo Trademark Policy]). In general, a package may use the word “Maemo” as a part of its name only if the package is both:

* Created or approved in writing by Nokia Corporation, and
* Intended to be used only in the Maemo environment (either within Scratchbox or devices) 

Packages that were published with the word “Maemo” in the package name before 11th May 2007 (when the trademark policy was published) may continue using that name; see the Trademark FAQ available at [http://maemo.org/ maemo.org].

== The version of a package ==

If an upstream package is re-packaged or otherwise modified for Maemo, the packaging changes MAY be propagated back to upstream.

The resulting revision string SHOULD have the form “RidentifierX” where:
* R is the upstream revision
* If the modification is intended (only) for the Maemo platform, identifier SHOULD be “Maemo”. In other cases some suitable other identifier should be used.
* X is a monotonically increasing number.

If upstream sources are packaged for Maemo directly, when an upstream package for the corresponding version does not exist but is likely to become available later, a Maemo revision prefixed with zero SHOULD be used (resulting in “0identifierX”). 

These rules ensure that when a new upstream package is released, its revision will be higher and it will be considered as an upgrade from the older Maemo package (the future upstream package may or may not require modification to fit into Maemo, but that should not be a consideration when choosing revision numbers). This is similar to how e.g. Ubuntu deals with Debian packages.

To verify that the new version is higher than the previous Maemo version, but lower than the next upstream version would be, compare the version numbers with: 
 dpkg --compare-versions oldversion lt newversion && echo true

Otherwise the rules for package versions are the same as in Debian. (Please note the proper format of the version string: For native packages, i.e. software which doesn’t have an upstream, use a version number without a revision part.)


=== Example of modifying an upstream package ===

* Version of upstream sources: 0.10
* Version of upstream package: 0.10-4
* Version of modified package in Maemo: 0.10-4maemo1


=== Example of packaging sources not yet in the upstream distribution ===

* Version of upstream sources: 0.7
* Latest package in upstream distribution: 0.6-3
* Package version in Maemo: 0.7-0maemo1

== Package maintenance ==

Currently Maemo does not have a process for orphaned packages.

== Dependencies ==

See [[#Essential packages|Essential packages]] below.

== Virtual packages ==

Virtual package names intended for generic use SHOULD be commonly agreed and appear in the list included in the <code>maemo-policy</code> package. Virtual package names MAY be created privately for use between a certain group of packages, provided that the chosen name clearly belongs to those packages (using e.g. foo-theme for package foo, or similar).


== Base system ==

Maemo doesn’t have a base system in the sense that Debian does, as there is no installer. In some ways everything that is included in the device (or SDK) images could be considered a “base system”, but this does not affect packaging.

== Essential packages ==

Packages marked Essential are always installed in Debian based systems, and according to the Debian Policy, other packages should not list dependencies to them unless a specific version dependency is needed.

However, Maemo installations have a different set of essential packages as Debian, and therefore binary packages MUST list their direct dependencies also to packages that are essential in Debian, but not guaranteed to be installed in all Maemo devices. (This is especially important to note when porting packages from Debian to Maemo.)

As a result, package installation and uninstallation MUST be tested on a device which doesn’t have extra software installed. Testing package installation in Scratchbox is not enough, as Scratchbox uses the real Debian binaries instead of BusyBox.

== Prompting in maintainer scripts ==

As users do not see the command line, prompting the user MUST be done using GUI tools. The following tools are provided in Maemo for this:

'''maemo-confirm-text''' Present user with text and ask for confirmation

A package using these MUST depend on hildon-application-manager for maemo-confirm-text.

For more information on the tools, see [[Documentation/Maemo_5_Developer_Guide/Packaging,_Deploying_and_Distributing|Packaging, Deploying and Distributing]].

All other installation time interaction requirements at SHOULD be first discussed on the maemo-developers mailing list.

== Separating files into binary packages (new section)==

Due to the limited space on available on devices, any files that are not needed at run time SHOULD either be removed from the binary packages or put in a separate binary package which is not installed by default. See the following subsections for details.

If this requires packaging the sources differently from the upstream distribution (Debian), the packaging changes SHOULD be propagated back to upstream (unless the changes are incompatible with the upstream policy or practices, as might be the case e.g. with documentation and localization packaging).

=== Library and program packages ===

Libraries SHOULD be packaged separately from programs using them. This also encourages better API maintenance.

=== Development packages ===

If there are development files (static libraries, headers, test programs etc), they MUST be in a separate development (-dev) package. Libtool *.la files MUST NOT be included in any packages, as they cause problems with indirect library dependencies.

=== Localization packages ===

Applications SHOULD NOT directly depend on multiple localizations, instead they SHOULD depend on a generic package name and each localization package SHOULD "provide" that package.

=== Documentation packages ===

If documentation is included, it SHOULD be packaged separately. Also, if end-user documentation is localized, the version for each language or locale SHOULD be packaged as noted in [[#Localization packages|above]].

Developer documentation SHOULD be packaged separately from end-user documentation, as developer documentation should not need to be installed on end-user devices. API documentation for libraries SHOULD be auto-generated from the sources.

=== Debug packages ===

Debug symbol files MUST NOT be included in binary packages (applications or libraries) intended to be installed on user machines.  Library symbol files SHOULD be included in -dev packages or in -dbg packages for the library.  Application symbol files MAY be included in -dbg packages for the application.

Debug symbol files are required to allow users to debug packages, because on ARM (unlike on x86) optimized binaries or libraries cannot be debugged without them. Debug symbols also help in getting more useful performance and memory profiling results.

The <code>debug-pkg-check</code> script from the <code>maemo-debug-scripts</code> package can be used to verify debug packages. See also [[#Compilation options and stripping|Compilation options and stripping]].

=== Configuration packages ===

If the packaged software may have different configurations (e.g. for different regions, products, customizations, device and SDK environments, etc.), those configurations SHOULD be packaged separately. Configurations could be simple files in /etc, or something more complex such as themes or pluggable modules.

Configuration packages SHOULD depend on the package that uses them (to avoid leaving the configuration installed and consuming flash space when the actual software is uninstalled).

The application package SHOULD only depend on the configuration if it is required for the software to function. If there can be any number of alternate configurations, a virtual package SHOULD be used for the dependency. If alternate configurations cannot coexist, they MUST declare a conflict (using the virtual package if provided). This section mainly concerns software that is part of the Maemo platform, but separating programs from configurations is often a good practice for other packages as well. Please consider even building the configuration from a different source package; this way the whole program does not have to be rebuilt (and possibly approved) for a simple configuration change, and the user has less packages to download when upgrading.


= Source packages =

== Package relationships ==

Unlike the [[#Essential packages|run-time environment on Maemo devices]], the Maemo build environment (= Scratchbox + Debian dev-kit) provides “host” versions of all the Debian essential and build-essential tools, so those SHOULD NOT be listed in the package build dependencies.

== Changelog: debian/changelog ==

The main difference between Maemo and Debian changelogs is that Maemo uses a different Bugzilla bug tracking system (and there are actually two of them). While bug fixes in Debian are marked with a “Closes:” entry in the changelog, in Maemo they are marked with “Fixes:”. A Bug ID of the form of NB#xxxx refers to the Nokia internal BTS and MB#xxxx refers to the public Maemo BTS. These are used for automated tracking of bug state changes.

The distribution and urgency fields in changelog are currently ignored.

== Main building script: debian/rules ==

=== DEB_BUILD_OPTIONS ===

The DEB_BUILD_OPTIONS environment variable can be used to control certain features when building packages. If a package supports a feature discussed below, it MUST use the given option for controlling enabling of that feature.

Options currently used by the Maemo build infrastructure:

'''thumb''' 
* Maemo5: SHOULD NOT be used. The Omap3 version used in it has broken thumb support.

'''vfp''' 
* Maemo 5: Enabled by default.

'''nolauncher''' 
:Request application to be built without maemo-launcher support. Note that if an application supports maemo-launcher, it should be enabled by default, as it makes the application start up significantly faster and saves memory.

'''parallel=N'''
:Asks the package to enable GNU Make’s -jN parallel build option to speed up the package build. If this option is not set, the package should be built sequentially (e.g. to save memory).


'''Deprecated options:'''


'''maemo-launcher''' 
:Application should be built with maemo-launcher support. This should now be the default behavior. See the nolauncher option above.

'''softfp''' 
:Use soft floating point. After IT OS 2005, all of the IT OS 2006, 2007 and 2008 toolchains use soft floats by default.


'''nodocs'''
:Asks the package to neither build nor install documentation. Building documentation (especially with gtk-doc) can take a long time and the documentation packages are not needed on the device, only in the development environment. It should be possible to generate the documentation only when needed.

=== Compilation options and stripping ===

The Debian Policy “Binaries” section recommends optimizing and debug symbols: http://www.debian.org/doc/debian-policy/ch-files.html#s10.1

In Maemo these rules are more strict:
* Code MUST be compiled with optimization to produce a faster or smaller executable (unless impossible because of compiler bugs). Generally -O2 or -Os should be used, or -O3 if that works better. If the compiler crashes when full optimization is enabled, -O1 can be used instead.
* If sources are freely available, they MUST be compiled so that the resulting binaries contain debug symbols (-g compiler option(s)).
* The resulting binaries and libraries MUST be stripped and the debug symbols separated to debug symbol files ([[#Debug_packages|and put into -dbg debug packages]]).
* If sources are not available for a library used by another component, or if the full debug information cannot be provided e.g. for contract reasons, that library SHOULD either be compiled with -fno-omit-frame-pointer or provide at least minimal debug symbols so that problems in other components can be debugged through that library.

== Original sources ==

When packaging upstream sources, the original sources SHOULD be provided separately from the debian/ directory (and patches, etc.) in an .orig.tar.gz file.

= Control files and their fields =

== Package control files: debian/control ==

Distribution, priority and urgency fields are currently ignored. To be safe, use optional for priority unless there is a very good reason not to. See the notes for other fields below.

'''Maintainer'''

If an upstream package is modified for Maemo, the Maintainer field MUST be changed from the original (unless the original maintainer also maintains the Maemo package). The original maintainer MAY be marked with the field XSBC-Original-Maintainer.

'''Section'''

See [[#Sections|Sections]].

'''Architecture'''

Architectures currently supported by Maemo are i386 and armel (in addition to any, all and source). 

Note: There is also a Maemo specific XS-scratchbox-architecture field which can have the value uarm to indicate that the package is to be compiled with the uClibc toolchain instead of Glibc. This is used only for building the kernel and initfs, and may be phased out if they switch to using Glibc.

'''Depends'''

Packages MUST depend only on their direct dependencies, which MUST be generated automatically whenever possible (using ${misc:Depends}, ${shlibs:Depends} etc. —see “man debhelper”)

'''Pre-depends'''

Pre-dependencies should be avoided when possible, and any needs SHOULD first be discussed on the maemo-developers mailing list.

''' Standards-Version '''
The Standards-Version field is for the Debian Policy version (latest is v3.7.2.2). 


'''Installed-Size'''

Note that a package may take less space than indicated by this (automatically calculated) field if the UBIFS or JFFS-2 filesystem is able to compress the files.


'''Maemo extensions:'''
* XB-Maemo-Icon-26: 48x48 pixel icon of the application. The icon has to be png-based and base64-encoded.
* XSBC-Bugtracker: Link to a valid bugtracker. Requirement for promotion to maemo.org extras repository.
* XB-Maemo-Display-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.
* XB-Maemo-Upgrade-Description: Describes, what has changed in an upgraded version.

= Package maintainer scripts and installation procedure =

== Differences between scratchbox and device environments ==

Maintainer scripts MUST take into account the differences of the device and scratchbox environments, and behave sensibly in both. The differences SHOULD NOT cause unnecessary warnings to be printed.

If a script needs to detect whether it is running in scratchbox, currently one way to do so is to test the presence of /targets/links/scratchbox.config (although this is not guaranteed to work in future versions of scratchbox). init.d scripts MUST either be invoked using invoke-rc.d, or only run directly if the status returned by policy-rc.d allows it. (In practice the policy is such that services will not be started in scratchbox.)

GConf values need to be handled directly in scratchbox, since gconfd (or D-Bus which is used for communicating with gconfd) is not running. Please also note the shell commands available for scripts, as discussed in sections 3.7 (Essential packages) and 10.3 (Scripts).


=== Lifeguard reboots ===

Note that the lifeguard will reboot Maemo devices if certain processes exit. Packages must take care that they do not cause such reboots during installation (either by restarting a service or by causing clients of a service to exit), as this could result in a broken package database. (This is mainly an issue for upgrades or replacements for system packages, as no others are watched by the lifeguard by default.) Package installation and upgrades MUST be tested in a live system (on an actual device).

== Controlling terminal for maintainer scripts ==

Maintainer scripts do not have a controlling terminal when running on the device, and are only able to interact with the user through a GUI tool. See [[#Prompting in maintainer scripts|Prompting in maintainer scripts]]).

= The operating system =

== File system hierarchy ==

Due to the problem of not having enough space on the root-partition, please consider to use the <code>maemo-optify</code> script. This is needed for packages larger than 500 kB to be promoted to the maemo.org extras-repository.

== Users and groups ==

The “user” account has the UID and GID 29999 in Maemo. The base useradd utility does not handle policy issues (the adduser wrapper is not available in Maemo), and therefore dynamically added users and groups (including system users) currently go into the 30000–59999 range which is reserved in Debian. There is currently no decision to change this, but the numeric ID’s should not be depended on in any way.

To maintain compatibility, packages MUST NOT allocate UID’s or GID’s in the global 0–99 and 60000–64999 ranges except as allowed in Debian.


== Console messages from init.d scripts ==

Maemo has no strict requirements or policy for console messages, as the user does not normally see them. For consistency (and special circumstances such as debugging) it’s still recommended that packages follow the guidelines of the Debian Policy.

== Cron jobs ==

Currently cron is not available in Maemo.

== Menus ==

Applications in Maemo are listed in the application menu if they provide a .desktop file in the <code>/usr/share/applications/hildon</code> directory. Files added to or removed from this directory are detected automatically.

== Multimedia handlers ==

Maemo uses the freedesktop.org standards for registering MIME types and handlers. Please see [[Documentation/Maemo_5_Developer_Guide/Application_Development/MIME_type_mapping|MIME type documentation]] for an example. But be aware, that there is a [https://bugs.maemo.org/show_bug.cgi?id=6263 bug in Fremantle].

The MIME utilities from the xdg-utils package are not available in Maemo.

= Files =

== Binaries ==

As in Debian, but note the policy on build options, optimization and stripping in sections [[#Main building script: debian/rules|Main building script: debian/rules]] and [[#Compilation options and stripping|Compilation options and stripping]].

== Libraries ==

Note the [[#Library and program packages|guideline on libraries]].

== Scripts ==

The <code>/bin/sh</code> on Maemo devices is provided by BusyBox, and (unlike in Debian) the Bash shell is not available by default. Therefore, all shell scripts MUST work with a POSIX compatible shell.

Perl scripts SHOULD be replaced with POSIX compatible shell scripts if possible. (If a package has to use perl scripts, it MUST depend on <code>perl-base</code>, as noted in [[#Essential packages|Essential packages]]).

== Configuration files ==

Applications that store configuration options elsewhere in the user’s home directory than in $HOME/MyDocs SHOULD add a configuration file telling the Maemo backup system what data needs to be backed up and restored. If the application’s configuration file format changes between releases, its restore script needs to be able to handle the older format appropriately. <!-- See [[Maemo Tutorial]] for more information. (which Maemo tutorial?) -->

Note that user configuration files under $HOME, and all GConf settings except defaults set in schemas, are removed if the user restores original device settings using the Control panel.

As also recommended in the Debian Policy, packages SHOULD NOT place files in <code>/etc/skel</code>: there is no good way to make them available to the existing user (and on Maemo devices new users are normally not created).


== Log files ==

Due to limited space, log files SHOULD be kept minimal if used at all. If a log file causes the device to run out of disk space, it can make the device unusable and force the user to reflash.

Log files should preferably be in a place where the user can remove them (through the UI), and they SHOULD NOT grow without bounds. The logrotate package is not available (and simple rotation is not necessarily enough to limit the size of log files, depending on the logging behavior).

= Customized programs =

== Daemons ==

Maemo devices do not (by default) have any network services or an inetd daemon. Anything installed afterward SHOULD conform to Debian.

== Editors and pagers==

By default the EDITOR or PAGER environment variables do not have a value (and the /usr/bin aliases specified in the Debian Policy do not exist).


= Documentation =

== Manual pages and info documentation ==

Maemo devices do not have the utilities needed for viewing manual or info pages. As [[#Documentation packages|described]], documentation should be packaged separately and installing it should be optional.

== Examples ==

Tests and examples are not needed for running the programs, so they SHOULD be in a separate package which the user does not have to install.


= Appendix =


== DEB_BUILD_OPTIONS examples ==

'''VFP option'''

Add to debian/rules these lines:
 # Use hardware floating point
 ifneq (,$(findstring vfp,$(DEB_BUILD_OPTIONS)))
 CFLAGS += -mfpu=vfp -mfloat-abi=softfp
 endif


= References =

'''Debian Policy''' Debian Policy Manual: http://www.debian.org/doc/debian-policy/

'''Debian New Maintainers’ Guide''' Debian New Maintainer’s Guide: http://www.debian.org/doc/manuals/maint-guide/

'''Debian Social Contract''' Debian Social Contract: http://www.debian.org/social_contract

'''Quick Start Guide''' Maemo Quick Start Guide: http://maemo.org/development/documentation/maemo-quick-start-guide.pdf

'''Maemo Trademark Policy''' Maemo trademark usage: http://maemo.org/intro/trademarks/trademark_usage_guidelines.html

'''[[Documentation | Maemo Documentation]]'''

'''FHS''' Filesystem Hierarchy Standard: http://www.pathname.com/fhs/

'''[[Packaging]]'''

[[Category:Packaging]]