Packaging/Guidelines - Revision history

amigadave: wikify section headings

amigadave — Tue, 01 Mar 2011 10:40:03 GMT

wikify section headings

amigadave: /* Sections */ reformat table,add


amigadave — Tue, 01 Mar 2011 10:32:46 GMT
Sections:  reformat table,add <code>

		
		
		
		
		
		
		← Older revision
		Revision as of 10:32, 1 March 2011
		
		Line 85:
Line 85:
 The section of packages in the user segment MUST be one of the following:  The section of packages in the user segment MUST be one of the following:
  
- {| class="wikitable" + {| class="wikitable sortable"
  + |+ Maemo package sections
  + |-
 ! Key  ! Key
- ! Example English i18n + ! class="unsortable" | Example English i18n
 |-  |-
- | user/desktop + | <code>user/desktop</code>
 | Desktop  | Desktop
 |-  |-
- | user/development + | <code>user/development</code>
 | Programming  | Programming
 |-  |-
- | user/education + | <code>user/education</code>
 | Education  | Education
 |-  |-
- | user/games + | <code>user/games</code>
 | Games  | Games
 |-  |-
- | user/graphics + | <code>user/graphics</code>
 | Graphics  | Graphics
 |-  |-
- | user/multimedia + | <code>user/multimedia</code>
 | Multimedia ''or'' Sound & Video  | Multimedia ''or'' Sound & Video
 |-  |-
- | user/navigation + | <code>user/navigation</code>
 | (Location &) Navigation  | (Location &) Navigation
 |-  |-
- | user/network + | <code>user/network</code>
 | Internet & Networking  | Internet & Networking
 |-  |-
- | user/office + | <code>user/office</code>
 | Office  | Office
 |-  |-
- | user/science + | <code>user/science</code>
 | Science  | Science
 |-  |-
- | user/system + | <code>user/system</code>
 | System  | System
 |-  |-
- | user/utilities + | <code>user/utilities</code>
 | Utilities ''or'' Accessories  | Utilities ''or'' Accessories
- |-  
 |}  |}



dneary: Integrate Graham Cobb's suggestions (with which Daniel agreed). Plus branding update.
dneary — Thu, 29 Apr 2010 21:12:40 GMT
Integrate Graham Cobb's suggestions (with which Daniel agreed). Plus branding update.

		
		
		
		
		
		
		← Older revision
		Revision as of 21:12, 29 April 2010
		
		Line 57:
Line 57:
  
 === Maemo packages that are not yet in Debian ===  === Maemo packages that are not yet in Debian ===
-  
- Open source Maemo software SHOULD include packaging files (the debian/ directory) in the project’s public version control, even if the actual packages would not yet be available in the public Maemo repositories. This helps to make sure that if Debian or some Debian derivative distribution decides to include that software, they have a model for how to package it, and unnecessary differences can be avoided. It also allows other distributions’ maintainers to review and suggest improvements to the packaging.  
  
 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]].  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]].
Line 72:
Line 70:
 '''Upstream package''' A package in the upstream distribution.  '''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 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.
  
  
Line 142:
Line 140:
 == Package naming ==  == 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: + 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  * Created or approved in writing by Nokia Corporation, and
 * Intended to be used only in the Maemo environment (either within Scratchbox or devices)    * 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]. + 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 ==  == The version of a package ==
  
- If an upstream package is re-packaged or otherwise modified for Maemo, a Maemo revision MUST be appended to the upstream revision. The resulting revision string + If an upstream package is re-packaged or otherwise modified for Maemo, the packaging changes MAY be propagated back to upstream.
- SHOULD have the form “RidentifierX” where: +  
  + The resulting revision string SHOULD have the form “RidentifierX” where:
 * R is the upstream revision  * 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. + * 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.  * 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”).    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. + 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:    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:  
Line 178:
Line 177:
 * Version of upstream sources: 0.7  * Version of upstream sources: 0.7
 * Latest package in upstream distribution: 0.6-3  * Latest package in upstream distribution: 0.6-3
- * Package version in maemo: 0.7-0maemo1 + * Package version in Maemo: 0.7-0maemo1
  
 == Package maintenance ==  == Package maintenance ==
Line 201:
Line 200:
 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.  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.) + 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.  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.
Line 243:
Line 242:
 === Debug packages ===  === Debug packages ===
  
- All binary packages which contain executable code SHOULD have a corresponding debug (-dbg) package with debug symbol files for all ELF binaries and shared libraries in the corresponding binary package. Debug symbol files are required 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.   + 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]].  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]].
Line 314:
Line 315:
 == Original sources ==  == 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. (This is not different from Debian but is currently not followed by all Maemo packages. This policy may be changed to a “MUST” severity later, i.e. non-compliant packages will not be accepted.) + 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 =  = Control files and their fields =
Line 324:
Line 325:
 '''Maintainer'''  '''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. + 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'''  '''Section'''
Line 386:
Line 387:
 == Users and groups ==  == 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. + 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.  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.
Line 397:
Line 398:
 == Cron jobs ==  == Cron jobs ==
  
- Currently cron is not available in maemo. + Currently cron is not available in Maemo.
  
 == Menus ==  == Menus ==




amigadave: lots of minor fixes
amigadave — Tue, 27 Apr 2010 10:15:36 GMT
lots of minor fixes

		
		
		
		
		
		
		← Older revision
		Revision as of 10:15, 27 April 2010
		
		Line 26:
Line 26:
  
 In general Maemo packages should follow the Debian policy. However, there are some items where Maemo:  In general Maemo packages should follow the Debian policy. However, there are some items where Maemo:
- * Is more strict because it’s an embedded distribution, aimed at consumer products with more limited resources and also e.g. different legal requirements + * 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  * 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.  * 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 doesn’t provide a utility to check conformance to the additional policies stated in this document. + 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 ==  == Conformance and handling packaging differences ==
Line 38:
Line 38:
 === Guidelines violations ===  === Guidelines violations ===
  
- If a package doesn’t 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:   + 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 package is fixed
 * The Maemo packaging guidelines are updated to accept this exception  * The Maemo packaging guidelines are updated to accept this exception
Line 48:
Line 48:
 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.  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 can’t be fixed now, that should only affect the severity or schedule, and the bug should remain open.) Reasons for WONTFIX could be e.g.: + 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,  * the constraints of the device environment,
 * that changing the current packaging or behavior would break some specific product feature, or  * that changing the current packaging or behavior would break some specific product feature, or
Line 58:
Line 58:
 === Maemo packages that are not yet in Debian ===  === Maemo packages that are not yet in Debian ===
  
- Open source Maemo software SHOULD include packaging files (the debian/ directory) in the project’s public version control, even if the actual packages wouldn’t yet be available in the public Maemo repositories. This helps to make sure that if Debian or some Debian derivative distribution decides to include that software, they have a model for how to package it, and unnecessary differences can be avoided. It also allows other distributions’ maintainers to review and suggest improvements to the packaging. + Open source Maemo software SHOULD include packaging files (the debian/ directory) in the project’s public version control, even if the actual packages would not yet be available in the public Maemo repositories. This helps to make sure that if Debian or some Debian derivative distribution decides to include that software, they have a model for how to package it, and unnecessary differences can be avoided. It also allows other distributions’ maintainers to review and suggest improvements to the packaging.
  
 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]].  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]].
Line 190:
Line 190:
 == Virtual packages ==  == Virtual packages ==
  
- Virtual package names intended for generic use SHOULD be commonly agreed and appear in the list included in the maemo-policy 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). + 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).
  
  
Line 239:
Line 239:
 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]].  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 shouldn’t need to be installed on end-user devices. API documentation for libraries SHOULD be auto-generated from the sources. + 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 packages ===
Line 253:
Line 253:
 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).  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 doesn’t have to be rebuilt (and possibly approved) for a simple configuration change, and the user has less packages to download when upgrading. + 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.
  
  
Line 320:
Line 320:
 == Package control files: debian/control ==  == Package control files: debian/control ==
  
- Distribution, priority and urgency fields are currently ignored. To be safe, use optional for priority unless there’s a very good reason not to. See the notes for other fields below. + 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'''  '''Maintainer'''
Line 334:
Line 334:
 Architectures currently supported by Maemo are i386 and armel (in addition to any, all and source).    Architectures currently supported by Maemo are i386 and armel (in addition to any, all and source).  
  
