Copyright (C) 1999, 2000 by Richard Dawe



Introduction
************

DJGPP has a lot of packages, and is becoming more and more popular.
This is a testament to those who have worked on it & helped with it,
and continue to do so (thanks guys & gals). However, for new users, it
can be tricky to install and configure.  Even for old users, it is
somtimes a lot of hassle to install/remove packages ;) So, it would be
nice to have some (standard) way of simplifying this process. The DJGPP
Software Manifest, hopefully, will allow this.

DJGPP software often comes with a "manifest file", with a file extension
of `.mft', which lists the files contained in the package, and a
"version file", with a file extension of `.ver', which has a brief
description of the package, often containing no more than the name and
version.

It would be useful to have a standard way of describing DJGPP packages,
so that they could be installed/uninstalled/queried by a "package
manager", taking into account any interactions between the packages.
The description would also include more information about the package
than the current manifest & version files do.

Before going any further, the term "package" should be defined in the
context of this specification. A "package" is a compressed archive
containing a file or files describing the package. Thus, the files in
the current DJGPP archive qualify as packages because they contain
manifest and version files.

DJGPP packages are distributed as binaries (pre-compiled), sources
(compilation required) or documentation (reading required).

DJGPP Software Manifest
=======================

The name DJGPP Software Manifest (DSM) has been chosen for the
description.  This is stored in a "DSM file", with a file extension of
`.dsm'. This will provide the following information about a package:

   * Package name, version, type, short and long descriptions;

   * Names of binary, source or documentation DSMs for this package;

   * License, author, organisation, maintainer, porter, mailing list
     and newsgroup information;

   * Home page, download site, location on DJGPP archive;

   * Location of informational files in the package;

   * Dependency of package on other packages, e.g. requirements,
     clashes;

If the package contains a DSM file, it should be stored in either the
top-level directory (the base directory of the archive) or in
`manifest/' off the top-level directory. This ensures that the package
managers can easily find the DSM.

DSM File Syntax
***************

Syntax
======

Directives
----------

A DSM is a plain text file. It describes the package using directives.
A "directive" is a name, consisting only of alphanumeric and hyphen
characters, e.g. `short-description'. A directive takes a single value
and is separated from it by a colon, e.g.:

     short-description: V. short

Directives are single-valued - to have multiple values, the directive
should be used more than once. This is not allowed with all directives.
*Note Multiply-Allowed Directives::. If the directives have some logical
grouping, e.g. when describing package authors, then different
directives are associated by occurrence in the DSM, e.g. the third
`author-email' directive refers the third author's e-mail address.

Line Continuation & Escaping
----------------------------

It may be desirable to have more than one line of data for some of the
directives, e.g. `short-description'. The line continuation character is
a backslash, \. This should be the last non-whitespace character on the
line.

In the informational directives `short-description' and
`long-description', C-style escapes can be used to insert newlines, etc.
into the directive. The following escapes should be supported:

`\n'
     Newline

`\t'
     Tab

`\\'
     Backslash

Formats
-------

The "version number" must be specified as follows:

     <Major>[.<Minor>[.<Subminor>[.<Subsubminor>]]]
     [(alpha <Alpha number>) | (beta <Beta number>)]
     [revision <Revision number>] [patchlevel <Patchlevel number>]
     [snapshot <ISO 8061 hyphenless date>] [platform <Platform specifier>]

The components must be in this order. NB: The versions 1.0.0 and 1.0
may seem to be the same, but are not.

The "ISO 8061 hyphenless date" is specified by `YYYYMMDD', where `YYYY'
is the 4-digit year, `MM' is the 2-digit month number and `DD' is the
2-digit day number (in the month), all padded with zeroes as necessary.

The "platform" is a `<CPU>-<Manufacturer>-<Operating System>' triplet
or `<CPU>-<Manufacturer>-<Kernel>-<Operating System>' quadruplet
describing the hardware & software that the package works on. This
format is used by autoconf for its `--host', `--target' and `--build'
options. For DJGPP the platform is usually `i386-pc-msdosdjgpp'. The CPU
could be `i486', `i586' for Pentium-class CPUs or `i686' for Pentium
II-class CPUs.

Descriptive Directives
======================

DSM Header
----------

The following fields comprise the DSM header:

`dsm-file-version'
     This specifies the revision of this file, e.g. 1, 0.1 - do not
     confuse this with `dsm-version'. This allows the user to check for
     new versions of a package's DSM file.

`dsm-version'
     DSM format version number, e.g. 0.4.0, the version of this
     specification.

`dsm-name'
     DSM name = file name without extension

`dsm-type'
     (binaries|sources|documentation|group|virtual)

The different DSM types are defined as follows:

`binaries'
     The package primarily contains executable programs.

`sources'
     The package primarily contains source code.

`documentation'
     The package primarily contains documentation.

`group'
     The DSM refers to a collection of related packages. This is so
     that, for example, the whole of GNU emacs could be installed by
     referring to its group DSM. A group package is, in a way, a
     meta-package. A group package is implemented by using the
     `requires' directive.

`virtual'
     A virtual package refers to facilities that are outside the domain
     of a package manager, e.g. there could be a virtual package for
     Microsoft Windows.  A virtual package is implemented by using the
     `provides' directive.

The following fields comprise the DSM author information header:

`dsm-author'
     DSM author's name

`dsm-author-email'
     DSM author's e-mail address

`dsm-author-im'
     DSM author's instant messaging details, e.g for ICQ

`dsm-author-web-site'
     DSM author's web site

`dsm-author-ftp-site'
     DSM author's FTP site

These fields are needed because the DSM may not have been written by the
person(s) who made the package.

Information Directives
----------------------

The following fields give more detailed information about the package
itself.  The version information is particularly important.

In the `binaries-dsm', `source-dsm' and `documentation-dsm' fields
below, it is not necessary that the version for those packages will be
the same as for this package, i.e. specified by `version'.

`name'
     This specifies the package name, which cannot contain whitespace.
     Instead use hyphens or underscores.

`version'
     Version number

`manifest'
     Manifest, .mft, file name without extension

`binaries-dsm'
     Binaries DSM name, file name without extension

`sources-dsm'
     Sources DSM name, file name without extension

`documentation-dsm'
     Documentation DSM name, file name without extension

`short-description'
     One line of text

`long-description'
     Multiple lines of text

`license'
     Package's license, e.g. GNU General Public License, BSD License

`organisation'
     e.g. FSF

`author'
     Author's name for this package

`author-email'
     Author's e-mail address

`author-im'
     Author's instant messaging details, e.g. for ICQ

`web-site'
     Home page for the package or author - this should give the
     complete URL, e.g. `http://www.grossprojekt.org/'.

`ftp-site'
     Download site of the package or author - this should give the
     complete URL, e.g. `ftp://ftp.grossprojekt.org/'.

`maintainer'
     Maintainer's name

`maintainer-email'
     Maintainer's e-mail address

`maintainer-im'
     Maintainer's instant messaging details, e.g. for ICQ

`maintainer-web-site'
     Maintainer's home page

`maintainer-ftp-site'
     Maintainer's FTP site

`porter'
     Porter's name

`porter-email'
     Porter's e-mail address

`porter-im'
     Porter's instant messaging details, e.g. for ICQ

`porting-web-site'
     Home page for the port, with complete URL.

`porting-ftp-site'
     Download site for the port, with complete URL.

`mailing-list'
     Mailing list's e-mail address

`mailing-list-description'
     Description of the Mailing list

`mailing-list-request'
     E-mail address to which request subscription requests should be
     sent. Details for how to use this should be on the mailing list's
     web site.

`mailing-list-administrator'
     Mailing list administrator's name

