From Fedora Project Wiki

No edit summary
Line 27: Line 27:
* Comments that are to be fixed upstream may be relevant in a review request. Don't hesitate to communicate with upstream during the review if an issue that is relevant for upstream has been found out. It may happen that a packages not in shape for inclusion in fedora and requires some work upstream before being imported.
* Comments that are to be fixed upstream may be relevant in a review request. Don't hesitate to communicate with upstream during the review if an issue that is relevant for upstream has been found out. It may happen that a packages not in shape for inclusion in fedora and requires some work upstream before being imported.


== Application binary interface changes (controversial) ==
== Application binary interface changes ==


Application binary interface (ABI) changes in libraries (with a change in soname) should be avoided in fedora releases and done only in rawhide, except when solving a security issue or a very grave bug.
Application binary interface (ABI) changes in libraries (with a change in soname) should be avoided in fedora releases and done only in rawhide, except when solving a security issue or a very grave bug.
Line 37: Line 37:
Some interesting utilities exist for finding differences in ABI, and finding which package provide sonames, <code>rpmsoname</code> and <code>rpmsodiff</code>.
Some interesting utilities exist for finding differences in ABI, and finding which package provide sonames, <code>rpmsoname</code> and <code>rpmsodiff</code>.


== Acceptable use of rpath (recommendation) ==
== Acceptable use of rpath ==


Using rpath for libraries in system library directories is forbiddeen in fedora. It may be acceptable, and even desirable to use rpath for internal libraries that are nevertheless installed (for example to factor out code for different executables). That way it could be avoided to have these libraries installed on system paths. For example the libraries could be installed in:
Using rpath for libraries in system library directories is forbidden in fedora. It may be acceptable, and even desirable to use rpath for internal libraries that are nevertheless installed (for example to factor out code for different executables). That way it could be avoided to have these libraries installed on system paths. For example the libraries could be installed in:


<pre> %{_libdir}/myapp/libmyapp.so.0.3.4 </pre>
<pre> %{_libdir}/myapp/libmyapp.so.0.3.4 </pre>

Revision as of 19:02, 20 July 2008