- Note: There’s 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. + 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'''  '''Depends'''
Line 365:
Line 365:
 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.  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’s 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.) + 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 DBus 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). + 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).
  
  
Line 393:
Line 393:
 == Console messages from init.d scripts ==  == Console messages from init.d scripts ==
  
- Maemo has no strict requirements or policy for console messages, as the user doesn’t normally see them. For consistency (and special circumstances such as debugging) it’s still recommended that packages follow the guidelines of the Debian Policy. + 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 ==  == Cron jobs ==
Line 421:
Line 421:
 == Scripts ==  == Scripts ==
  
- The /bin/sh 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. + 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]]).  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]]).
Line 431:
Line 431:
 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.  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 /etc/skel: there is no good way to make them available to the existing user (and on Maemo devices new users are normally not created). + 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).
  
  
Line 444:
Line 444:
 == Daemons ==  == Daemons ==
  
- Maemo devices don’t (by default) have any network services or an inetd daemon. Anything installed afterward SHOULD conform to Debian. + Maemo devices do not (by default) have any network services or an inetd daemon. Anything installed afterward SHOULD conform to Debian.
  
 == Editors and pagers==  == Editors and pagers==
Line 455:
Line 455:
 == Manual pages and info documentation ==  == Manual pages and info documentation ==
  
- Maemo devices don’t 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. + 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 ==  == Examples ==




amigadave: consistent capitalisation of Maemo, minor fixes
amigadave — Tue, 27 Apr 2010 09:42:58 GMT
consistent capitalisation of Maemo, minor fixes
Show changes


amigadave: /* Debug packages */ use code
amigadave — Tue, 27 Apr 2010 09:29:55 GMT
Debug packages:  use code

		
		
		
		
		
		
		← Older revision
		Revision as of 09:29, 27 April 2010
		
		Line 248:
Line 248:
 All binary packages which contain executable code SHOULD have a corresponding debug (-dbg) package with debug symbol files for all ELF binaries and shared libraries in the corresponding binary package. Debug symbol files are required 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.    All binary packages which contain executable code SHOULD have a corresponding debug (-dbg) package with debug symbol files for all ELF binaries and shared libraries in the corresponding binary package. Debug symbol files are required 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 debug-pkg-check script from the maemo-debug-scripts package can be used to verify debug packages. See also [[#Compilation options and stripping|Compilation options and stripping]]. + 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 ===  === Configuration packages ===




amigadave: formatting changes
amigadave — Mon, 26 Apr 2010 15:00:12 GMT
formatting changes
Show changes


amigadave: /* Compilation options and stripping */ formatting
amigadave — Mon, 26 Apr 2010 14:48:42 GMT
Compilation options and stripping:  formatting

		
		
		
		
		
		
		← Older revision
		Revision as of 14:48, 26 April 2010
		
		Line 310:
Line 310:
  
 === Compilation options and stripping ===  === 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  The Debian Policy “Binaries” section recommends optimizing and debug symbols: http://www.debian.org/doc/debian-policy/ch-files.html#s10.1
  
Line 315:
Line 316:
 * 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.  * 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)).  * 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]]). + * 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.  * 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.
  




amigadave: /* Debug packages */ formatting
amigadave — Mon, 26 Apr 2010 14:44:55 GMT
Debug packages:  formatting

		
		
		
		
		
		
		← Older revision
		Revision as of 14:44, 26 April 2010
		
		Line 248:
Line 248:
  
 === Debug packages ===  === Debug packages ===
- All binary packages which contain executable code SHOULD have a corresponding debug (-dbg) package with debug symbol files for all ELF binaries and shared libraries in the corresponding binary package. +  
- Debug symbol files are required because on ARM (unlike e.g. on x86) optimized binaries or libraries cannot14 be debugged without them. Debug symbols also help in + All binary packages which contain executable code SHOULD have a corresponding debug (-dbg) package with debug symbol files for all ELF binaries and shared libraries in the corresponding binary package. Debug symbol files are required 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.  
- getting more useful performance and memory profiling results.   + 
  
 The debug-pkg-check script from the maemo-debug-scripts package can be used to verify debug packages. See also [[#Compilation options and stripping | Compilation options and stripping]].  The debug-pkg-check script from the maemo-debug-scripts package can be used to verify debug packages. See also [[#Compilation options and stripping | Compilation options and stripping]].




amigadave: /* Purpose */ formatting
amigadave — Mon, 26 Apr 2010 14:23:01 GMT
Purpose:  formatting

		
		
		
		
		
		
		← Older revision
		Revision as of 14:23, 26 April 2010
		
		Line 9:
Line 9:
  
 ==Purpose==  ==Purpose==
- This document describes the general rules agreed for creating Maemo packages. Following them makes package integration + 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
- 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.
- packages in the long run. Conforming packages should also install and behave better + 
- in the users’ devices. + 
  
 For related documents, see:  For related documents, see:

← Older revision		Revision as of 10:32, 1 March 2011
Line 85:		Line 85:
	The section of packages in the user segment MUST be one of the following:		The section of packages in the user segment MUST be one of the following:

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

← Older revision		Revision as of 21:12, 29 April 2010
Line 57:		Line 57:

	=== Maemo packages that are not yet in Debian ===		=== Maemo packages that are not yet in Debian ===
-
-	Open source Maemo software SHOULD include packaging files (the debian/ directory) in the project’s public version control, even if the actual packages would not yet be available in the public Maemo repositories. This helps to make sure that if Debian or some Debian derivative distribution decides to include that software, they have a model for how to package it, and unnecessary differences can be avoided. It also allows other distributions’ maintainers to review and suggest improvements to the packaging.

	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]].		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]].
Line 72:		Line 70:
	'''Upstream package''' A package in the upstream distribution.		'''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 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.


