Note to package maintainers: unowned directories

[Michael Schwendt]

Some package maintainers have asked in private about "unowned directories",
so here is a revised cut'n'paste job of the various replies.

[...]

The background:

  https://fedoraproject.org/wiki/Packaging/ReviewGuidelines

  MUST: A package must own all directories that it creates. If it does not
  create a directory that it uses, then it should require a package which
  does create that directory

[...]

The term "unowned directory" (or "orphaned directory") refers to a
packaging mistake, where

 * a package includes files within a directory it creates,
   but _not_ the directory itself, and

 * none of the package's dependencies provide the directory either,
   and

 * the directory belongs to your package and does not belong to
   any core package or base filesystem package that is considered
   essential/fundamental.


This has several side-effects:

[1] A restrictive superuser umask during package installation
    can create inaccessible directories.
    Scenario: umask 077 ; yum update or rpm -ivh ...

    Symptoms: Run-time problems. For example, unreadable subdirs
    below %_libdir disable plugins. Unreadable subdirs below %_datadir
    prevent application data, help texts, and graphics from being accessed.

    Several sorts of users fix such permission problems with chmod instead
    of taking the time to report it as a bug. It is common belief
    that such bugs are so obvious they would be found by the package
    maintainer or will be reported by other users.

[2] Upon uninstalling the package (or upgrading to another version),
    the old directory is not removed from the file system, because
    in the RPM database it does not belong into the package.
    Especially if directories contain a version number, they clutter
    up the file system with every update which doesn't remove old
    directories.

[3] Unowned/orphaned directories cannot be checked with rpm -V
    and not with rpm -qf either.

[4] Upstream source tarball configuration can fail, because it is
    searched in old and empty versioned header directories, or because
    it is tried to use multiple versioned directories instead of
    just the latest valid one.


Examples of common packaging mistakes in spec %files lists:

[1]

  %{_datadir}/foo/*

  This includes everything _in_ "foo", but not "foo" itself.
  "rpm -qlv pkgname" will show a missing drwxr-xr-x entry for "foo".
  Correct would be

  %{_datadir}/foo/

  to include the directory _and_ the entire tree below it.


[2]

  %{_docdir}/%{name}-%{version}/*

  %{_includedir}/%{name}-%{version}/*.h

  Same as in [1] but creates an additional unowned directory
  everytime %version changes.
  Correct would be:

  %{_docdir}/%{name}-%{version}/

  %dir %{_includedir}/%{name}-%{version}
  %{_includedir}/%{name}-%{version}/*.h


[3]

  %dir %{_libdir}/foo-2/fu
  %dir %{_libdir}/foo-2/bar
  %{_libdir}/foo-2/fu/*.so
  %{_libdir}/foo-2/bar/config*

  Here it is attempted at including the directories explicitly with
  the %dir macro. However, while "bar" is included, "foo-2" is not.
  Typically packagers run into that mistake if all installed files
  are stored only in subdirs of the parent "foo-2" directory.
  Correct would be:

  %dir %{_libdir}/foo-2
  %dir %{_libdir}/foo-2/fu
  %dir %{_libdir}/foo-2/bar
  %{_libdir}/foo-2/fu/*.so
  %{_libdir}/foo-2/bar/config*


[4]

  %{_datadir}/%{name}/db/raw/*.db
  %{_datadir}/%{name}/pixmaps/*.png

  Here only specific data files are included, and all (4!) directories
  below %_datadir are unowned.
  Correct would be:

  %dir %{_datadir}/%{name}
  %dir %{_datadir}/%{name}/db
  %dir %{_datadir}/%{name}/db/raw
  %dir %{_datadir}/%{name}/pixmaps
  %{_datadir}/%{name}/db/raw/*.db
  %{_datadir}/%{name}/pixmaps/*.png


It's easy to find unowned directories with "rpmls" from rpmdevtools or
"rpm -qlv". Just a bit of carefulness is needed to not include core
filesystem directories, such as %_bindir, %_libdir (and obvious others,
e.g. from the "filesystem" pkg) which don't belong into your package.

HTH