[draft] Policy: resource files (was: kdelibs 3/4 conflicts, plan)

[Thiago Macieira]

Rex Dieter wrote:
[snip]

I'd like to have a policy file in Techbase that describes how to handle 
resource files that we install all over the place. We need to finish it 
by the KDE 4.0 release and we must comply with it.

This is the initial draft (attached)

-- 
  Thiago Macieira  -  thiago (AT) macieira.info - thiago (AT) kde.org
    PGP/GPG: 0x6EF45358; fingerprint:
    E067 918B B660 DBD1 105C  966C 33F5 F005 6EF4 5358
-------------- next part --------------
Resource Files Policy
=====================

  Rationale
  ---------

    This policy deals with resource files that KDE applications, libraries and
modules install to the filesystem and are loaded or otherwise used at runtime.
This policy is necessary to avoid conflicts among versions of the same program
or between different programs.

  Definitions
  -----------

  Prefix/install prefix:
    The root of the installation, containing subdirs "bin", "lib" and "share".
Each entry in $KDEDIRS is an install prefix.

  Component: 
    A component is each and every KDE block, be it an application, a library, a
module, a KPart, a plugin, etc. This is not strictly tied to the concept of
components in KComponentData, but instead to each logical unit. Each component
is wholly installed in one install prefix.

  Component name:
    A name that uniquely identifies that component inside KDE. It is generally
the application's name, the library's name, etc.

  Highlander Component: 
    (named after the Highlander movies motto of "There can be only one")
    A Highlander component is a component that is unique in the installation.
That is, no other versions of that same component can exist in the same install
prefix. All applications are Highlander components (since you can't install two
applications of the same name in the same "bin" directory).

  Versioned Component:
    It's a pseudo-Highlander component that has a major version name attached
to it. A versioned component is known by its name without the version
number (component name), but takes resources with that version name. Libraries
are always Versioned Components.

  Non-Versioned Component:
    It's a non-Highlander component that has no specific version number
attached to it, but may exist in several versions in the same install prefix.
In general, Non-Versioned Components are specific to one KDE major version
(kde3, kde4, etc.) and are "highlander" inside that version. Plugins, modules
and kparts are Non-Versioned Components.

  Policy
  ------

    The installation of a KDE component must not interfere with the
functionality of other components or other versions of the same non-Highlander
component.

    To accomplish that, the component must decide if the file it is installing
is shared. That is, if the file that it is installing can be read by other
components or other versions of the same component.

    If the file cannot be shared--that is, the file is specific to that version
of the component--it must be installed in a directory that is also specific to
that version of the component, a subdirectory of $prefix/share/apps.

    To determine the name of the directory that is specific to that version of
the component, use the following rule:
    - if the component is Highlander, the directory is the component name;
    - if the component is Versioned, the directory name is the component name
      and its version.
    - if the component is Non-Versioned, the directory name is either prefixed
      by the major KDE version (kde3, kde4, etc.) or suffixed by it (3, 4, etc.)

  Examples
  --------

Application: Konqueror is Highlander
    component name:     konqueror
    executable:         bin/konqueror
    config file:        share/config/konquerorrc
    app-specific dir:   share/apps/konqueror

Library: kdeui is Versioned Component
    component name:     kdeui
    version:            5
    soname:             libkdeui.so.5
    library binary:     lib/libkdeui.so.5, libkdeui.so.5.*
        also:           lib/libkdeui.so   [exception: development file]
    config file:        config/kdeui5rc
    lib-specific dir:   share/apps/kdeui5

KPart: katepart is a Non-Versioned Component
    component name:     katepart
    module binary:      lib/kde4/katepart.so
    config file:        config/katepartrc       [shared configurations]
                        config/katepart4rc  or  [specific configurations]
                        config/kde4/katepartrc
    part-specific dir:  share/apps/katepart4  or
                        share/apps/kde4/katepart

KDE service: kded is Non-Versioned Component
    component name:     kded
    executable:         bin/kded4
    config file:        config/kdedrc           [shared configurations]
                        config/kded4rc          [specific configurations]

Application-specific library: dolphinprivate is Versioned Component
    component name:     dolphinprivate
    version:            1
    soname:             libdolphinprivate.so.1
    library binary:     lib/libdolphinprivate.so.1, libdolphinprivate.so.1.*
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20070803/b78502fa/attachment.sig>