The Mer Wiki now uses your Mer user account and password (create account on https://bugs.merproject.org/)


Packaging guidelines

From Mer Wiki
(Difference between revisions)
Jump to: navigation, search
(Pkgconfig Files)
(begin editing)
 
(2 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
= Packaging Guidelines =
 
= Packaging Guidelines =
  
Guidelines below were adapted for MeeGo from Moblin, OpenSUSE, Fedora and other distributions.
+
Guidelines below were adapted for Mer from MeeGo, OpenSUSE, Fedora and other distributions.
  
 
== Maintaining a Package ==
 
== Maintaining a Package ==
Every package in MeeGo needs a maintainer (AKA owner, bug owner). Any package without an owner will automatically be nominated for deletion from MeeGo. A package maintainer is responsible for making sure that
+
Every package in Mer needs a maintainer (AKA owner, bug owner). A package maintainer is responsible for making sure that
 
* packages are up to date with latest upstream
 
* packages are up to date with latest upstream
* packages consistently build in the MeeGo build system and fix build failures when they occur
+
* packages consistently build in their area of the Mer build system and fix build failures when they occur
 
* package meta data in the RPM spec file is accurate
 
* package meta data in the RPM spec file is accurate
 
* the license of the package is correct
 
* the license of the package is correct
Line 14: Line 14:
 
* she/he Provides information about major changes to other packagers and maintainer to allow enough time for fixing compatibility issues
 
* she/he Provides information about major changes to other packagers and maintainer to allow enough time for fixing compatibility issues
  
Since the data about ownership of packages is not maintained anywhere right now we are starting to use available meta data fields in the build system to track ownership. This will be better integrated and managed at a later point, but to be able to start somewhere MeeGo will use the bugowner key available for every package. We will start adding the metadata about maintainers (bugowners) in the build system and we will have a grace period for this data to be supplied and added to the build system. After the grace period, packages without a maintainer will be reviewed and any packages without a maintainer will be nominated for deletion.
+
Data about ownership of packages is not currently maintained  
 
+
To add yourself as a bugowner of a package, please follow the steps below:
+
* Update to the most recent osc version (0.131) from the MeeGo tools repository. Note: this is essential, since the needed options are not released upstream yet. Tools: http://repo.meego.com/MeeGo/tools/repos/
+
* Identify the packages  of which you are the ultimate maintainer
+
* Do the following for every package you maintain in the Trunk:* projects:
+
<code>
+
osc reqms --role bugowner <project> <package> -m "I want to own this because I love this package"
+
</code>
+
* Your request will be sent and someone in release engineering will approve it
+
 
+
 
+
The current status can be seen here: [[Packaging/Maintainers]]
+
  
 
== Package Naming ==
 
== Package Naming ==
Line 35: Line 23:
 
== Version and Release ==
 
== Version and Release ==
  
Package Versions look like : X.Y.Z-R.B
+
Package Versions look like : X.Y.Z-R.C.B
 
* X.Y.Z is the 'Version' number - determined by the source package.
 
* X.Y.Z is the 'Version' number - determined by the source package.
* R is the 'Release' number which is automatically incremented by OBS whenever a source/packaging changes (eg a check-in or request acceptance)
+
* R is the 'Release' number which should be manually incremented by the maintainer whenever a packaging changes (this includes changing a patch)
 +
* C is a number which is incremented by OBS
 
* B is the build number which is incremented when the package is rebuilt due to a dependency change.
 
* B is the build number which is incremented when the package is rebuilt due to a dependency change.
  
Line 51: Line 40:
 
==== Non-Numeric Version ====
 
==== Non-Numeric Version ====
  
We can use letters and tilde into the version tag. We do not use the Release field for this.
+
We can use letters and tilde in the version tag. We do not use the Release field for this.
  
 
Example:
 
Example:
Line 62: Line 51:
  
 
rpmdev-vercmp is a rpm version comparison checker, belongs to package rpmdevtools,  
 
rpmdev-vercmp is a rpm version comparison checker, belongs to package rpmdevtools,  
you need to install it first through zypper.
+
you need to install it first through zypper. (FIXME - not in Mer)
  
 
Version comparison results:
 
Version comparison results:
Line 78: Line 67:
 
</pre>
 
</pre>
  
Note that the ~ comparison order is specific to MeeGo rpm (http://rpm.org/ticket/56).
+
Note that the ~ comparison order is specific to Mer rpm (http://rpm.org/ticket/56).
  
 
=== Release ===
 
=== Release ===
Line 84: Line 73:
 
This field is handled by the build system to be able to manage automated builds. The initial setting in the spec file is used by the build system but in many cases it does not need to be changed.
 
This field is handled by the build system to be able to manage automated builds. The initial setting in the spec file is used by the build system but in many cases it does not need to be changed.
  
There is no need for the %{dist} macro in the release field. This is also handled directly by the build system.
+
The release number should be set to 1 with any version update and increased by one with any change in the packaging (including changes to or addition of patches).
 
+
The release number is set to zero with any version update. It is increased by one with any change in the package.
+
  
 
We can put letters into the version tag, so we do not use the Release field for this. Details can be found above.
 
We can put letters into the version tag, so we do not use the Release field for this. Details can be found above.
  
If you build the package outside of the OBS or if you copy a package then you will of course not get the correct Release or Build values.
+
If you build the package outside of the OBS or if you copy a package then you will of course not get the correct C or Build values.
  
 
== Tags ==
 
== Tags ==
*The ''Packager'' tag should not be used in spec files. The identities of the packagers are evident from the changelog entries. By not using the ''Packager'' tag, you also avoid seeing bad binaries rebuilt by someone else with your name in the header.  See also the '''Maximum RPM definition of the Packager tag''' at [http://www.rpm.org/max-rpm/s1-rpm-inside-tags.html#S3-RPM-INSIDE-PACKAGER-TAG www.rpm.org] .  If you need to include information about the packager in the rpms ''you'' built, use <code>%packager</code> in your <code>~/.rpmmacros</code> instead.
+
* The ''Packager'' tag should not be used in spec files. The identities of the packagers are evident from the changelog entries. By not using the ''Packager'' tag, you also avoid seeing bad binaries rebuilt by someone else with your name in the header.  See also the '''Maximum RPM definition of the Packager tag''' at [http://www.rpm.org/max-rpm/s1-rpm-inside-tags.html#S3-RPM-INSIDE-PACKAGER-TAG www.rpm.org] .  If you need to include information about the packager in the rpms ''you'' built, use <code>%packager</code> in your <code>~/.rpmmacros</code> instead.
 
*The ''Vendor'' tag should not be used. It is set automatically by the build system.
 
*The ''Vendor'' tag should not be used. It is set automatically by the build system.
  
*Usually, the ''Pre<code></code>Req'' tag should be replaced by plain ''Requires''.  For more info, see Maximum RPM snapshot's  [http://www.rpm.org/max-rpm-snapshot/s1-rpm-depend-manual-dependencies.html#S3-RPM-DEPEND-FINE-GRAINED fine grained dependencies chapter] .
+
*Usually, the ''PreReq'' tag should be replaced by plain ''Requires''.  For more info, see Maximum RPM snapshot's  [http://www.rpm.org/max-rpm-snapshot/s1-rpm-depend-manual-dependencies.html#S3-RPM-DEPEND-FINE-GRAINED fine grained dependencies chapter] .
* The ''Source'' tag documents where to find the upstream sources for the rpm.  In most cases this should be a complete URL to the upstream tarball.
+
* The ''Source'' tag documents the container for the upstream sources for the rpm.  In most cases this should be a simple filename as the source should come from the Mer git repositories.
 +
 
 
=== Summary Tag ===
 
=== Summary Tag ===
 
The summary is a single line string describing the package. The maximum length is 80 characters. It should fit all standard situations and not assume any special context. It should be helpful alone, in alphabetically sorted or unsorted lists of some selected packages, and in alphabetically sorted or unsorted lists of all packages.
 
The summary is a single line string describing the package. The maximum length is 80 characters. It should fit all standard situations and not assume any special context. It should be helpful alone, in alphabetically sorted or unsorted lists of some selected packages, and in alphabetically sorted or unsorted lists of all packages.
Line 110: Line 98:
 
=== Group Tag ===
 
=== Group Tag ===
  
The group tag is used to group packages by the types of functionality they provide. In MeeGo the latest group tag are defined in package sepctacle, you can check out in file /usr/share/spectacle/GROUPS.
+
The group tag is used to group packages by the types of functionality they provide. In Mer the latest group tag are defined in package sepctacle, you can check out in file /usr/share/spectacle/GROUPS.
  
Valid RPM Groups are:
+
Valid Mer Core RPM Groups are: (FIXME - tbd)
 
<pre>
 
<pre>
Amusements/Games
 
Amusements/Graphics
 
Applications/Archiving
 
Applications/Communications
 
Applications/Databases
 
Applications/Editors
 
Applications/Emulators
 
Applications/Engineering
 
Applications/File
 
Applications/Internet
 
Applications/Multimedia
 
Applications/Productivity
 
Applications/Publishing
 
Applications/System
 
Applications/Text
 
Development/Debuggers
 
Development/Languages
 
Development/Libraries
 
Development/System
 
Development/Tools
 
 
Documentation
 
Documentation
 
System/Boot
 
System/Boot
System/Console
+
System/Core
System/I18n/Chinese
+
System/Development
System/I18n/Japanese
+
System/I18n/Korean
+
System/Packages
+
 
System/Base
 
System/Base
 
System/Daemons
 
System/Daemons
 
System/Kernel
 
System/Kernel
 
System/Libraries
 
System/Libraries
System/Shells
+
System/Qt
System/X11
+
System/X11/Fonts
+
System/X11/Icons
+
System/GUI/XFCE
+
System/GUI/Other
+
System/GUI/GNOME
+
 
</pre>
 
</pre>
  
==== Domain/Subsystem based RPM Groups ====
 
 
Following the new architecture and the new [http://meego.com/developers/meego-architecture/meego-architecture-domain-view domain view], RPM groups (The Group tag in the RPM) for core packages will be changed to match the domains and any package in the core that is part of one of the domain will have a corresponding group that matches the architecture.
 
 
{|
 
! Domain 
 
! Subsystem 
 
!Groupname
 
|-
 
| Communications  ||  Cellular Adaptation  ||  Communications/Cellular Adaptation
 
|-
 
| Communications  ||  Cellular Framework  ||  Communications/Cellular Framework
 
|-
 
| Communications  ||  Telephony and IM  ||  Communications/Telephony and IM
 
|-
 
| Communications  ||  Bluetooth  ||  Communications/Bluetooth
 
|-
 
| Communications  ||  Connectivity Adaptation  ||  Communications/Connectivity Adaptation
 
|-
 
| Communications  ||  ConnMan  ||  Communications/ConnMan
 
|-
 
| Data Management  ||  Content Framework  ||  Data Management/Content Framework
 
|-
 
| Development Platform  ||  Platform SDK  ||  Development Platform/Platform SDK
 
|-
 
| Essentials  ||  Base Essentials  ||  Essentials/Base Essentials
 
|-
 
| Graphics  ||  Font Management  ||  Graphics/Font Management
 
|-
 
| Graphics  ||  Display and Graphics Adaptation  ||  Graphics/Display and Graphics Adaptation
 
|-
 
| Graphics  ||  Input Adaptation  ||  Graphics/Input Adaptation
 
|-
 
| Graphics  ||  Open GL ES  ||  Graphics/Open GL ES
 
|-
 
| Graphics  ||  X11  ||  Graphics/X11
 
|-
 
| Kernel  ||  Linux Kernel  ||  Kernel/Linux Kernel
 
|-
 
| Location  ||  Location Framework  ||  Location/Location Framework
 
|-
 
| Location  ||  Location Adaptation  ||  Location/Location Adaptation
 
|-
 
| Multimedia  ||  Audio Adaptation  ||  Multimedia/Audio Adaptation
 
|-
 
| Multimedia  ||  Camera Adaptation  ||  Multimedia/Camera Adaptation
 
|-
 
| Multimedia  ||  Gstreamer  ||  Multimedia/Gstreamer
 
|-
 
| Multimedia  ||  Imaging and Video Adaptation  ||  Multimedia/Imaging and Video Adaptation
 
|-
 
| Multimedia  ||  Imaging Codecs  ||  Multimedia/Imaging Codecs
 
|-
 
| Multimedia  ||  PulseAudio  ||  Multimedia/PulseAudio
 
|-
 
| Multimedia  ||  Sharing  ||  Multimedia/Sharing
 
|-
 
| Multimedia  ||  UPnP  ||  Multimedia/UPnP
 
|-
 
| Personal Information Management  ||  Backup Framework  ||  Personal Information Management/Backup Framework
 
|-
 
| Personal Information Management  ||  Calendar Engine  ||  Personal Information Management/Calendar Engine
 
|-
 
| Personal Information Management  ||  Contacts Engine  ||  Personal Information Management/Contacts Engine
 
|-
 
| Personal Information Management  ||  Email Engine  ||  Personal Information Management/Email Engine
 
|-
 
| Personal Information Management  ||  Synchronization Framework  ||  Personal Information Management/Synchronization Framework
 
|-
 
| Qt  ||  Qt  ||  Qt/Qt
 
|-
 
| Qt  ||  Qt Mobility  ||  Qt/Qt Mobility
 
|-
 
| Qt  ||  Qt WebKit  ||  Qt/Qt WebKit
 
|-
 
| Security  ||  Accounts  ||  Security/Accounts
 
|-
 
| Security  ||  Certificate Manager  ||  Security/Certificate Manager
 
|-
 
| Security  ||  Integrity Protection Framework  ||  Security/Integrity Protection Framework
 
|-
 
| Security  ||  Access Control Framework  ||  Security/Access Control Framework
 
|-
 
| Security  ||  Single Sign-On  ||  Security/Single Sign-On
 
|-
 
| Security  ||  SW Distribution Security  ||  Security/SW Distribution Security
 
|-
 
| Security  ||  Security Adaptation  ||  Security/Security Adaptation
 
|-
 
| Software Management  ||  Package Manager  ||  Software Management/Package Manager
 
|-
 
| System  ||  Context Framework  ||  System/Context Framework
 
|-
 
| System  ||  NGF  ||  System/NGF
 
|-
 
| System  ||  Resource Policy  ||  System/Resource Policy
 
|-
 
| System  ||  Sensor Adaptation  ||  System/Sensor Adaptation
 
|-
 
| System  ||  Sensor Framework  ||  System/Sensor Framework
 
|-
 
| System  ||  Startup Services  ||  System/Startup Services
 
|-
 
| System  ||  System Control  ||  System/System Control
 
|-
 
| System  ||  Device Mode Adaptation  ||  System/Device Mode Adaptation
 
|-
 
| System  ||  Vibra and Haptics Adaptation  ||  System/Vibra and Haptics Adaptation
 
|-
 
 
 
|}
 
  
 
=== BuildRoot tag ===
 
=== BuildRoot tag ===
The ''BuildRoot'' value MUST be below <code>%{_tmppath}/</code> and MUST contain at least <code>%{name}</code>, <code>%{version}</code> and <code>%{release}</code>.
+
The BuildRoot tag can be omitted in packages targeting Mer.
 
+
The ''recommended'' values for the ''BuildRoot'' tag are (in descending order of preference) :
+
<pre>
+
%{_tmppath}/%{name}-%{version}-%{release}-root
+
</pre>
+
 
+
The BuildRoot tag can be omitted in packages targeting MeeGo only and is handled directly by rpm in MeeGo, for packages that need to run on other distros with older rpm it should be added for backward compatibility.
+
 
+
=== PreReq ===
+
 
+
Packages should not use the PreReq tag. Once upon a time, in dependency loops PreReq used to "win" over the conventional Requires when RPM determined the installation order in a transaction. This is no longer the case.
+
  
 
=== Explicit Requires ===
 
=== Explicit Requires ===
Line 312: Line 148:
  
 
=== Patches ===
 
=== Patches ===
Each problem should be solved in a separate patch. To allow easy maintenance of patches, every patch should have a header providing the following information:
 
  
* Authors' names
+
Mer packages are moving to be built from git and have 3 base scenarios:
* [http://meego.com/about/contribution-guidelines/signed-process Signed-off-by] tag
+
* Detailed description of the fixed problem
+
* URL of the original source of the patch if any
+
  
The name of a patch file consists of:
+
* upstream uses git and release tarballs correspond to a git tag
 
+
* upstream uses git but release tarballs are modified from git contents
* The name and version of the source tarball from which the patched file is derived
+
* upstream does not use git
* Some words that characterize the patch content
+
* The filename suffix <code class="filename">.patch</code>
+
 
+
Patches are in the unified format (<span>'''diff -u'''</span>) and should be applied with 1 strip level in the spec file (<span>'''%patch -p1'''</span>). The only exceptions are the patches obtained from an another primary source site. The original name, suffix, and format is preserved in this case.
+
 
+
Each patch should be compressed with <span>'''bzip2'''</span> if its size is greater than 100kB. The macros <code class="systemitem">%name</code> and <code class="systemitem">%version</code> should be used whenever possible.
+
 
+
Example:
+
 
+
Source:  %{name}-%{version}.tar.bz2
+
Patch0:  %{name}-%{version}-autoconf.patch
+
Patch1:  %{name}-%{version}-gcc31.patch
+
 
+
For the patches to be applied, the patches should be mentioned under %setup. For the above example, this could be done as
+
 
+
%setup -q
+
%patch0 -p1
+
%patch1 -p1
+
  
 +
For each of these scenarios there may be additional patches applied to the upstream source before it is used in Mer.
  
 
Patches have to be marked as such in the spec file and should be applied using the internal patch routines available in rpm. Use of alternate patch management system not supported by rpm is not allowed.
 
Patches have to be marked as such in the spec file and should be applied using the internal patch routines available in rpm. Use of alternate patch management system not supported by rpm is not allowed.
Line 346: Line 161:
 
=== %clean ===
 
=== %clean ===
  
The %clean section is not required for MeeGo 1.1 and above. Each package for MeeGo 1.0 MUST have a %clean section, which contains rm -rf %{buildroot} (or $RPM_BUILD_ROOT).
+
The %clean section is not required for Mer
  
 
== Documentation ==
 
== Documentation ==
Line 370: Line 185:
  
 
== Test Packages ==
 
== Test Packages ==
Tests should be included in -test subpackage or separate package according to the following guidelines.
+
Tests should be included in -tests subpackage or separate package according to the following guidelines.
 +
 
 +
  * test executables should be installed to /opt/tests/<packagename>/
 +
  * common test data should be installed to /opt/tests/<packagename>/{audio video image etc}
 +
  * test package's test-definition should be installed to /opt/tests/<packagename>/test-definition/
  
[http://wiki.meego.com/Test_Packaging Test Packaging Guidelines]
+
See also ref: [http://wiki.mer.com/Test_Packaging Test Packaging Guidelines]
  
 
== Shared Libraries ==
 
== Shared Libraries ==
Whenever possible (and feasible), MeeGo Packages containing libraries should build them as shared libraries. In addition, every binary RPM package which contains shared library files (not just symlinks) in any of the dynamic linker's default paths, must call ldconfig in <code>%post</code> and <code>%postun</code>. If the package has multiple subpackages with libraries, each subpackage should also have a <code>%post/%postun</code> section that calls <code>/sbin/ldconfig</code>. An example of the correct syntax for this is:
+
Whenever possible (and feasible), Mer Packages containing libraries should build them as shared libraries. In addition, every binary RPM package which contains shared library files (not just symlinks) in any of the dynamic linker's default paths, must call ldconfig in <code>%post</code> and <code>%postun</code>. If the package has multiple subpackages with libraries, each subpackage should also have a <code>%post/%postun</code> section that calls <code>/sbin/ldconfig</code>. An example of the correct syntax for this is:
 
<pre>
 
<pre>
 
%post -p /sbin/ldconfig
 
%post -p /sbin/ldconfig
Line 398: Line 217:
 
As a rule of thumb, use <code>%config(noreplace)</code> instead of plain <code>%config</code> unless your best, educated guess is that doing so will break things.  In other words, think hard before overwriting local changes in configuration files on package upgrades.  An example case when /not/ to use <code>noreplace</code> is when a package's configuration file changes so that the new package revision wouldn't work with the config file from the previous package revision.  Whenever plain <code>%config</code> is used, add a brief comment to the specfile explaining why.
 
As a rule of thumb, use <code>%config(noreplace)</code> instead of plain <code>%config</code> unless your best, educated guess is that doing so will break things.  In other words, think hard before overwriting local changes in configuration files on package upgrades.  An example case when /not/ to use <code>noreplace</code> is when a package's configuration file changes so that the new package revision wouldn't work with the config file from the previous package revision.  Whenever plain <code>%config</code> is used, add a brief comment to the specfile explaining why.
  
Don't use %config or %config(noreplace) under /usr. /usr is deemed to not contain configuration files in MeeGo.
+
Don't use %config or %config(noreplace) under /usr. /usr is deemed to not contain configuration files in Mer.
  
 
== Initscripts ==
 
== Initscripts ==
  
In MeeGo 1.2 and previous version SystemV-style initscripts are supported.
+
In Mer we use [http://en.wikipedia.org/wiki/Systemd Systemd] as system and service manager.
  
In MeeGo 1.3 we use [http://en.wikipedia.org/wiki/Systemd Systemd] as system and service manager.
+
See [[systemd|the systemd page]] for more info
  
 
== Desktop files ==
 
== Desktop files ==
Line 450: Line 269:
 
Name[pt_BR]=Relógios
 
Name[pt_BR]=Relógios
 
Name[zh_CN]=时钟
 
Name[zh_CN]=时钟
Icon=meego-app-clocks
+
Icon=mer-app-clocks
Exec=meego-qml-launcher --opengl --fullscreen --app meego-app-clocks
+
Exec=mer-qml-launcher --opengl --fullscreen --app mer-app-clocks
 
</pre>
 
</pre>
  
Line 505: Line 324:
 
There is very little value in choosing one style over the other, since they will resolve to the same values in all scenarios. You should pick a style and use it consistently throughout your packaging.
 
There is very little value in choosing one style over the other, since they will resolve to the same values in all scenarios. You should pick a style and use it consistently throughout your packaging.
  
Mixing the two styles, while valid, is bad from a QA and usability point of view, and should not be done in MeeGo packages.
+
Mixing the two styles, while valid, is bad from a QA and usability point of view, and should not be done in Mer packages.
  
 
== Handling Locale Files ==
 
== Handling Locale Files ==
Line 515: Line 334:
 
If you don't, your package could fail to generate translation files in the buildroot.
 
If you don't, your package could fail to generate translation files in the buildroot.
  
MeeGo includes an rpm macro called <code>%find_lang</code>. This macro will locate all of the locale files that belong to your package (by name), and put this list in a file. You can then use that file to include all of the locales. <code>%find_lang</code> should be run in the %install section of your spec file, after all of the files have been installed into the buildroot. The correct syntax for <code>%find_lang</code> is usually:
+
Mer includes an rpm macro called <code>%find_lang</code>. This macro will locate all of the locale files that belong to your package (by name), and put this list in a file. You can then use that file to include all of the locales. <code>%find_lang</code> should be run in the %install section of your spec file, after all of the files have been installed into the buildroot. The correct syntax for <code>%find_lang</code> is usually:
 
<pre>
 
<pre>
 
%find_lang %{name}
 
%find_lang %{name}
Line 575: Line 394:
  
 
== Scriptlets ==
 
== Scriptlets ==
Great care should be taken when using scriptlets in MeeGo packages. If scriptlets are used, those scriptlets must be sane.  
+
Great care should be taken when using scriptlets in Mer packages. If scriptlets are used, those scriptlets must be sane.  
  
  
Line 633: Line 452:
 
See [[Spectacle]]
 
See [[Spectacle]]
  
Spectacle is a great tool for straightforward packages, and we have many of those, hundreds, many of those packages already have been using spectacle happily for a while now. Generally, the 80/20 rule applies here, almost 80% of packages in MeeGo can be converted to this format, probably around 20% will need to stay as is for various reasons.
+
Spectacle is a great tool for straightforward packages, and we have many of those, hundreds, many of those packages already have been using spectacle happily for a while now. Generally, the 80/20 rule applies here, almost 80% of packages in Mer can be converted to this format, probably around 20% will need to stay as is for various reasons.
  
 
Spectacle in general helps  a lot when you have a package that does:
 
Spectacle in general helps  a lot when you have a package that does:
Line 660: Line 479:
 
== Modifying existing Packages ==
 
== Modifying existing Packages ==
  
If you base a new package on an existing non-MeeGo package, make sure you verify its correctness of the package  and the spec file and to understand exactly what has been done to package the software exactly. Do not submit a package without knowing what those strange, but innocent-looking commands do.
+
If you base a new package on an existing non-Mer package, make sure you verify its correctness of the package  and the spec file and to understand exactly what has been done to package the software exactly. Do not submit a package without knowing what those strange, but innocent-looking commands do.
  
 
In particular, you should
 
In particular, you should
Line 672: Line 491:
 
* skim the summary and description for typos and oddities (see Summary and description ),
 
* skim the summary and description for typos and oddities (see Summary and description ),
 
* make sure that the correct build root is used,
 
* make sure that the correct build root is used,
* ensure that macro usage is consistent and that the macros are available in MeeGo (see Macros ).  
+
* ensure that macro usage is consistent and that the macros are available in Mer (see Macros ).  
  
 
Keep old changelog entries to credit the original authors. Entries that are several years old or refer to ancient versions of the software may be erased. If you end up doing radical changes and re-write most of the spec file anyway, feel free to start the changelog from scratch. In other words, use your best judgement.
 
Keep old changelog entries to credit the original authors. Entries that are several years old or refer to ancient versions of the software may be erased. If you end up doing radical changes and re-write most of the spec file anyway, feel free to start the changelog from scratch. In other words, use your best judgement.
Line 678: Line 497:
 
== Changelogs ==
 
== Changelogs ==
  
This section describes the MeeGo policy for RPM changelogs. (Original changelogs included in the original source are not affected by this policy.)  
+
This section describes the Mer policy for RPM changelogs. (Original changelogs included in the original source are not affected by this policy.)  
  
 
Please consider that a "normal end user with some technical skills" should be able to read and understand an RPM changelog. Changelog entries have to be in reverse chronological order: newer change log entries are listed above older entries, with the first entry being the most recent.  
 
Please consider that a "normal end user with some technical skills" should be able to read and understand an RPM changelog. Changelog entries have to be in reverse chronological order: newer change log entries are listed above older entries, with the first entry being the most recent.  
  
Please bear in mind that MeeGo changelogs will be automatically parsed to prepare distribution release notes and to report on bugs and CVEs and malformed entries may not be read correctly.
+
Please bear in mind that Mer changelogs will be automatically parsed to prepare distribution release notes and to report on bugs and CVEs and malformed entries may not be read correctly.
  
 
=== General information ===
 
=== General information ===
  
* MeeGo uses a separate file for package changes which is similar to a debian changelog file. This file is named as the spec file, but ends in *.changes instead of *.spec. The %changelog% section must not be used in the .spec file.
+
* Mer uses a separate file for package changes which is similar to a debian changelog file. This file is named as the spec file, but ends in *.changes instead of *.spec. The %changelog% section must not be used in the .spec file.
 
* Entries in the changes file should have the following structure:
 
* Entries in the changes file should have the following structure:
 
<pre>
 
<pre>
* dow mmm dd yyyy Name Goes Here <your@email.com> - [version]
+
* dow mmm dd yyyy Name Goes Here <your@email.com> - [version]-[release]
 
- comment
 
- comment
 
- comment
 
- comment
Line 695: Line 514:
 
</pre>
 
</pre>
  
Note the following exceptions are noted through observation:
+
In future the latest entry in a changelog will be validated.
* version is often omitted (such as: alsa-utils 1.0.15-1 -> 1.0.16-1)
+
* there are multiple changelog entries per version (such as: alsa-utils 1.0.19)
+
* the hyphen between email and version is often omitted (such as: alsa-utils)
+
* spaces between name and <email> are omitted (such as: Zhang, Qiang Z<qiang.z.zhang@intel.com> nano)
+
* name is sometimes omitted (such as: bitstream-vera-fonts nicolas.mailhot at laposte.net)
+
* <email> is sometimes omitted (such as: binutils Jim Kingdon)
+
This wide variation in formats makes automation tasks harder than they should be. Please use the correct format.
+
  
 
=== External References ===
 
=== External References ===
Line 715: Line 527:
 
==== Bug Numbers in the change log ====
 
==== Bug Numbers in the change log ====
  
During maintenance of a distribution, every change has to be marked with the correct bug number. Normally this has to be a number from https://bugs.merproject.org/. Add an entry with bugzilla number and a short description of the bug-summary. For example:
+
During maintenance of a distribution, changes should be marked with the correct bug number. This has to be a number from https://bugs.merproject.org/. Add an entry with bugzilla number and a short description of the bug-summary. For example:
 
  - Removed invalid desktop Category "Application" (MER#4654).
 
  - Removed invalid desktop Category "Application" (MER#4654).
 
  - Symlink icon to pixmaps dir (MER#2108)
 
  - Symlink icon to pixmaps dir (MER#2108)
 
  - Added gnome-ui-properties to control-center (MER#1960).
 
  - Added gnome-ui-properties to control-center (MER#1960).
 
New packages related to new features will refer to the corresponding bug number in bugzilla, preceded with an FEA.  For example:
 
- Adding Qt Contacts support FEA#8011
 
  
 
==== CVE numbers in change log ====
 
==== CVE numbers in change log ====

Latest revision as of 23:20, 13 June 2013

This page has been imported from the meego wiki - it is undergoing adaptation for Mer.

Contents

[edit] Packaging Guidelines

Guidelines below were adapted for Mer from MeeGo, OpenSUSE, Fedora and other distributions.

[edit] Maintaining a Package

Every package in Mer needs a maintainer (AKA owner, bug owner). A package maintainer is responsible for making sure that

  • packages are up to date with latest upstream
  • packages consistently build in their area of the Mer build system and fix build failures when they occur
  • package meta data in the RPM spec file is accurate
  • the license of the package is correct
  • she/he follow upstream for any critical security issues and fix them ASAP
  • she/he Provides information about major changes to other packagers and maintainer to allow enough time for fixing compatibility issues

Data about ownership of packages is not currently maintained

[edit] Package Naming

  • Dash '-' must be used as the delimiter for name parts.
  • Do NOT use an underscore '_', a plus '+', or a period '.' as a delimiter.
  • The spec file should be named using the %{name}.spec scheme which should also correspond to the package name within a project in the build system.

[edit] Version and Release

Package Versions look like : X.Y.Z-R.C.B

  • X.Y.Z is the 'Version' number - determined by the source package.
  • R is the 'Release' number which should be manually incremented by the maintainer whenever a packaging changes (this includes changing a patch)
  • C is a number which is incremented by OBS
  • B is the build number which is incremented when the package is rebuilt due to a dependency change.

[edit] Version

The Version field in the spec file is where you should put the current version of the software being packaged. There are four cases where the version contains non-numeric characters:

  • Pre-release packages: Packages released as "pre-release" versions, prior to a "final" version. Example tags include "alpha", "beta", "rc", "cvs", "git", "svn", etc... Details can be found below: Non-Numeric Version.
  • Post-release packages: Packages released after a "final" version. These packages contain the same numeric version as the "final" version, but have an additional non-numeric identifier. This mechanism may also be used for packaging only changes to an upstream package.
  • Snapshot packages: Packages built from SCM snapshots. These packages could be either "pre" or "post" release packages.

[edit] Non-Numeric Version

We can use letters and tilde in the version tag. We do not use the Release field for this.

Example:

Let's assume the following Qt versions:
Qt 4.7.0~beta1
Qt 4.7.0~beta1+git1
Qt 4.7.0~beta2
Qt 4.7.0

rpmdev-vercmp is a rpm version comparison checker, belongs to package rpmdevtools, 
you need to install it first through zypper. (FIXME - not in Mer)

Version comparison results:
$ rpmdev-vercmp 4.7.0~beta1 4.7.0~beta1+git1
0:4.7.0~beta1+git1-None is newer

$ rpmdev-vercmp 4.7.0~beta1+git2 4.7.0~beta2
0:4.7.0~beta2-None is newer

$ rpmdev-vercmp 4.7.0~beta2 4.7.0
0:4.7.0-None is newer

Conclusion:
4.7.0~beta1 < 4.7.0~beta1+git1 < 4.7.0~beta2 < 4.7.0

Note that the ~ comparison order is specific to Mer rpm (http://rpm.org/ticket/56).

[edit] Release

This field is handled by the build system to be able to manage automated builds. The initial setting in the spec file is used by the build system but in many cases it does not need to be changed.

The release number should be set to 1 with any version update and increased by one with any change in the packaging (including changes to or addition of patches).

We can put letters into the version tag, so we do not use the Release field for this. Details can be found above.

If you build the package outside of the OBS or if you copy a package then you will of course not get the correct C or Build values.

[edit] Tags

  • The Packager tag should not be used in spec files. The identities of the packagers are evident from the changelog entries. By not using the Packager tag, you also avoid seeing bad binaries rebuilt by someone else with your name in the header. See also the Maximum RPM definition of the Packager tag at www.rpm.org . If you need to include information about the packager in the rpms you built, use %packager in your ~/.rpmmacros instead.
  • The Vendor tag should not be used. It is set automatically by the build system.
  • Usually, the PreReq tag should be replaced by plain Requires. For more info, see Maximum RPM snapshot's fine grained dependencies chapter .
  • The Source tag documents the container for the upstream sources for the rpm. In most cases this should be a simple filename as the source should come from the Mer git repositories.

[edit] Summary Tag

The summary is a single line string describing the package. The maximum length is 80 characters. It should fit all standard situations and not assume any special context. It should be helpful alone, in alphabetically sorted or unsorted lists of some selected packages, and in alphabetically sorted or unsorted lists of all packages.

It should describe the package's main function and point out any special properties of the package to support the user comparing similar packages. For example, the two words "Web Browser" summarize any web browser, but using additional adjectives (like minimalistic, complex, GNOME, KDE, text-based, fast, or author's) helps characterize a specific package.

The RPM spec file contains only the English version to keep the RPM database small.

  • The Summary tag value should not end in a period. If this bothers you from a grammatical point of view, sit down, take a deep breath, and get over it.


[edit] Group Tag

The group tag is used to group packages by the types of functionality they provide. In Mer the latest group tag are defined in package sepctacle, you can check out in file /usr/share/spectacle/GROUPS.

Valid Mer Core RPM Groups are: (FIXME - tbd)

Documentation
System/Boot
System/Core
System/Development
System/Base
System/Daemons
System/Kernel
System/Libraries
System/Qt


[edit] BuildRoot tag

The BuildRoot tag can be omitted in packages targeting Mer.

[edit] Explicit Requires

Packages must not contain explicit Requires on libraries except when absolutely necessary. When explicit library Requires are necessary, there should be a spec file comment justifying it.

We generally rely on rpmbuild to automatically add dependencies on library SONAMEs. Modern package management tools are capable of resolving such dependencies to determine the required packages. Explicit dependencies on specific package names may aid the inexperienced user, who attempts at installing RPM packages manually, however, history has shown that such dependencies add confusion when library/files are moved from one package to another, when packages get renamed, when one out of multiple alternative packages would suffice, and when versioned explicit dependencies become out-of-date and inaccurate. Additionally, in some cases, old explicit dependencies on package names require unnecessary updates/rebuilds.

Exemplary rationale for a versioned explicit dependency:

  # The automatic dependency on libfubar.so.1 is insufficient,
  # as we strictly need at least the release that fixes two segfaults.
  Requires: libfubar >= 0:1.2.3-7

Packagers should revisit an explicit dependency as appropriate to avoid it becoming inaccurate and superfluous.

[edit] BuildRequires

In package development and testing, please verify that your package is not missing any necessary build dependencies. Having proper build requirements saves the time of all developers and testers as well as build systems because they will not need to search for missing build requirements manually. It is also a safety feature that prevents builds with that would not otherwise fail, but would be missing crucial features. For example, a graphical application may exclude PNG support after its configure script detects that libpng is not installed.

Before adding BuildRequires to any package, please be comfortable with Requires .

[edit] Patches

Mer packages are moving to be built from git and have 3 base scenarios:

  • upstream uses git and release tarballs correspond to a git tag
  • upstream uses git but release tarballs are modified from git contents
  • upstream does not use git

For each of these scenarios there may be additional patches applied to the upstream source before it is used in Mer.

Patches have to be marked as such in the spec file and should be applied using the internal patch routines available in rpm. Use of alternate patch management system not supported by rpm is not allowed.

[edit]  %clean

The %clean section is not required for Mer

[edit] Documentation

Any relevant documentation included in the source distribution should be included in the package. Irrelevant documentation include build instructions, the omnipresent INSTALL file containing generic build instructions, for example, and documentation for non-Linux systems, e.g. README.MSDOS. Pay also attention about which subpackage you include documentation in, for example API documentation belongs in the -devel subpackage, not the main one. Or if there's a lot of documentation, consider putting it into a subpackage. In this case, it is recommended to use *-doc as the subpackage name, and Documentation as the value of the Group tag.

Also, if a package includes something as %doc, it must not affect the runtime of the application. To summarize: If it is in %doc, the program must run properly if it is not present.

[edit] Devel Packages

If the software being packaged contains files intended solely for development, those files should be put in a -devel subpackage. The following are examples of file types which should be in -devel:

  • Header files (such as .h files)
  • Unversioned shared libraries (such as libfoo.so). Versioned shared libraries (such as libfoo.so.3, libfoo.so.3.0.0) should not be in -devel.

A good rule of thumb is if the file is used for development and not needed for the base package to run properly, it should go in -devel.

[edit] Requiring Base Package

Devel packages must require the base package using a fully versioned dependency: Requires: %{name} = %{version}-%{release}. Usually, subpackages other than -devel should also require the base package using a fully versioned dependency.

[edit] Pkgconfig Files

The placement of pkgconfig(.pc) files depends on their usecase. Since they are almost always used for development purposes, they should be placed in a -devel package. A reasonable exception is when the main package itself is a development tool not installed in a user runtime, such as gcc or gdb. See also http://people.freedesktop.org/~dbn/pkg-config-guide.html

[edit] Test Packages

Tests should be included in -tests subpackage or separate package according to the following guidelines.

 * test executables should be installed to /opt/tests/<packagename>/
 * common test data should be installed to /opt/tests/<packagename>/{audio video image etc}
 * test package's test-definition should be installed to /opt/tests/<packagename>/test-definition/

See also ref: Test Packaging Guidelines

[edit] Shared Libraries

Whenever possible (and feasible), Mer Packages containing libraries should build them as shared libraries. In addition, every binary RPM package which contains shared library files (not just symlinks) in any of the dynamic linker's default paths, must call ldconfig in %post and %postun. If the package has multiple subpackages with libraries, each subpackage should also have a %post/%postun section that calls /sbin/ldconfig. An example of the correct syntax for this is:

%post -p /sbin/ldconfig

%postun -p /sbin/ldconfig

Note that this specific syntax only works if /sbin/ldconfig is the only call in %post and %postun. If you have additional commands to run during the scriptlet, call /sbin/ldconfig at the beginning of the scriptlet, like this:

%post
/sbin/ldconfig
/usr/bin/foo --add

%postun
/sbin/ldconfig
/usr/bin/foo --remove

[edit] Configuration files

Configuration files must be marked as such in packages.

As a rule of thumb, use %config(noreplace) instead of plain %config unless your best, educated guess is that doing so will break things. In other words, think hard before overwriting local changes in configuration files on package upgrades. An example case when /not/ to use noreplace is when a package's configuration file changes so that the new package revision wouldn't work with the config file from the previous package revision. Whenever plain %config is used, add a brief comment to the specfile explaining why.

Don't use %config or %config(noreplace) under /usr. /usr is deemed to not contain configuration files in Mer.

[edit] Initscripts

In Mer we use Systemd as system and service manager.

See the systemd page for more info

[edit] Desktop files

If a package contains a GUI application, then it needs to also include a properly installed .desktop file. For the purposes of these guidelines, a GUI application is defined as any application which draws an X window and runs from within that window. Installed .desktop files MUST follow the desktop-entry-spec , paying particular attention to validating correct usage of Name, GenericName, Categories , StartupNotify entries.

[edit] Icon tag in Desktop Files

The icon tag can be specified in two ways:

  • Full path to specific icon file:

Icon=/usr/share/pixmaps/comical.png

  • Short name without file extension:

Icon=comical

The short name without file extension is preferred, because it allows for icon theming (it assumes .png by default, then tries .svg and finally .xpm), but either method is acceptable.

[edit] .desktop file creation

If the package doesn't already include and install its own .desktop file, you need to make your own. You can do this by including a .desktop file you create as a Source: (such as Source3: %{name}.desktop) or generating it in the spec file. Here are the contents of a sample .desktop file (comical.desktop):

[Desktop Entry]
Name=Comical
GenericName=Comic Archive Reader
Comment=Open .cbr & .cbz files
Exec=comical
Icon=comical
Terminal=false
Type=Application
Categories=Graphics;

[edit] Localizing .desktop files

The values of Name or GenericName are displayed as captions to the graphical desktop icon, so they should be localized according to the Desktop Entry Specification. Most of the time, only language codes or language/country codes are needed to select the intended system locale. For example:

[Desktop Entry]
Type=Application
Name=Clocks
Name[de]=Uhrzeit
Name[es]=Relojes
Name[fr]=Horloges
Name[pt_BR]=Relógios
Name[zh_CN]=时钟
Icon=mer-app-clocks
Exec=mer-qml-launcher --opengl --fullscreen --app mer-app-clocks

In the above .desktop file, [de] specifies the German language locale, covering any German-speaking locale, such as de_DE or de_AT.

Note: Since a language/country code (e.g. pt_BR) is more specific than a language code (e.g. pt), a string for the pt_BR locale will not be used for the Portuguese language locale (pt). If a string is appropriate for every Portuguese locale, you can use "Name[pt]" instead.

[edit] desktop-file-install usage

It is not simply enough to just include the .desktop file in the package, one MUST run desktop-file-install OR desktop-file-validate in %install (and have BuildRequires: desktop-file-utils), to help ensure .desktop file safety and spec-compliance. desktop-file-install MUST be used if the package does not install the file or there are changes desired to the .desktop file (such as add/removing categories, etc). desktop-file-validate MAY be used instead if the .desktop file's content/location does not need modification. Here are some examples of usage:

desktop-file-install                                    \
--dir=${RPM_BUILD_ROOT}%{_datadir}/applications         \
%{SOURCE3}
desktop-file-install                                    \
--add-category="AudioVideo"                             \
--delete-original                                       \
--dir=%{buildroot}%{_datadir}/applications              \
%{buildroot}/%{_datadir}/foo.desktop
desktop-file-validate %{buildroot}/%{_datadir}/applications/foo.desktop

[edit] .desktop file post-install

After installing a .desktop file, it's typical to touch the file and the folder so that the UX will detect the change. Otherwise, the new file will not be detected until reboot. I.e.

  %post
  touch %{_datadir}/applications/foo.desktop
  touch %{_datadir}/applications

...will update the time-stamp of the folder and the .desktop file.

[edit] Macros

[edit] Using %{buildroot} and %{optflags} vs $RPM_BUILD_ROOT and $RPM_OPT_FLAGS

There are two styles of defining the rpm Build Root and Optimization Flags in a spec file:

macro style variable style
Build Root %{buildroot} $RPM_BUILD_ROOT
Opt. Flags %{optflags} $RPM_OPT_FLAGS

There is very little value in choosing one style over the other, since they will resolve to the same values in all scenarios. You should pick a style and use it consistently throughout your packaging.

Mixing the two styles, while valid, is bad from a QA and usability point of view, and should not be done in Mer packages.

[edit] Handling Locale Files

If the package includes translations, add

BuildRequires: gettext

If you don't, your package could fail to generate translation files in the buildroot.

Mer includes an rpm macro called %find_lang. This macro will locate all of the locale files that belong to your package (by name), and put this list in a file. You can then use that file to include all of the locales. %find_lang should be run in the %install section of your spec file, after all of the files have been installed into the buildroot. The correct syntax for %find_lang is usually:

%find_lang %{name}

In some cases, the application may use a different "name" for its locales. You may have to look at the locale files and see what they are named. If they are named myapp.mo, then you will need to pass myapp to %find_lang instead of %{name}. After %find_lang is run, it will generate a file in the active directory (by default, the top level of the source dir). This file will be named based on what you passed as the option to the %find_lang macro. Usually, it will be named %{name}.lang. You should then use this file in the %files list to include the locales detected by %find_lang. To do this, you should include it with the -f parameter to %files.

%files -f %{name}.lang
%defattr(-,root,root,-)
%{_bindir}/foobar
...

If you are already using the -f parameter for the %files section where the locales should live, just append the contents of %{name}.lang to the end of the file that you are already using with -f. (Note that only one file may be used with %files -f.)

Here is an example of proper usage of %find_lang, in foo.spec:

...
%prep
%setup -q

%build
%configure --with-cheese
make %{?_smp_mflags}

%install
make DESTDIR=%{buildroot} install
%find_lang %{name}

%clean
rm -rf %{buildroot}

%files -f %{name}.lang
%defattr(-,root,root,-)
%doc LICENSE README
%{_bindir}/foobar



[edit] Why do we need to use %find_lang?

Using %find_lang helps keep the spec file simple, and helps avoid several other packaging mistakes.

  • Packages that use %{_datadir}/* to grab all the locale files in one line also grab ownership of the locale directories, which is not permitted.
  • Most packages that have locales have lots of locales. Using %find_lang is much easier in the spec file than having to do:
%{_datadir}/locale/ar/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/be/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/cs/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/de/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/es/LC_MESSAGES/%{name}.mo
...
  • As new locale files appear in later package revisions, %find_lang will automatically include them when it is run, preventing you from having to update the spec any more than is necessary.

Keep in mind that usage of %find_lang in packages containing locales is a MUST.

[edit] Scriptlets

Great care should be taken when using scriptlets in Mer packages. If scriptlets are used, those scriptlets must be sane.


[edit] Scriptlets requirements

Do not use the Requires(pre,post) style notation for scriptlet dependencies, because of two bugs in RPM. Instead, they should be split like this:

Requires(pre): ...
Requires(post): ...

For more information, see www.redhat.com .

[edit] Running scriptlets only in certain situations

When the rpm command executes the scriptlets in a package it indicates if the action preformed is an install, erase, upgrade or reinstall by passing an integer argument to the script in question according to the following:

          install   erase   upgrade  reinstall
%pre         1        -         2         2
%post        1        -         2         2
%preun       -        0         1         -
%postun      -        0         1         -

This means that for example a package that installs an init script with the chkconfig command should uninstall it only on erase and not upgrade with the following snippet:

%preun
if [ $1 -eq 0 ] ; then
/sbin/chkconfig --del %{name}
fi

See also /usr/share/doc/rpm-*/triggers, which gives a more formal, generalized definition about the integer value(s) passed to various scripts.

[edit] Scriplets are only allowed to write in certain directories

Build scripts of packages (%prep, %build, %install, %check and %clean) may only alter files (create, modify, delete) under %{buildroot}, %{_builddir} and valid temporary locations like /tmp, /var/tmp (or $TMPDIR or %{_tmppath} as set by the rpmbuild process) according to the following matrix

/tmp, /var/tmp, $TMPDIR, %{_tmppath}  %{_builddir}  %{buildroot}
%prep yes yes no
%build yes yes no
%install yes yes yes
%check yes yes no
%clean yes yes yes

Further clarification: That should hold true irrespective of the builder's uid.

[edit] Use of Epochs

The Epoch tag in RPM is to be used only as a last resort, and should be avoided whenever possible. However, it is sometimes necessary to use an Epoch to handle upstream versioning changes or to ease transition from third party repositories.


[edit] Writing a package from scratch

See Spectacle

Spectacle is a great tool for straightforward packages, and we have many of those, hundreds, many of those packages already have been using spectacle happily for a while now. Generally, the 80/20 rule applies here, almost 80% of packages in Mer can be converted to this format, probably around 20% will need to stay as is for various reasons.

Spectacle in general helps a lot when you have a package that does:

  • configure
  • make
  • make install

and especially useful when for example you have to manage many build dependencies and patches or for common packaging of perl/python/X packages that usually follows the same packaging work flow. We have plans to add lots of nice features to make packaging easier and more fun with spectacle.

While spectacle has many advanced options to cover all kind of corner cases, it should not be used for complex packages that would require lots of customization, especially now that we support multiple architectures and where we need to apply code and custom scripts to support different scenarios.

Spectacle provides scripts to convert spec files to spectacle, those try to do their best but you SHOULD never just take the output as is and rely on the script, a review of the output is necessary, otherwise you might end up with lots of duplication in the spec file. This is the most common mistake, developers are relying on the output of the conversion script, basically picking some spec file from another distro and converting it. This can lead to major disasters in some cases.

So to summarize:

  • It is NOT mandatory to use spectacle
  • If you try to convert and find yourself spending more than a few minutes on a package, then probably there is something wrong and you should not be using that or you should RTFM.
  • Use it with care, especially when you first import the data from existing spec files or when you first create your YAML file
  • Your distro maintainer might send you a note that certain packages you are maintaining could be converted to spectacle easily, but she/he should not reject your package because it does not use spectacle.
  • If you find yourself forced to edit the spec file manually for some reason, then either:
    • your package is not suitable to be used with spectacle
    • or you might want to ask for a feature to support that special case
  • packager should not change packaging format randomly.
    • You need to be the main maintainer
    • If a package is already using the yaml format, you need to have a valid reason why not to use the yaml format

[edit] Modifying existing Packages

If you base a new package on an existing non-Mer package, make sure you verify its correctness of the package and the spec file and to understand exactly what has been done to package the software exactly. Do not submit a package without knowing what those strange, but innocent-looking commands do.

In particular, you should

  • ensure that original tarballs are self-contained pristine tarballs. The tarball should not contain symlinks that reference outside the tarball root directory
  • verify any sources and patches and remove patches or sources that:
    • are related to platforms we do not support (example: sparc, ia64, ppc, ...)
    • Implement features we do not support (example: selinux)
    • Read every patch and understand what it does, if it is needed, put an explanation in the header justifying why the patch is needed.
  • verify that the license stated in the spec file matches the actual license of the software,
  • skim the summary and description for typos and oddities (see Summary and description ),
  • make sure that the correct build root is used,
  • ensure that macro usage is consistent and that the macros are available in Mer (see Macros ).

Keep old changelog entries to credit the original authors. Entries that are several years old or refer to ancient versions of the software may be erased. If you end up doing radical changes and re-write most of the spec file anyway, feel free to start the changelog from scratch. In other words, use your best judgement.

[edit] Changelogs

This section describes the Mer policy for RPM changelogs. (Original changelogs included in the original source are not affected by this policy.)

Please consider that a "normal end user with some technical skills" should be able to read and understand an RPM changelog. Changelog entries have to be in reverse chronological order: newer change log entries are listed above older entries, with the first entry being the most recent.

Please bear in mind that Mer changelogs will be automatically parsed to prepare distribution release notes and to report on bugs and CVEs and malformed entries may not be read correctly.

[edit] General information

  • Mer uses a separate file for package changes which is similar to a debian changelog file. This file is named as the spec file, but ends in *.changes instead of *.spec. The %changelog% section must not be used in the .spec file.
  • Entries in the changes file should have the following structure:
* dow mmm dd yyyy Name Goes Here <your@email.com> - [version]-[release]
- comment
- comment

In future the latest entry in a changelog will be validated.

[edit] External References

Each external reference (bug numbers etc) should be of the form:

"(" + external reference code + bug number +")"

Currently defined:

  • Mer Bugs : MER#
  • Common Vulnerability / Exposure : CVE

[edit] Bug Numbers in the change log

During maintenance of a distribution, changes should be marked with the correct bug number. This has to be a number from https://bugs.merproject.org/. Add an entry with bugzilla number and a short description of the bug-summary. For example:

- Removed invalid desktop Category "Application" (MER#4654).
- Symlink icon to pixmaps dir (MER#2108)
- Added gnome-ui-properties to control-center (MER#1960).

[edit] CVE numbers in change log

As with bug numbers: Add a short description (normally the CVE summary should be enough), the Bugzilla and the CVE number to the changelog entry. Examples:

- Add gdk-pixbuf-226710.patch (MER#226710), and (CVE-2007-0010).
- More XPM fixes: (CVE-2005-2975) xpm too many colors DoS (MER#129642)
- fix ~/.dmrc symlink attack (MER#180704), (CVE-2006-2449)

[edit] Spec File changes

Be as precise as possible! This is especially important if you remove something from the spec file.

  • Removing original source code must be declared in spec file with a comment ("useful for FreeBSD only" for example) - not necessary to repeat the comment in specfile.
  • Extra commands (for example during %install) can be illustrated with a short comment in spec file
  • Adding/Removing packages from Requires/Provides must be described in the changelog

[edit] Source Code changes

Document the most important changes but limit verbosity.

  • look into the source changelog and pick up the most important changes for the distribution (changes for other operation systems are not important). What has changed in the new version, usually in the level of detail of a NEWS file, the change log files are usually too long. More than 10-15 lines shouldn't be necessary to describe the most important changes.
  • arrange the original changes behind the version update information. Example:
 - Update to 1.3.2:
   + fixes memory leak in import function
   + new API command: unlock_client()
   + the following bugs are closed by this new upstream release:
   ++ ............ [MGN:332]
   ++ .............[MGN:337]
 - split of devel package
  • If upstream does not provide a meaningful change log, then only do best effort. Don't waste too much time over it.
  • If the upstream tarball really has not changed except for the version number, just the version number in the change log would be fine. Same goes for packages just containing some graphics or theming (unless upstream already provides something that fits). If the upstream changes just consists of "updated translation" or "several bug fixes" even that can be sufficient for a changelog entry (unless these bug fixes contain something you find worth mentioning).

[edit] Packaging Static Libraries

Packages including libraries should exclude static libs as far as possible (eg by configuring with --disable-static). Static libraries should only be included in exceptional circumstances. Applications linking against libraries should as far as possible link against shared libraries not static versions.

Libtool archives, foo.la files, should not be included. Packages using libtool will install these by default even if you configure with --disable-static, so they may need to be removed before packaging. Due to bugs in older versions of libtool or bugs in programs that use it, there are times when it is not always possible to remove *.la files without modifying the program. In most cases it is fairly easy to work with upstream to fix these issues. Note that if you are updating a library in a stable release (not devel) and the package already contains *.la files, removing the *.la files should be treated as an API/ABI change -- ie: Removing them changes the interface that the library gives to the rest of the world and should not be undertaken lightly.


[edit] Packaging Static Libraries

  • In general, packagers are strongly encouraged not to ship static libs unless a compelling reason exists.
  • We want to be able to track which packages are using static libraries (so we can find which packages need to be rebuilt if a security flaw in a static library is fixed, for instance). There are two scenarios in which static libraries are packaged:
  1. Static libraries and shared libraries. In this case, the static libraries must be placed in a *-static subpackage. Separating the static libraries from the other development files in *-devel allow us to track this usage by checking which packages BuildRequire the *-static package. The intent is that whenever possible, packages will move away from using these static libraries, to the shared libraries.
  2. Static libraries only. When a package only provides static libraries you can place all the static library files in the *-devel subpackage. When doing this you also must have a virtual Provide for the *-static package:
%package devel
Provides: foo-static = %{version}-%{release}

Packages which explicitly need to link against the static version must BuildRequire: foo-static, so that the usage can be tracked.

  • If (and only if) a package has shared libraries which require static libraries to be functional, the static libraries can be included in the *-devel subpackage. The devel subpackage must have a virtual Provide for the *-static package, and packages dependent on it must BuildRequire the *-static package.


[edit] Staticly Linking Executables

  • Static linkage is a special exception and should be decided on a case-by-case basis. The packager must provide rationale for linking statically, including precedences where available, to release engineering for approval.
Personal tools