#130 Migrates https://fedoraproject.org/wiki/Common_Rpmlint_issues
Merged 2 months ago by ankursinha. Opened 10 months ago by ankursinha.
fedora-docs/ ankursinha/package-maintainer-docs feat/common-rpmlint-issues  into  main

file modified
+2
@@ -35,3 +35,5 @@ 

  * xref:Upstream_Release_Monitoring.adoc[Upstream Release Monitoring]

  

  * xref:Utilities.adoc[Package Maintenance Utilities]

+ 

+ * xref:CommonRpmlintIssues.adoc[Common Rpmlint issues]

@@ -0,0 +1,228 @@ 

+ = Common Rpmlint issues

+ 

+ This is a collection of information on dealing with rpmlint.

+ Note that the first thing you should do is use the `-e` option to rpmlint so that it provides additional explanatory text.

+ For example:

+ 

+ [source,bash]

+ ----

+ rpmlint -e description-line-too-long

+ 

+ description-line-too-long:

+ Your description lines must not exceed 80 characters. If a line is exceeding

+ this number, cut it to fit in two lines.

+ ----

+ 

+ 

+ The information provided here is not exhaustive.

+ It covers some scenarios for which quick fixes are known.

+ It is also not a "fix-all" for every scenario and should be carefully considered within the context of building your RPM.

+ Some rpmlint warning should not be fixed for some packages, for example warnings about non-standard groups or users, or about setuid executables may be perfectly right for some packages.

+ You can see descriptions of various rpmlint issues in the files installed by package rpmlint under

+ `/usr/lib/python3.12/site-packages/rpmlint/descriptions/`.

+ 

+ For more information on rpmlint project look at

+ link:https://github.com/rpm-software-management/rpmlint[Rpmlint GitHub Project].

+ 

+ [[debuginfo_without_sources]]

+ == debuginfo-without-sources

+ 

+ `rpmlint -e debuginfo-without-sources` provides a good overall picture.

+ See also xref:packaging-guidelines::index.adoc[Compiler Flags].

+ To fix, make sure that debugging symbols are created and that they not are stripped so they are available for rpmbuild post-processing.

+ 

+ [[file_not_utf8]]

+ == file-not-utf8

+ 

+ Indicates that the text encoding of the specified file, usually a documentation file, is not in UTF8.

+ 

+ * Usually fixed by running `iconv` on the uncompressed file before installation.

+   See man page *ICONV(1)*. For example, to recode a file named AUTHORS encoded in latin-1, you can use:

+ 

+ [source,bash]

+ ----

+ iconv -f iso8859-1 -t utf-8 AUTHORS > AUTHORS.conv && mv -f AUTHORS.conv AUTHORS

+ ----

+ 

+ or check the sample at the link:https://fedoraproject.org/wiki/Perl/Tips#file-not-utf8[Perl]

+ packaging tips page and

+ link:https://fedoraproject.org/wiki/Packaging_tricks#Convert_encoding_to_UTF-8[generic tricks] page.

+ 

+ [[hardcoded_library_path]]

+ == hardcoded-library-path

+ 

+ * Don't hardcode path in SPEC.

+   Use xref:packaging-guidelines::RPMMacros.adoc[macros] instead.

+ 

+ 

+ [[incorrect_fsf_address]]

+ == incorrect-fsf-address

+ 

+ * In all cases, upstream should be informed about this.

+ This is the only requirement with respect to this error.

+ 

+ The license file, usually COPYING, must *not* be patched for legal reasons.

+ Other files can be patched if deemed suitable.

+ 

+ 

+ [[incoherent_version_in_changelog]]

+ == incoherent-version-in-changelog

+ 

+ * Check the changelog entries. See also: xref:packaging-guidelines::manual-changelog.adoc[manual changelog guidelines] in the Packaging Guidelines.

+ 

+ [[invalid_license]]

+ == invalid-license

+ 

+ The value of the License tag was not recognized.

+ 

+ * Check xref:packaging-guidelines::LicensingGuidelines.adoc[Licensing guidelines]

+ 

+ [[invalid_soname]]

+ == invalid-soname

+ 

+ The handling of this error depends on ld.so's load path (the "linker

+ path") and whether it refers to a private or public library.

+ 

+ The linker path is `%{_libdir}` + any path listed in `/etc/ld.so.conf` or