`mailing-list-administrator-email'
     Mailing list administrator's e-mail address

`mailing-list-administrator-im'
     Mailing list administrator's instant messaging details, e.g. for
     ICQ

`mailing-list-web-site'
     Mailing list home page, with complete URL - this should contain
     details of how to join the list.

`mailing-list-ftp-site'
     Mailing list download site, with complete URL.

`newsgroup'
     Newsgroup for the package

`newsgroup-description'
     Description of the newsgroup

`newsgroup-email-gateway'
     This is an e-mail address to send newsgroup items to. The e-mail
     will be converted into a newsgroup posting. An example for DJGPP is
     `djgpp@delorie.com'.

`newsgroup-administrator'
     Newsgroup administrator's name

`newsgroup-administrator-email'
     Newsgroup administrator's e-mail address

`newsgroup-administrator-im'
     Newsgroup administrator's instant messaging details, e.g. for ICQ

`newsgroup-web-site'
     Newsgroup home page, with complete URL.

`newsgroup-ftp-site'
     Newsgroup download site, with complete URL.

Installion & Dependency Directives
==================================

Package Archive Information
---------------------------

`simtelnet-path'
     This is the location of the package's archive in the DJGPP FTP
     structure, e.g. v2tk/ . This is for automatic FTP or HTTP
     downloading by the package manager. The trailing slash is optional.

`zip'
     This specifies the archive file names in preferred order of
     installation. The file extension must be `.zip' and must be
     present in this field.

`tar-gzip'
     This specifies the archive File names in preferred order of
     installation. The file extension must be one of `.tgz', `.taz' or
     `.tar.gz' and must be present in this field.

`changelog'
     This specifies the relative path in the archive to the changelog,
     for use by the package manager.

`pre-install-readme'
     This specifies the relative path in the archive to "readme" file
     for pre-install information.

`post-install-readme'
     This specifies the relative path in the archive to "readme" file
     for post-install information.

`pre-uninstall-readme'
     This specifies the relative path in the archive to "readme" file
     for pre-uninstall information.

`post-uninstall-readme'
     This specifies the relative path in the archive to "readme" file
     for post-uninstall information.

`builtin-pre-install-script'
     [Built-in scripting]

`builtin-post-install-script'
     [Built-in scripting]

`builtin-pre-uninstall-script'
     [Built-in scripting]

`builtin-post-uninstall-script'
     [Built-in scripting]

*Note Scripting:: for a definition of the built-in scripting language.

`pre-install-script'
     [File name, extracted from zip/tgz]

`post-install-script'
     [File name]

`pre-uninstall-script'
     [File name]

`post-uninstall-script'
     [File name]

The script files can be in any scripting language, so long as the
scripting host can be invoked by DOS programs. If this is not the case,
then any DOS package manager will fail to install/uninstall. A
`requires' directive should be used to ensure that the script can be
run.

`prefix'
     If the archive isn't structured to fit into the DJGPP tree, then a
     prefix can be specified to cope with this; e.g. if all the files
     are in the directory `demopkg/' in the archive, the `prefix' could
     be `contrib/' to put them into `contrib/demopkg/' off the DJGPP
     directory. `prefix' should be a relative path. The trailing slash
     is optional.

Dependencies
------------

<Operator> can be any of the C operators  ==, <=, >=, !=, <, >.
Omission of <Operator> implies an equality test. Omission of <Operator>
and <Version> implies any version of the package.

A package does not automatically clash with other versions of itself.

`requires'
     <Package> [[<Operator>] <Version>]
     _or_ <Feature> [[<Operator>] [<Version>]][: <Qualifier>]

`depends-on'
     <Package> [[<Operator>] <Version>]
     _or_ <Feature> [[<Operator>] [<Version>]][: <Qualifier>]
`conflicts-with'
     <Package> [[<Operator>] <Version>]
     _or_ <Feature> [[<Operator>] [<Version>]][: <Qualifier>]

`replaces'
     <Package> [[<Operator>] <Version>]

`duplicate-action'
     (replace|backup|keep|skip|query)

