[Debian GNUstep maintainers] Naming convention for GNUstep packages

[Yavor Doganov]

Dear FTP masters,

We at the GNUstep team are writing something like a sub-policy
document (similar to those that already have the Perl/Python/Java and
some other teams) and would like to solicit your opinion regarding the
names of GNUstep packages and the sections they should be placed in.

Since your statements are authoritative, I'd appreciate if you keep
pkg-gnustep-maintainers at lists.alioth.debian.org in the loop when
replying so that we have them public and recorded.  (If that's not
possible for some reason, that's fine too.)

We've had some disputes in the past (circa 20/25 years ago) but I
believe everything is settled now and just needs coordination and
approval from your part, after a civilized discussion.

I'll include the relevant part of our document (sorry for its length)
and needless to say, this is just a proposal.  Only you have the power
to decide, and that's how it should be.

2 Package Types and Names
*************************

There are several different types of GNUstep packages--some of them
traditionally have generic names, a heritage from NeXT/Apple and a
practice that many upstream developers still follow.  With the large set
of packages that Debian provides, it is almost certain that at some
point they would clash with some other non-GNUstep package.  In order to
prevent pollution of the general namespace, the Debian FTP masters have
enforced a certain naming convention, reserving a separate namespace for
GNUstep.  Unfortunately, it is not used consistently and it was never
documented.  This section is an attempt to fix this.

   The first GNUstep packages that were uploaded to Debian matched the
upstream names, that's why the oldest packages lack the ‘.app’ suffix
(‘gnumail’, ‘gworkspace’ or ‘affiche’, to name a few).  Some other
packages have unnecessary suffixes like ‘.tool’ or ‘.framework’, or even
awkward names like ‘addresses-for-gnustep’.

   Here is a description of the package types and package names which
must be used consistently.

Tools
     These are non-GUI (CLI) programs which are linked with
     ‘gnustep-base’ and installed in ‘/usr/bin’ or ‘/usr/sbin’ (or
     ‘/usr/games’ if it is a console-based game).  Tools which are
     written in the C programming language and use ‘gnustep-make’'s
     ‘ctool.make’ also fall in this category.

     The package for a single tool should match the tool name.  It
     shouldn't matter that the tool is written in the Objective-C
     language, C, Perl, Python, etc.  If there is a collision with some
     other package, one of them has to be renamed as is the usual
     practice.

     Good: ‘src:unar’: ‘bin:unar’
     Bad: ‘src:mknfonts.tool’: ‘bin:mknfonts.tool’

     Section: Entirely depends on the tool's purpose--‘unar’ is
     perfectly suitable for section ‘utils’ but a GNUstep-specific tool
     like ‘mknfonts’ should be in section ‘gnustep’.

Applications
     The most common case, GUI programs which link with ‘gnustep-gui’.
     These are installed in ‘/usr/lib/GNUstep/Applications’, with
     ‘/usr/bin/Foo’ or ‘/usr/games/Foo’ being a symlink to
     ‘/usr/lib/GNUstep/Applications/Foo.app/Foo’.  Applications may have
     architecture-independent resources which may be split into a
     separate ‘arch:all’ binary package, or can have bundles
     (extensions) installed under the main app bundle or in the GNUstep
     Bundles/ApplicationSupport directories (‘/usr/lib/GNUstep/Bundles’
     or ‘/usr/lib/GNUstep/ApplicationSupport’).

     All applications must have the ‘.app’ suffix in their source
     package and binary package names.(1)  If there are several binary
     packages, they must follow the established convention that is used
     (almost) consistently for other Debian packages (e.g.,
     ‘.app-common’, ‘.app-data’, ‘.app-sounds’ or other suffix as
     appropriate).  If there is a binary package which is
     architecture-dependent and provides a CLI variant of the program,
     it should not have the ‘.app’ suffix.  If the source package also
     provides a shared library as binary packages, they must follow the
     naming scheme for shared libraries.

     Good: ‘src:adun.app’: ‘bin:adun.app’ and ‘bin:adun-core’
     Bad: ‘src:affiche’: ‘bin:affiche.app’

     Section: If a particular section is suitable, it should be used.
     For example, ‘pikopixel.app’ should be in the ‘graphics’ section,
     ‘fisicalab.app’ in section ‘education’, ‘lusernet.app’ in ‘news’,
     ‘gnumail.app’ in section ‘mail’.  If no section is appropriate or
     if the app is basically closely related to GNUstep
     (‘gworkspace.app’ or ‘systempreferences.app’ being the perfect
     examples for this), use section ‘gnustep’.

Libraries
     Shared libraries must follow all the rules and conventions as
     described in the Debian Policy.  *Note (debian-policy)Shared
     libraries::.  If the library also provides bundles which depend on
     the library's interface (the typical case if the library
     dynamically loads bundles), they must be installed in a versioned
     sub-directory or have a versioned suffix so that installing
     multiple versions of the same library is possible.

     If the library name is unique there is no need to change the source
     package name.  If it is generic or likely to clash with another
     package in the future, prepend ‘gnustep-’.  That is, if the
     upstream name of the library is ‘Performance’, the source package
     name should be ‘gnustep-performance’.

     But this does not solve the collision problem, unfortunately.
     While GNUstep non-library package types have separate namespace,
     clashes could eventually occur for libraries as they have to follow
     the Debian Policy.  Naturally, a distinguished name of the source
     package won't help if a binary package name coincides with another
     package, or if there are file conflicts.  In such rare cases,
     disputes with the maintainer(s) of the conflicting package should
     be resolved following the usual practice.  File conflicts for
     libraries are unlikely to occur as GNUstep libraries are usually
     CamelCase, but package names like ‘libperformance-dev’ look way too
     generic.

     A real example to illustrate a binary package clash is the GNUstep
     CoreGraphics library, named Opal.  While the source package could
     be named ‘gnustep-opal’, according to the Debian Policy the binary
     package name of the ‘-dev’ package should be ‘libopal-dev’.  This
     coincides (or more correctly said, coincided, because it's no
     longer in Debian) with the binary package ‘libopal-dev’ from
     ‘src:opal’, a library used by ‘ekiga’.  There are no file
     conflicts, because the GNUstep library is named Opal, not opal.
     But the binary package names are the same if Policy has to be
     followed, and that's not allowed; it's not even technically
     possible.

     Traditionally, many GNUstep libraries and frameworks append ‘Kit’
     to their names, so in most cases it should be sufficient to
     distinguish them from other libraries if the main name coincides.
     Binary package names for shared libraries are enforced by the
     Debian Policy and thoroughly checked by ‘lintian’, so there is
     little or no room for deviation.