Line 142:		Line 140:
	== Package naming ==		== 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:	+	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		* Created or approved in writing by Nokia Corporation, and
	* Intended to be used only in the Maemo environment (either within Scratchbox or devices)		* 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].	+	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 ==		== The version of a package ==

-	If an upstream package is re-packaged or otherwise modified for Maemo, ~~a Maemo revision MUST~~ be ~~appended~~ to ~~the~~ upstream ~~revision~~. The resulting revision string	+	If an upstream package is re-packaged or otherwise modified for Maemo, the packaging changes MAY be propagated back to upstream.
-	SHOULD have the form “RidentifierX” where:	+
		+	The resulting revision string SHOULD have the form “RidentifierX” where:
	* R is the upstream revision		* 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.	+	* 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.		* 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”).		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.	+	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:		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:
Line 178:		Line 177:
	* Version of upstream sources: 0.7		* Version of upstream sources: 0.7
	* Latest package in upstream distribution: 0.6-3		* Latest package in upstream distribution: 0.6-3
-	* Package version in ~~maemo~~: 0.7-0maemo1	+	* Package version in Maemo: 0.7-0maemo1

	== Package maintenance ==		== Package maintenance ==
Line 201:		Line 200:
	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.		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~~.)	+	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.		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.
Line 243:		Line 242:
	=== Debug packages ===		=== Debug packages ===

-	~~All~~ binary packages ~~which contain executable code SHOULD have a corresponding debug~~ (~~-dbg~~) ~~package with debug~~ symbol files for ~~all ELF binaries and shared libraries~~ in the ~~corresponding binary package~~. Debug symbol files are required 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.	+	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]].		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]].
Line 314:		Line 315:
	== Original sources ==		== 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. ~~(This is not different from Debian but is currently not followed by all Maemo packages. This policy may be changed to a “MUST” severity later, i.e. non-compliant packages will not be accepted.)~~	+	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 =		= Control files and their fields =
Line 324:		Line 325:
	'''Maintainer'''		'''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.	+	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'''		'''Section'''
Line 386:		Line 387:
	== Users and groups ==		== 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.	+	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.		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.
Line 397:		Line 398:
	== Cron jobs ==		== Cron jobs ==

-	Currently cron is not available in ~~maemo~~.	+	Currently cron is not available in Maemo.

	== Menus ==		== Menus ==

← Older revision		Revision as of 10:15, 27 April 2010
Line 26:		Line 26:

	In general Maemo packages should follow the Debian policy. However, there are some items where Maemo:		In general Maemo packages should follow the Debian policy. However, there are some items where Maemo:
-	* Is more strict because ~~it’s~~ an embedded distribution, aimed at consumer products with more limited resources and also e.g. different legal requirements	+	* 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		* 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.		* 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 ~~doesn’t~~ provide a utility to check conformance to the additional policies stated in this document.	+	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 ==		== Conformance and handling packaging differences ==
Line 38:		Line 38:
	=== Guidelines violations ===		=== Guidelines violations ===

-	If a package ~~doesn’t~~ 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:	+	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 package is fixed
	* The Maemo packaging guidelines are updated to accept this exception		* The Maemo packaging guidelines are updated to accept this exception
Line 48:		Line 48:
	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.		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 ~~can’t~~ be fixed now, that should only affect the severity or schedule, and the bug should remain open.) Reasons for WONTFIX could be e.g.:	+	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,		* the constraints of the device environment,
	* that changing the current packaging or behavior would break some specific product feature, or		* that changing the current packaging or behavior would break some specific product feature, or
Line 58:		Line 58:
	=== Maemo packages that are not yet in Debian ===		=== Maemo packages that are not yet in Debian ===

-	Open source Maemo software SHOULD include packaging files (the debian/ directory) in the project’s public version control, even if the actual packages ~~wouldn’t~~ yet be available in the public Maemo repositories. This helps to make sure that if Debian or some Debian derivative distribution decides to include that software, they have a model for how to package it, and unnecessary differences can be avoided. It also allows other distributions’ maintainers to review and suggest improvements to the packaging.	+	Open source Maemo software SHOULD include packaging files (the debian/ directory) in the project’s public version control, even if the actual packages would not yet be available in the public Maemo repositories. This helps to make sure that if Debian or some Debian derivative distribution decides to include that software, they have a model for how to package it, and unnecessary differences can be avoided. It also allows other distributions’ maintainers to review and suggest improvements to the packaging.

	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]].		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]].