+ in a file in `/etc/ld.so.conf.d`.

+ 

+ Public libraries are libs expected to be used by other packages.

+ Other libraries e.g., plugins and functionality internal to the package are private.

+ 

+ We have four cases:

+ 

+ * The library is public.

+   Inform upstream about the issue and propose that they add or fix versioning, possibly by sending a patch.

+   Don't apply the patch until it's merged upstream to avoid upgrade problems.

+ * The library is stored outside the linker path.

+   In this case the error can be ignored.

+ * The library is private and stored in a directory included in the linker path.

+   If possible, move the library to another directory outside the linker path.

+   This might require patching build scripts.

+ * The library is private, stored in a directory included in the linker path and can't be moved.

+   Here, the library must have a name unlikely to clash with other libraries.

+   Consider filtering the Provides: to make sure the private library isn't visible.

+ 

+ The standard way to move a private library is to create a new directory under `%{_libdir}` e.g., `/usr/lib/myapp`.

+ Don't list it in `/etc/ld.so.conf` files!

+ Instead, use a rpath to let the application locate the library.

+ 

+ See also:

+ 

+ * link:#no_soname[no-soname]

+ * http://lists.fedoraproject.org/pipermail/devel/2012-April/166104.html[thread on fedora-devel]

+ 

+ [[no_binary]]

+ == no-binary

+ 

+ The package should be of the noarch architecture because it doesn't contain any binaries.

+ 

+ * Add `BuildArch: noarch` to the SPEC file

+ 

+ 

+ [[no_documentation]]

+ == no-documentation

+ 

+ Indicates that rpmlint could find no files marked as `%doc`. There are

+ several instances where this is acceptable:

+ 

+ * The package really has no documentation.

+   This is rare and in general quite a bad idea; every package should have some sort of documentation and should at least have the text of their license.

+   However, some packages have internal help systems.

+ * All of the documentation was included in a -doc subpackage.

+   This would be rare as most packages should have some license text, a changelog or other information that is better placed in the main package instead of a -doc subpackage.

+ * This is a subpackage and the relevant documentation was included in the main package.

+   This often happens with the -devel subpackage, but you should at least double check to ensure that any of the package's documentation which is intended for developers is included in the -devel subpackage.

+ 

+ [[no_soname]]

+ == no-soname

+ 

+ Indicates that the specified shared library does not have an soname (`DT_SONAME ELF` field).

+ If an executable is linked with a shared object which has a DT_SONAME field, when the executable is run the dynamic linker will attempt to load the shared object specified by the `DT_SONAME` field rather than the using the file name given to the linker.

+ See man page *LD(1)*.

+ 

+ * See the relevant packaging guidelines at xref:packaging-guidelines::index.adoc#_downstream_so_name_versioning[Downstream soname versioning] for information on dealing with this.

+ 

+ See also:

+ 

+ * link:#invalid_soname[invalid-soname]

+ 

+ [[private_shared_object_provides]]

+ == private-shared-object-provides

+ 

+ ----

+ W: python-dulwich.x86_64: W: private-shared-object-provides /usr/lib64/python2.6/site-packages/dulwich/_objects.so _objects.so()(64bit)

+ ----

+ 

+ * Many times this can be solved by following the procedure listed on

+ xref:packaging-guidelines::AutoProvidesAndRequiresFiltering.adoc[Packaging guidelines:AutoProvidesAndRequiresFiltering].

+ 

+ [[script_without_shebang]]

+ == script-without-shebang

+ 

+ * You forgot to unset executable bits on files reported by this error.

+   See also: link:https://fedoraproject.org/wiki/Packaging_tricks#Add_shebang[add shebang].

+ 

+ [[spurious_executable_perm]]

+ == spurious-executable-perm

+ 

+ Indicates that a file has the executable bit set while it probably should not.

+ 

+ * Unset the executable bit, for example `chmod -x README.md` in

+ the `%install` section of your spec file.

+ 

+ [[standard_dir_owned_by_package]]

+ == standard-dir-owned-by-package

+ 

+ This package owns a directory that is part of the standard hierarchy,

+ which can lead to default directory permissions or ownerships being

+ changed to something non-standard.

+ 

+ * You should not make Systems standard directory's to belong to your package.

+ 

+ [[unstripped_binary_or_object]]