Frameworks
     Frameworks are libraries which can be also dynamically loaded like
     bundles by tools/applications with the ‘NSBundle’ class, or the
     program may link with them as a shared library.  They are installed
     at ‘/usr/lib/GNUstep/Frameworks’ along with a complex and
     convoluted set of symlinks to make them FHS-compliant.  For the
     purpose of Debian packaging, frameworks are considered shared
     libraries and all rules applying to libraries also apply to
     frameworks.

     Good: ‘src:dbuskit’: ‘bin:libdbuskit0’ and ‘bin:libdbuskit-dev’
     Bad: ‘src:popplerkit.framework’, ‘bin:addressview.framework’

     Section: As is the practice with shared libraries in Debian, the
     runtime library must be in ‘libs’ and the package providing the
     headers and the ‘.so’ symlink must be in ‘libdevel’.  If there is a
     separate package providing documentation (whether it is a library
     API reference or a manual), it should be placed in section ‘doc’.

Bundles
     Bundles(2) are shared objects which can be dynamically loaded by
     tools, applications or shared libraries.  Consider them as the
     rough equivalent of dynamically loaded plugins/modules that are
     widely spread nowadays.  The rendering part of the ‘gnustep-gui’
     library (‘gnustep-back’) is built as bundles managed by Debian's
     alternatives system.

     A package providing a system-wide bundle should be named
     ‘src:gnustep-FOO-bundle’, with FOO being a descriptive word,
     ideally matching the upstream name.  The binary package name should
     be the same.  Note that this convention does _not_ apply to
     application bundles; they belong to the respective ‘.app’ (or
     ‘.app-FOO’) package.

     Good: ‘src:gnustep-cddb-bundle’: ‘bin:gnustep-cddb-bundle’
     Bad: ‘src:cddb.bundle’: ‘bin:cddb.bundle’

     Section: System-wide bundles are specific to GNUstep so they should
     be placed in the ‘gnustep’ section.

Services
     Services are special kinds of tools which other running
     applications may use through GNUstep's services facility.  Services
     that are provided by applications can be exposed and made
     accessible with the ‘make_services’ user tool and deserve no
     special mentioning: they are part of the package that is providing
     the application.  There may be system-wide services which are
     packaged separately and installed at ‘/usr/lib/GNUstep/Services’,
     to be shared among applications.  Services are executables that can
     be accessed by any application via its ‘Services’ menu; they are
     not shared objects to be dynamically loaded like bundles.

     A package providing a global system-wide service must be named
     ‘src:gnustep-FOO-service’, with FOO being a descriptive word,
     ideally matching the upstream name.  The binary package name must
     be the same.  System-wide services are only usable within GNUstep
     so the right section is ‘gnustep’, regardless of the functionality
     that the service provides.

Themes
     Themes are bundles which use the ‘GSTheme’ class to change the
     appearance of all GNUstep applications.  They can be compiled or
     architecture-independent (also known as "pixmap themes").

     A package providing a GNUstep theme must be named
     ‘src:gnustep-FOO-theme’, with FOO matching the upstream name.  The
     binary package name must be the same.  Naturally, GNUstep themes
     are strictly GNUstep-specific and should be in section ‘gnustep’.

Palettes
     Palettes are also bundles which provide some GUI-related
     functionality, usually for a specific application or certain set of
     applications.

     There shouldn't be a reason to package a palette separately, they
     are typically distributed as part of an application that enhances
     another application.  In any case, should the need arise, a package
     providing a palette should be named ‘src:gnustep-FOO-palette’ with
     the same binary package name.

   ---------- Footnotes ----------

   (1) Some packages are GUI programs but do not link with the GNUstep
GUI library.  For example, ‘oolite’ is a game that is a GNUstep package
in the general sense, however it is not a _GNUstep application_ and
should not have the ‘.app’ suffix.

   (2) Note that the term "bundle" is widely used within GNUstep and may
have different meanings depending on context.  For example, a ‘.gorm’
file (somewhat confusingly, it is actually a directory containing
several files) is also a bundle.  An application with its resources is
also called an “app bundle”; there are other examples as well.