`depends-on' has a different emphasis than `requires'. A package
`requires' another to function *at all*. If it `depends-on' then some
of its functionality may not be available.

The default `duplicate-action' will depend on the installation utility.

`provides'
     <Feature> [[<Operator>] [<Version>]][: <Qualifier>]

The `provides' directive is used to indicate the provision of certain
features by the package. These can then be used in the `requires',
`depends-on' and `conflicts-with' dependencies above. Virtual packages
can use `provides' to indicate features that are available by default,
e.g. the DPMI 0.9 support provided by Windows DOS boxes.

If the package provides only certain parts of a standard, e.g. CWSDPMI's
support of some DPMI 1.0 function calls, then the optional qualifier
can be used to indicate these. It is suggested that these take the form
of `function 0x0501' or `function gethostbyname_r()'. Acronyms should
be written in uppercase. *Note Standard Provisions:: for the 'provides'
defined so far. The use of feature qualifiers should be co-ordinated by
incorporation into this specification.

The feature name is like a package name, and so cannot contain
whitespace - please use hyphens or underscores instead.

`install-before'
     <Package> [[<Operator>] <Version>]

`install-after'
     <Package> [[<Operator>] <Version>]

`install-warning'
     Message

DSM File Structure
==================

   * A group of packages has a DSM entry with a name such as "C
     development" and a list of 'requires' fields.

   * A virtual package has a DSM entry with a name such as "Windows 95"
     and a list of 'provides' fields such as `provides: DPMI 0.9'.


It is recommended that the DSM's author writes their name and contact
details at the start of each DSM as a comment, in addition to the
`dsm-author', etc. fields.

Required Fields
---------------

`dsm-author'

`dsm-file-version'

`dsm-version'

`dsm-name'

`dsm-type'

`name'

`version'

`short-description'

`simtelnet-path'
     This is only needed if it's a binaries, documentation or sources
     package that is actually in (or will be in) the Simtelnet archive.

`zip or tar-gzip'
     This is only needed if it's a binaries, documentation or sources
     package.

Any known `requires', `depends-on', `replaces', `install-before' or
`install-after' dependencies are also required.

Multiply-Allowed Directives
---------------------------

The following directives are allowed multiply:

`author'

`author-email'

`author-im'

`web-site'

`ftp-site'

`maintainer'

`maintainer-email'

`maintainer-im'

`maintainer-web-site'

`maintainer-ftp-site'

`porter'

`porter-email'

`porter-im'

`porter-web-site'

`porter-ftp-site'

`mailing-list'

`mailing-list-description'

`mailing-list-request'

`mailing-list-administrator'

`mailing-list-administrator-email'

`mailing-list-administrator-im'

`mailing-list-web-site'

`mailing-list-ftp-site'

`newsgroup'

`newsgroup-description'

`newsgroup-email-gateway'

`newsgroup-administrator'

`newsgroup-administrator-email'

`newsgroup-administrator-im'

`newsgroup-web-site'

`newsgroup-ftp-site'


`zip'

`tar-gzip'


`requires'

`depends-on'

`conflicts-with'

`replaces'

`provides'

`install-before'

`install-after'
An example is the case where a package has multiple authors:

     author: Fred Bloggs
     author-email: fred.bloggs@bigcorp.co.uk
     author: Ed Wiggins
     author-email: ed.wiggins@bigcorp.co.uk

Scripting
=========

The built-in scripting language isn't intended for complex operations.
For that, external scripting should be used. The following commands are
supported in the `builtin-pre-install-script',
`builtin-post-install-script', `builtin-pre-uninstall-script' and
`builtin-post-uninstall-script' directives.

`echo'
     <Arguments>


     This displays/outputs `Arguments'. This could be used to remind
     the user to read the fine manual.


`command'
     <Program> <Arguments>


     This executes `Program' by passing `Arguments' to it. This could be
     used to run `install-info'  - *Note Texinfo: (texinfo)Invoking
     install-info.


Here is a simple example:

     builtin-post-install-script: command: echo Hello Mum!

Standard Provisions
===================

`DPMI 0.9'

`DPMI 1.0'

`DPMI 1.0: function 0x0506'

`DPMI 1.0: function 0x0507'

`DPMI 1.0: function 0x0508'

`DPMI 1.0: function 0x0509'

`DPMI 1.0: function 0x0E01'

`info-reader'
     This denotes ability to read documentation in info format.

`LFN'
     This denotes the Windows '95 Long FileName API for DOS boxes.

Concept Index
*************

binaries package:
          See ``DSM File Syntax''.
dependency qualification:
          See ``Installion & Dependency Directives''.
dependency qualifier:
          See ``Installion & Dependency Directives''.
directive:
          See ``DSM File Syntax''.
directives:
          See ``DSM File Syntax''.
documentation package:
          See ``DSM File Syntax''.
DSM file:
          See ``Introduction''.
escape characters:
          See ``DSM File Syntax''.
escaping:
          See ``DSM File Syntax''.
feature:
          See ``Installion & Dependency Directives''.
features:
          See ``Installion & Dependency Directives''.
group package:
          See ``DSM File Syntax''.
ISO 8061 date:
          See ``DSM File Syntax''.
line continutation:
          See ``DSM File Syntax''.
manifest file:
          See ``Introduction''.
multiple values:
          See ``DSM File Syntax''.
package:
          See ``Introduction''.
package manager:
          See ``Introduction''.
platform:
          See ``DSM File Syntax''.
sources package:
          See ``DSM File Syntax''.
version file:
          See ``Introduction''.
version number:
          See ``DSM File Syntax''.
virtual package:
          See ``DSM File Syntax''.
Variable Index
**************

author:
          See ``DSM File Syntax''.
author-email:
          See ``DSM File Syntax''.
author-im:
          See ``DSM File Syntax''.
binaries:
          See ``DSM File Syntax''.
binaries-dsm:
          See ``DSM File Syntax''.
builtin-post-install-script:
          See ``Installion & Dependency Directives''.
builtin-post-uninstall-script:
          See ``Installion & Dependency Directives''.
builtin-pre-install-script:
          See ``Installion & Dependency Directives''.
builtin-pre-uninstall-script:
          See ``Installion & Dependency Directives''.
changelog:
          See ``Installion & Dependency Directives''.
command:
          See ``Scripting''.
conflicts-with:
          See ``Installion & Dependency Directives''.
depends-on:
          See ``Installion & Dependency Directives''.
documentation:
          See ``DSM File Syntax''.
documentation-dsm:
          See ``DSM File Syntax''.
DPMI 0.9:
          See ``Standard Provisions''.
DPMI 1.0:
          See ``Standard Provisions''.
DPMI 1.0: function 0x0506:
          See ``Standard Provisions''.
DPMI 1.0: function 0x0507:
          See ``Standard Provisions''.
DPMI 1.0: function 0x0508:
          See ``Standard Provisions''.
DPMI 1.0: function 0x0509:
          See ``Standard Provisions''.
DPMI 1.0: function 0x0E01:
          See ``Standard Provisions''.
dsm-author:
          See ``DSM File Syntax''.
dsm-author-email:
          See ``DSM File Syntax''.
dsm-author-ftp-site:
          See ``DSM File Syntax''.
dsm-author-im:
          See ``DSM File Syntax''.
dsm-author-web-site:
          See ``DSM File Syntax''.
dsm-file-version:
          See ``DSM File Syntax''.
dsm-name:
          See ``DSM File Syntax''.
dsm-type:
          See ``DSM File Syntax''.
dsm-version:
          See ``DSM File Syntax''.
duplicate-action:
          See ``Installion & Dependency Directives''.
echo:
          See ``Scripting''.
ftp-site:
          See ``DSM File Syntax''.
group:
          See ``DSM File Syntax''.
info-reader:
          See ``Standard Provisions''.
install-after:
          See ``Installion & Dependency Directives''.
install-before:
          See ``Installion & Dependency Directives''.
install-warning:
          See ``Installion & Dependency Directives''.
LFN:
          See ``Standard Provisions''.
license:
          See ``DSM File Syntax''.
long-description:
          See ``DSM File Syntax''.
mailing-list:
          See ``DSM File Syntax''.
mailing-list-administrator:
          See ``DSM File Syntax''.
mailing-list-administrator-email:
          See ``DSM File Syntax''.
mailing-list-administrator-im:
          See ``DSM File Syntax''.
mailing-list-description:
          See ``DSM File Syntax''.
mailing-list-ftp-site:
          See ``DSM File Syntax''.
mailing-list-request:
          See ``DSM File Syntax''.
mailing-list-web-site:
          See ``DSM File Syntax''.
maintainer:
          See ``DSM File Syntax''.
maintainer-email:
          See ``DSM File Syntax''.
maintainer-ftp-site:
          See ``DSM File Syntax''.
maintainer-im:
          See ``DSM File Syntax''.
maintainer-web-site:
          See ``DSM File Syntax''.
manifest:
          See ``DSM File Syntax''.
name:
          See ``DSM File Syntax''.
newsgroup:
          See ``DSM File Syntax''.
newsgroup-administrator:
          See ``DSM File Syntax''.
newsgroup-administrator-email:
          See ``DSM File Syntax''.
newsgroup-administrator-im:
          See ``DSM File Syntax''.
newsgroup-description:
          See ``DSM File Syntax''.
newsgroup-email-gateway:
          See ``DSM File Syntax''.
newsgroup-ftp-site:
          See ``DSM File Syntax''.
newsgroup-web-site:
          See ``DSM File Syntax''.
organisation:
          See ``DSM File Syntax''.
porter:
          See ``DSM File Syntax''.
porter-email:
          See ``DSM File Syntax''.
porter-im:
          See ``DSM File Syntax''.
porting-ftp-site:
          See ``DSM File Syntax''.
porting-web-site:
          See ``DSM File Syntax''.
post-install-readme:
          See ``Installion & Dependency Directives''.
post-install-script:
          See ``Installion & Dependency Directives''.
post-uninstall-readme:
          See ``Installion & Dependency Directives''.
post-uninstall-script:
          See ``Installion & Dependency Directives''.
pre-install-readme:
          See ``Installion & Dependency Directives''.
pre-install-script:
          See ``Installion & Dependency Directives''.
pre-uninstall-readme:
          See ``Installion & Dependency Directives''.
pre-uninstall-script:
          See ``Installion & Dependency Directives''.
prefix:
          See ``Installion & Dependency Directives''.
provides:
          See ``Installion & Dependency Directives''.
replaces:
          See ``Installion & Dependency Directives''.
requires:
          See ``Installion & Dependency Directives''.
short-description:
          See ``DSM File Syntax''.
simtelnet-path:
          See ``Installion & Dependency Directives''.
sources:
          See ``DSM File Syntax''.
sources-dsm:
          See ``DSM File Syntax''.
tar-gzip:
          See ``Installion & Dependency Directives''.
version:
          See ``DSM File Syntax''.
virtual:
          See ``DSM File Syntax''.
web-site:
          See ``DSM File Syntax''.
zip:
          See ``Installion & Dependency Directives''.
Table of Contents
*****************




Introduction
  DJGPP Software Manifest

DSM File Syntax
  Syntax
    Directives
    Line Continuation & Escaping
    Formats
  Descriptive Directives
    DSM Header
    Information Directives
  Installion & Dependency Directives
    Package Archive Information
    Dependencies
  DSM File Structure
    Required Fields
    Multiply-Allowed Directives
  Scripting
  Standard Provisions

Concept Index

Variable Index