+ == unstripped-binary-or-object

+ 

+ * Make sure binaries are executable.

+ 

+ [[unused_direct_shlib_dependency]]

+ == unused-direct-shlib-dependency

+ 

+ A binary is linked against a library but doesn't actually call any of the functions in it.

+ This often happens when linking against a library which uses pkgconfig; the pkgconfig file cannot know which specific functions your binary may need to call, so it tells you to link against all of the possibilities.

+ 

+ One fix for packages which use libtool is to put this in your `%build`

+ section after the `%configure` call:

+ 

+ [source,bash]

+ ----

+ sed -i -e 's! -shared ! -Wl,--as-needed\0!g' libtool

+ ----

+ 

+ Another fix for packages which use `%cmake` is to put this before call

+ `%cmake`:

+ 

+ [source,bash]

+ ----

+ export CXXFLAGS="%{optflags} -Wl,--as-needed"

+ ----

+ 

+ [[wrong_file_end_of_line_encoding]]

+ == wrong-file-end-of-line-encoding

+ 

+ The file has incorrect end-of-line encoding, usually caused by creation or modification on a non-Unix system.

+ It could prevent the file from being displayed correctly in certain circumstances.

+ UNIX and Linux use the Line-Feed character , whilst Windows and DOS use both a Carriage Return and Line Feed .

+ 

+ * Strip the Carriage Returns by using `perl` or `sed`, using `dos2unix` is not

+ necessary. See man page *SED(1)*

+ 

+ [source, bash]

+ ----

+ perl -i -pe 's/\r\n/\n/gs'

+ ----

+ 

+ [source, bash]

+ ----

+ sed -i 's/\r$//'

+ ----

There are a few items that do not seem relevant any more, so we can remove those. Also need to check the links to the packaging guidelines. Finally, once this is done, we need to put a redirect in place on the wiki.

This paragraph is ok. But the consequent example of issues is weird. I would rather directly point to rpmlint documentation.

This paragraph is ok. But the consequent example of issues is weird. I would rather directly point to rpmlint documentation.

Sure, makes sense. Where is the rpmlint documentation though? I don't see a link here: 🤔

https://github.com/rpm-software-management/rpmlint

This paragraph is ok. But the consequent example of issues is weird. I would rather directly point to rpmlint documentation.

Sure, makes sense. Where is the rpmlint documentation though? I don't see a link here: 🤔

https://github.com/rpm-software-management/rpmlint

Do we even need to have a link? Right above the -e parameter is explained, and the user can get up-to-date description with that. I would suggest just dropping the explanations. In case there is something useful that is not given by -e, a pull request to improve rpmlint's descriptions would be the correct way to get the extra material included. And you could ask rpmlint upstream to push the descriptions to a webpage, if you think such page is useful.

But if you think these descriptions contain useful information that is not given by -e (perhaps Fedora specific fixes that would not make sense in -e output?), I am fine with having this list also here.

rebased onto 5b0577968381b4aed9cd353c5483be7ac905915e

3 months ago

Thanks for the feedback folks. I've removed all the descriptions which were just repetitions of rpmlint output. I've left a few that do provide some suggestions on how to remedy the issue.

I guess https://fedoraproject.org/wiki/Packaging_tricks can also be migrated, since it's referred to in this document (I can do that next).

PS: I simply merged master into my branch for the PR. I don't think the diff pagure is generating is correct now---I've not touched any files apart from the rpmlint tricks and the nav doc..

rebased onto 23d656fd12c317e97c0dc50301fee6a384c4b974

3 months ago

Thanks, this looks good now. Probably these is still much that could be done with this page, but better to get it imported from Wiki now, and improved later if somebody decides to put some effort here.

Interesting that Pagure gets confused by back and forth merging like you did here. In any case, I had to rebase this pull request before merging, which cleaned up things so that also Pagure web UI now correctly shows the content.

Importing Packaging Tricks sounds like a good idea, great if you can do that!

rebased onto 359b1d4

2 months ago

I'll go ahead and merge this now. I'll see when I can work on the packaging tricks page, but I don't see myself having time to do it in the next few weeks. I'll open an issue so anyone else can also take it on in the meantime.

Pull-Request has been merged by ankursinha

2 months ago

Uh, sorry, I meant to merge this myself earlier, but apparently I only rebased. Good that this is now completed!