This page is used to hold packaging related informations that should not be in guidelines (because they are controversial, or because we don't want to inflate the guidelines even more). The guidelines are at PackageMaintainers/MainPagePackaging. A page for common rpmlint issues carries similar recommendations PackageMaintainers/Common Rpmlint Issues. A similar page targetted at multilib issues, with also some hints about keeping timestamps is at PackagingDrafts/MultilibTricks.

Recommendations for review requests

  • Use http://cvs.fedoraproject.org/viewcvs/rpms for checking SPEC file of any packages that are in Fedora. Having a look at other packages can give very interesting insights. However, it should always be remembered that some packages may not be in sync with the current guidelines (and some packages are under review).
  • Run rpmlint on both the SRPM and the binary RPMs before uploading them for review. Look at the output closely and fix those things that need fixing. (Run "rpmlint -i" for additional explanatory information about each issue.) If there are errors where you are unsure if they need fixing mention them in the bugreport and ask for advice. If there are known false-positives mention them, too. Some additional information about common rpmlint errors and how to deal with them is at PackageMaintainers/Common Rpmlint Issues.
  • Increase the "Release" tag every time you upload a new package to avoid confusion. The reviewer and other interested parties probably still have older versions of your SRPM lying around to check what has changed between the old and new packages; those get confused when the revision didn't change.
  • One Review-Bug for one package. Reviewing and tracking multiple packages in one bug is painful. If the packages depend on each other let the bugs block each other (See the fields "Bug ??? depends on:" and "Bug ??? blocks" in bugzilla).
  • List your binary rpms in verbose mode (rpm -qplv filename.rpm) and verify that the included files and directories and their file access permissions are correct. During review there are still too many packages, which install files into a new directory, but don't include the directory itself, or which install files with wrong access permissions (like executable documentation or non-executable shared libraries).

Recommendations for a sane review process

  • Let everybody comment on the review.
  • Comments on items that are not blockers in the guidelines are relevant. The goal of the review is to have good packages, the guidelines are not bureaucratic formal rules, but best packaging practices (and conventions), still they cannot and should not cover everything.
  • Exceptions from guidelines may happen. In that case it may be a good idea to have somebody ask on the relevant lists for help/advice, especially if there is disagreement.
  • Answer questions from all the comments, even those that are not blockers.
  • Even if the review has been accepted, let some time for others to comment if the review was fast.
  • Comments that are to be fixed upstream may be relevant in a review request. Don't hesitate to communicate with upstream during the review if an issue that is relevant for upstream has been found out. It may happen that a packages not in shape for inclusion in fedora and requires some work upstream before being imported.

Application binary interface changes

Application binary interface (ABI) changes in libraries (with a change in soname) should be avoided in fedora releases and done only in rawhide, except when solving a security issue or a very grave bug.

When breaking ABI, it is nice to warn on the fedora-devel-list and especially the package maintainers who depend on your package ABI. Dependent packages may be found using:

 repoquery --arch=src --whatrequires mypackage-devel 

Some interesting utilities exist for finding differences in ABI, and finding which package provide sonames, rpmsoname and rpmsodiff.

Acceptable use of rpath

Using rpath for libraries in system library directories is forbidden in fedora. It may be acceptable, and even desirable to use rpath for internal libraries that are nevertheless installed (for example to factor out code for different executables). That way it could be avoided to have these libraries installed on system paths. For example the libraries could be installed in:

 %{_libdir}/myapp/libmyapp.so.0.3.4 

And have the rpath set to %{_libdir}/myapp/.

Install dlopened objects out of %{_libdir} (controversial)

Objects that are dlopened and not linked against should not be in %{_libdir}, but in a directory below libdir where the application dlopening the object should search for. This is already the setup used by most packages, for example, there is typically a specific directory for plugins containing the dlopened objects.

Use of common namespace

Package files and directory are installed in places where name conflicts are possible. Therefore the file names should be specific of the package. This means avoiding short names (less that 3 or 4 letters), or names that are too generic (like compiler, viewer, show, convert...). The package names also share a common namespace, so should not be generic. It is better to avoid generic names than force the user to change their scripts or modify afterwards the package or utility names, leading to confusion. This is even more problematic when packages or file share the same name but have different functionalities.

There are some packages that already have generic names or have files with generic names. For some packages it is not an issue since they are covered by a standard (like POSIX utilities cat, ls), or have a long history.

The naming guidelines imposes the package naming, so those renaming issues should be tackled with upstream, explaining that in fedora we have to consider a broader perspective of a mix of packages of unknown size. If upstream cannot be convinced, it may be wise to search over the internet for packages that already use that name and think about which one should keep the main name, and a prefix or postfix can be used in fedora if disambiguation is needed.

Avoiding using fedora or redhat in a visible manner in spec files

It is better to avoid using the words fedora or redhat in spec files, to help others wanting to reuse the spec files (be it only in EPEL). dist or distribution can be used instead. For example README.fedora could be called README.dist instead. Of course this doesn't cover internal details like spec file conditionals like %fedora or %rhel.


Examples

If you're including some examples (configurations, source files, whatever), consider installing them in a document subdirectory named "%{_defaultdocdir}/%{name}-%{version}/examples/". As with all documentation, these files should not be directly referenced by any program: they're there for the benefit of the system administrator and users as documentation only. If the entire purpose of a package is to provide examples, then there's no need to bother; consider placing the whole set in %doc instead. This would be consistent with Debian policy guidelines; Fedora doesn't need to follow that, but it's a nice gesture for consistency.

Unfortunately, the implementation of %doc erases all files under the doc directory after the %install and %check stages have run, so using %doc is incompatible with having documentation subdirectories. So to do this, do not use the %doc macro under your %files list. Instead handle documentation files like any other file in %install and %files sections. They will still be identified as documentation files (e.g., rpm -qild PACKAGENAME will still work correctly). E.G.:

%install
...
install -d %{buildroot}/%{_defaultdocdir}/%{name}-%{version}/examples/
cp -p ...normal documents...%{buildroot}/%{_defaultdocdir}/%{name}-%{version}/
cp -p ...examples... %{buildroot}/%{_defaultdocdir}/%{name}-%{version}/examples/
...
%files
...
%{_defaultdocdir}/%{name}-%{version}/
...

Installing TeX files (unvetted)

Here are some things to consider if installing TeX-related files such as LaTeX styles, metafont information, etc. For formal information on fonts, see Packaging/FontsPolicy.

Depend on the virtual packages tex(tex) and tex(latex), not on specific packages like texlive. Fedora has changed its upstream source already, so it seems reasonable to prepare for that again:

Requires:       tex(tex), tex(latex)
BuildRequires:  tex(tex), tex(latex)

For filenames, follow the TeX file installation conventions documented in "info tds" of texlive-texmf. In general, TeX files belong under  %{_datadir}/texmf/TYPE/PACKAGENAME (i.e., it's under /usr/share/texmf). For LaTeX styles the type is "tex/latex".

After installing a metafont file (.mf), you may want to pre-generate the .tfm and *pk font files using mktextfm. (Watch out: You'll need to use mktexfm's --destdir option, and provide pwd and not "." as its option, or the pre-generation won't work if those files are already installed.) For example:

%define latexdir  %{_texmf_main}/tex/latex/%{name}
%define mfdir   %{_texmf_main}/metafont/%{name}
%define tfmdirr %{_texmf_main}/fonts/tfm/%{name}
%define tfmdir  %{tfmdirr}/oxsz
%define pkdirr  %{_texmf_main}/fonts/pk/%{name}
%define pkdir   %{pkdirr}/oxsz
... during %build:
for file in *.mf ; do
 mktextfm --destdir pwd basename $file .mf
done
... during %install:
install -d %{buildroot}%{latexdir}
install -d %{buildroot}%{mfdir}
install -d %{buildroot}%{tfmdir}
install -d %{buildroot}%{pkdir}
cp -p *.sty %{buildroot}%{latexdir}
cp -p tex/*.tfm %{buildroot}%{tfmdir}
cp -p tex/*pk %{buildroot}%{pkdir}
... in %files:
%{latexdir}/
%{mfdir}/
%{tfmdirr}/
%{pkdirr}/

After installing and uninstalling into /usr/share/texmf, run mktexlsr (which replaces texhash). This fixes up the "ls-R" files /usr/share/texmf so that TeX can find files rapidly. You should add "|| :" so that things can continue to work even if the update fails, and you should ensure that the tex(tex) package is installed during %post and %postun, like this:

Requires(post): tex(tex)
Requires(postun): tex(tex)
...
%post
mktexlsr >/dev/null 2>&1 || :
%postun
mktexlsr >/dev/null 2>&1 || :