Line 190:		Line 190:
	== Virtual packages ==		== Virtual packages ==

-	Virtual package names intended for generic use SHOULD be commonly agreed and appear in the list included in the maemo-policy 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).	+	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).


Line 239:		Line 239:
	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]].		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 ~~shouldn’t~~ need to be installed on end-user devices. API documentation for libraries SHOULD be auto-generated from the sources.	+	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 packages ===
Line 253:		Line 253:
	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).		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 ~~doesn’t~~ have to be rebuilt (and possibly approved) for a simple configuration change, and the user has less packages to download when upgrading.	+	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.


Line 320:		Line 320:
	== Package control files: debian/control ==		== Package control files: debian/control ==

-	Distribution, priority and urgency fields are currently ignored. To be safe, use optional for priority unless ~~there’s~~ a very good reason not to. See the notes for other fields below.	+	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'''		'''Maintainer'''
Line 334:		Line 334:
	Architectures currently supported by Maemo are i386 and armel (in addition to any, all and source).		Architectures currently supported by Maemo are i386 and armel (in addition to any, all and source).

-	Note: ~~There’s~~ 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.	+	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'''		'''Depends'''
Line 365:		Line 365:
	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.		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’s~~ 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.)	+	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 ~~DBus~~ 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).	+	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).


Line 393:		Line 393:
	== Console messages from init.d scripts ==		== Console messages from init.d scripts ==

-	Maemo has no strict requirements or policy for console messages, as the user ~~doesn’t~~ normally see them. For consistency (and special circumstances such as debugging) it’s still recommended that packages follow the guidelines of the Debian Policy.	+	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 ==		== Cron jobs ==
Line 421:		Line 421:
	== Scripts ==		== Scripts ==

-	The /bin/sh 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.	+	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]]).		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]]).
Line 431:		Line 431:
	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.		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 /etc/skel: there is no good way to make them available to the existing user (and on Maemo devices new users are normally not created).	+	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).


Line 444:		Line 444:
	== Daemons ==		== Daemons ==

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

	== Editors and pagers==		== Editors and pagers==
Line 455:		Line 455:
	== Manual pages and info documentation ==		== Manual pages and info documentation ==

-	Maemo devices ~~don’t~~ 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.	+	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 ==		== Examples ==

← Older revision		Revision as of 09:29, 27 April 2010
Line 248:		Line 248:
	All binary packages which contain executable code SHOULD have a corresponding debug (-dbg) package with debug symbol files for all ELF binaries and shared libraries in the corresponding binary package. Debug symbol files are required 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.		All binary packages which contain executable code SHOULD have a corresponding debug (-dbg) package with debug symbol files for all ELF binaries and shared libraries in the corresponding binary package. Debug symbol files are required 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 debug-pkg-check script from the maemo-debug-scripts package can be used to verify debug packages. See also [[#Compilation options and stripping\|Compilation options and stripping]].	+	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 ===		=== Configuration packages ===

← Older revision		Revision as of 14:48, 26 April 2010
Line 310:		Line 310:

	=== Compilation options and stripping ===		=== 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		The Debian Policy “Binaries” section recommends optimizing and debug symbols: http://www.debian.org/doc/debian-policy/ch-files.html#s10.1

Line 315:		Line 316:
	* 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.		* 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)).		* 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]]).	+	* 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.		* 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.

← Older revision		Revision as of 14:44, 26 April 2010
Line 248:		Line 248:

	=== Debug packages ===		=== Debug packages ===
-	All binary packages which contain executable code SHOULD have a corresponding debug (-dbg) package with debug symbol files for all ELF binaries and shared libraries in the corresponding binary package.	+
-	Debug symbol files are required because on ARM (unlike ~~e.g.~~ on x86) optimized binaries or libraries ~~cannot14~~ be debugged without them. Debug symbols also help in	+	All binary packages which contain executable code SHOULD have a corresponding debug (-dbg) package with debug symbol files for all ELF binaries and shared libraries in the corresponding binary package. Debug symbol files are required 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.
-	getting more useful performance and memory profiling results.	+

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

← Older revision		Revision as of 14:23, 26 April 2010
Line 9:		Line 9:

	==Purpose==		==Purpose==
-	This document describes the general rules agreed for creating Maemo packages. Following them makes package integration	+	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
-	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.
-	packages in the long run. Conforming packages should also install and behave better	+
-	in the users’ devices.	+

	For related documents, see:		For related documents, see: