Packaging/Guidelines - Revision history

imported_>amigadave: wikify section headings

2011-03-01T10:40:03Z

wikify section headings

imported_>amigadave: /* Sections */ reformat table,add


2011-03-01T10:32:46Z
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
|- 
|} |}



imported_>dneary: Integrate Graham Cobb's suggestions (with which Daniel agreed). Plus branding update.
2010-04-29T21:12:40Z
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 ==



imported_>amigadave: lots of minor fixes
2010-04-27T10:15:36Z
lots of minor fixes
Show changes


imported_>amigadave: consistent capitalisation of Maemo, minor fixes
2010-04-27T09:42:58Z
consistent capitalisation of Maemo, minor fixes
Show changes


imported_>amigadave: /* Debug packages */ use code
2010-04-27T09:29:55Z
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 ===



imported_>amigadave: formatting changes
2010-04-26T15:00:12Z
formatting changes
Show changes


imported_>amigadave: /* Compilation options and stripping */ formatting
2010-04-26T14:48:42Z
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.






imported_>amigadave: /* Debug packages */ formatting
2010-04-26T14:44:55Z
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]].



imported_>amigadave: /* Purpose */ formatting
2010-04-26T14:23:01Z
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 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: