\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename dsm.info
@settitle DJGPP Software Manifest Specification
@setchapternewpage odd
@paragraphindent 0
@c %**end of header

@c $Id: dsm.txi,v 1.12 2002/05/05 08:45:14 richdawe Exp $

@include version.txi

@titlepage
@title DJGPP Software Manifest Specification @value{DSM-SPEC-VERSION}
@subtitle Copyright @copyright{} @value{DSM-SPEC-COPYRIGHT-YEARS} by Richard Dawe
@page
@end titlepage

@ifinfo
@dircategory DJGPP Package Management
@direntry
* DSM: (dsm).                 DJGPP Software Manifest (DSM) specification
@end direntry
@end ifinfo

@node	Top,	Introduction,	(dir),	(dir)
@top

@c Author: Richard Dawe @email{rich@@phekda.freeserve.co.uk}

@ifnottex

DJGPP Software Manifest Specification @value{DSM-SPEC-VERSION}
Copyright @copyright{} @value{DSM-SPEC-COPYRIGHT-YEARS} by Richard Dawe

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts.  A copy of the license is included in the section
entitled "GNU Free Documentation License"
(@pxref{GNU Free Documentation License}).

@menu
* Introduction::
* Descriptive Directives::
* Installation & Dependency Directives::
* DSM File Structure::
* Scripting::
* Standard Provisions::

* Changelog::

* GNU Free Documentation License::

* Concept Index::
* Variable Index::
@end menu

@end ifnottex

@node	Introduction,	Descriptive Directives,	Top,	(dir)

@chapter 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.

@cindex manifest file
@cindex version file

DJGPP software often comes with a @dfn{manifest file}, with a file extension
of @samp{.mft}, which lists the files contained in the package, and a
@dfn{version file}, with a file extension of @samp{.ver}, which has a brief
description of the package, often containing no more than the name and version.

@cindex package manager

It would be useful to have a standard way of describing DJGPP packages,
so that they could be installed/uninstalled/queried by a @dfn{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.

@cindex package

Before going any further, the term "package" should be defined in the context
of this specification.  A @dfn{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).

@section DJGPP Software Manifest

@cindex DSM file

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

@itemize @bullet
@item Package name, version, type, short and long descriptions;
@item Names of binary, source or documentation DSMs for this package;
@item License, author, organisation, maintainer, porter, mailing list and newsgroup information;
@item Home page, download site, location on DJGPP archive;
@item Location of informational files in the package;
@item Dependency of package on other packages, e.g.: requirements, clashes;
@end itemize

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 @samp{manifest/} off the
top-level directory.  This ensures that the package managers can easily find
the DSM.

@node Descriptive Directives, Installation & Dependency Directives, Introduction, Top

@chapter DSM File Syntax

@section Syntax

@subsection Directives

@cindex directive
@cindex directives

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

@example
short-description: V. short
@end example

@cindex multiple values

Directives are single-valued - to have multiple values, the directive should be
used more than once.  This is not allowed with all directives.
@xref{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
@samp{author-email} directive refers the third author's e-mail address.

@subsection Line Continuation & Escaping

@cindex line continutation

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

@cindex escaping
@cindex escape characters

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

@table @samp
@item \n
Newline
@item \t
Tab
@item \\
Backslash
@end table

@subsection Formats

@cindex version number

The @dfn{version number} must be specified as follows:

@example
<Major>[.<Minor>[.<Subminor>[.<Subsubminor>]]]
[  (alpha <Alpha number>)
 | (beta <Beta number>)
 | (pre <Pre-release number>)]
[revision <Revision number>] [patchlevel <Patchlevel number>]
[snapshot <ISO 8061 hyphenless date>] [release <Release number>]
[platform <Platform specifier>]
@end example

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.

@cindex ISO 8061 date

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

@cindex platform

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

The platform should be treated insensitively of case.

@section Descriptive Directives

@subsection DSM Header

The following fields comprise the DSM header:

@vtable @samp
@item dsm-file-version
This specifies the revision of this file, e.g.: 1, 0.1 - do not confuse this
with @samp{dsm-version}.  This allows the user to check for new versions of a
package's DSM file.
@item dsm-version
DSM format version number, e.g.: @value{DSM-SPEC-VERSION},
the version of this specification.
@item dsm-name
DSM name = file name without extension
@end vtable

The following fields comprise the DSM author information header:

@vtable @samp
@item dsm-author
DSM author's name
@item dsm-author-email
DSM author's e-mail address
@item dsm-author-im
DSM author's instant messaging details, e.g for ICQ
@item dsm-author-web-site
DSM author's web site
@item dsm-author-ftp-site
DSM author's FTP site
@end vtable

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

@subsection Information Directives

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

In the @samp{binaries-dsm}, @samp{source-dsm} and @samp{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 @samp{version}.
@samp{binaries-dsm} cannot appear in a DSM for a binaries package;
@samp{sources-dsm} cannot appear in a DSM for a sources package;
@samp{documentation-dsm} cannot appear in a DSM for a documentation package.

@vtable @samp
@item name
This specifies the package name, which cannot contain whitespace.
Instead use hyphens or underscores.  The package name should be treated
insensitively of case.
@item version
Version number
@item type
(binaries|sources|documentation|group|virtual)

In previous versions of the DSM specification, this was called
@samp{dsm-type}.  @samp{dsm-type} should not be used.  The type
should be treated insensitively of case.

The different package types are defined as follows:

@cindex binaries package
@cindex sources package
@cindex documentation package
@cindex group package
@cindex virtual package

@vtable @samp
@item binaries
The package primarily contains executable programs.
@item sources
The package primarily contains source code.
@item documentation
The package primarily contains documentation.
@item 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 @samp{requires} directive.
@item 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 @samp{provides} directive.
@end vtable

@item manifest
Manifest, .mft, file name without extension
@item binaries-dsm
Binaries DSM name, file name without extension
@item sources-dsm
Sources DSM name, file name without extension
@item documentation-dsm
Documentation DSM name, file name without extension
@item short-description
One line of text
@item long-description
Multiple lines of text
@item license
Package's license, e.g.: GNU General Public License, BSD License
@item organisation
e.g.: FSF
@item author
Author's name for this package
@item author-email
Author's e-mail address
@item author-im
Author's instant messaging details, e.g.: for ICQ
@item web-site
Home page for the package or author - this should give the complete URL,
e.g.: @samp{http://www.grossprojekt.org/}.
@item ftp-site
Download site of the package or author - this should give the complete URL,
e.g.: @samp{ftp://ftp.grossprojekt.org/}.
@item maintainer
Maintainer's name
@item maintainer-email
Maintainer's e-mail address
@item maintainer-im
Maintainer's instant messaging details, e.g.: for ICQ
@item maintainer-web-site
Maintainer's home page
@item maintainer-ftp-site
Maintainer's FTP site
@item porter
Porter's name
@item porter-email
Porter's e-mail address
@item porter-im
Porter's instant messaging details, e.g.: for ICQ
@item porting-web-site
Home page for the port, with complete URL.
@item porting-ftp-site
Download site for the port, with complete URL.
@item mailing-list
Mailing list's e-mail address
@item mailing-list-description
Description of the Mailing list
@item 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.
@item mailing-list-administrator
Mailing list administrator's name
@item mailing-list-administrator-email
Mailing list administrator's e-mail address
@item mailing-list-administrator-im
Mailing list administrator's instant messaging details, e.g.: for ICQ
@item mailing-list-web-site
Mailing list home page, with complete URL - this should contain details of how
to join the list.
@item mailing-list-ftp-site
Mailing list download site, with complete URL.
@item newsgroup
Newsgroup for the package
@item newsgroup-description
Description of the newsgroup
@item 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
@samp{djgpp@@delorie.com}.
@item newsgroup-administrator
Newsgroup administrator's name
@item newsgroup-administrator-email
Newsgroup administrator's e-mail address
@item newsgroup-administrator-im
Newsgroup administrator's instant messaging details, e.g.: for ICQ
@item newsgroup-web-site
Newsgroup home page, with complete URL.
@item newsgroup-ftp-site
Newsgroup download site, with complete URL.
@end vtable

@node Installation & Dependency Directives, DSM File Structure, Descriptive Directives, Top
@section Installion & Dependency Directives

@subsection Package Archive Information

@vtable @samp
@item simtelnet-path
This is the location of the package's archive in the DJGPP FTP structure,
e.g.: @samp{v2tk/}.  This is for automatic FTP or HTTP downloading by
the package manager.  The trailing slash is optional.
@item zip
This specifies the archive file names in preferred order of installation.
The file extension must be @samp{.zip} and must be present in this field.

@samp{.zip} archives are created with PKZIP or a PKZIP-compatible archiver
such as Info-ZIP.
@item tar-gzip
This specifies the archive file names in preferred order of installation.
The file extension must be one of @samp{.tgz}, @samp{.taz}
or @samp{.tar.gz} and must be present in this field.

@samp{.tar.gz} archives are created with tar and the GNU zip program (gzip).
@item tar-bzip2
This specifies the archive file names in preferred order of installation.
The file extension must be one of @samp{.tbz}, @samp{.tbz2}
or @samp{.tar.bz2} and must be present in this field.

@samp{.tar.bz2} archives are created with tar and bzip2.
@end vtable

@vtable @samp
@item changelog
This specifies the relative path in the archive to the changelog, for use
by the package manager.
@end vtable

@vtable @samp
@item pre-install-readme
This specifies the relative path in the archive to "readme" file for
pre-install information.
@item post-install-readme
This specifies the relative path in the archive to "readme" file for
post-install information.
@item pre-uninstall-readme
This specifies the relative path in the archive to "readme" file for
pre-uninstall information.
@item post-uninstall-readme
This specifies the relative path in the archive to "readme" file for
post-uninstall information.
@end vtable

@vtable @samp
@item builtin-pre-install-script
[Built-in scripting]
@item builtin-post-install-script
[Built-in scripting]
@item builtin-pre-uninstall-script
[Built-in scripting]
@item builtin-post-uninstall-script
[Built-in scripting]
@end vtable

@xref{Scripting}, for a definition of the built-in scripting language.

@vtable @samp
@item pre-install-script
[File name, extracted from zip/tgz]
@item post-install-script
[File name]
@item pre-uninstall-script
[File name]
@item post-uninstall-script
[File name]
@end vtable

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 @samp{requires} directive
should be used to ensure that the script can be run.

@vtable @samp
@item keep-file
@samp{keep-file} can be used to specify files that should not be overwritten
on installation or removed on uninstall.  E.g.:

@example
keep-file: share/prog.cfg
@end example
@end vtable

@vtable @samp
@item 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
@samp{demopkg/} in the archive, the @samp{prefix} could be @samp{contrib/} to
put them into @samp{contrib/demopkg/} off the DJGPP directory.  @samp{prefix}
should be a relative path.  The trailing slash is optional.
@end vtable

@subsection Dependencies

@cindex operator

<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.

@vtable @samp
@item requires
<Package> [[<Operator>] <Version>]@*
@emph{or} <Feature> [[<Operator>] [<Version>]][: <Qualifier>]
@item depends-on
<Package> [[<Operator>] <Version>]@*
@emph{or} <Feature> [[<Operator>] [<Version>]][: <Qualifier>]
@item conflicts-with
<Package> [[<Operator>] <Version>]@*
@emph{or} <Feature> [[<Operator>] [<Version>]][: <Qualifier>]
@item replaces
<Package> [[<Operator>] <Version>]
@item duplicate-action
@samp{duplicate-action} should be treated insensitively of case.

(replace|backup|keep|skip|query)
@end vtable

@samp{depends-on} has a different emphasis than @samp{requires}.  A package
@samp{requires} another to function @strong{at all}.  If it @samp{depends-on}
then some of its functionality may not be available.

The default @samp{duplicate-action} will depend on the installation utility.

@vtable @samp
@item provides
<Feature> [[<Operator>] [<Version>]][: <Qualifier>]
@end vtable

@cindex feature
@cindex features

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

The feature name is like a package name, and so cannot contain whitespace -
please use hyphens or underscores instead.  The feature name should be treated
insensitively of case.

@cindex qualifier
@cindex dependency qualifier
@cindex dependency qualification

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 @dfn{qualifier}
can be used to indicate these.  It is suggested that these take the form of
@samp{function 0x0501} or @samp{function gethostbyname_r()}.  Acronyms should
be written in uppercase.  @xref{Standard Provisions}, for
the 'provides' defined so far.  The use of feature qualifiers
should be co-ordinated by incorporation into this specification.

Qualifiers should be treated insensitively of case.

@vtable @samp
@item install-before
<Package> [[<Operator>] <Version>]
@item install-after
<Package> [[<Operator>] <Version>]
@item install-warning
Message
@end vtable

@node DSM File Structure, Required Fields, Installation & Dependency Directives, Top
@section DSM File Structure

@ifnottex
@menu
* Required Fields::
* Multiply-Allowed Directives::
@end menu
@end ifnottex

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

@item
A virtual package has a DSM entry with a name such as "Windows 95" and
a list of 'provides' fields such as @samp{provides: DPMI 0.9}.

@end itemize

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 @samp{dsm-author},
etc. fields.

@node Required Fields, Multiply-Allowed Directives, DSM File Structure, DSM File Structure
@subsection Required Fields

@table @samp
@item dsm-author
@item dsm-file-version
@item dsm-version
@item dsm-name
@item name
@item version
@item type
@item short-description
@item 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.
@item zip or tar-gzip
This is only needed if it's a binaries, documentation or sources package.
@end table

Any known @samp{requires}, @samp{depends-on}, @samp{replaces},
@samp{install-before} or @samp{install-after} dependencies are also required.

@node Multiply-Allowed Directives, Scripting, Required Fields, DSM File Structure
@subsection Multiply-Allowed Directives

The following directives are allowed multiply:

@table @samp
@item author
@item author-email
@item author-im
@item web-site
@item ftp-site
@item maintainer
@item maintainer-email
@item maintainer-im
@item maintainer-web-site
@item maintainer-ftp-site
@item porter
@item porter-email
@item porter-im
@item porter-web-site
@item porter-ftp-site
@item mailing-list
@item mailing-list-description
@item mailing-list-request
@item mailing-list-administrator
@item mailing-list-administrator-email
@item mailing-list-administrator-im
@item mailing-list-web-site
@item mailing-list-ftp-site
@item newsgroup
@item newsgroup-description
@item newsgroup-email-gateway
@item newsgroup-administrator
@item newsgroup-administrator-email
@item newsgroup-administrator-im
@item newsgroup-web-site
@item newsgroup-ftp-site
@sp 1
@item zip
@item tar-gzip
@sp 1
@item requires
@item depends-on
@item conflicts-with
@item replaces
@item provides
@item install-before
@item install-after
@end table

An example is the case where a package has multiple authors:

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

@node Scripting, Standard Provisions, Multiply-Allowed Directives, Top
@section 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
@samp{builtin-pre-install-script},
@samp{builtin-post-install-script},
@samp{builtin-pre-uninstall-script} and
@samp{builtin-post-uninstall-script} directives.

@vtable @samp

@item echo
<Arguments>
@sp 1
This displays/outputs @samp{Arguments}.  This could be used to remind the user
to read the fine manual.
@sp 1

@item command
<Program> <Arguments>
@sp 1
This executes @samp{Program} by passing @samp{Arguments} to it.  This could be
used to run @samp{install-info}  -
@xref{Invoking install-info, Texinfo, Invoking install-info, texinfo,
Texinfo: The GNU Documentation Format}.
@sp 1

@end vtable

Here is a simple example:

@example
builtin-post-install-script: command: echo Hello Mum!
@end example

@node Standard Provisions, Changelog, Scripting, Top
@section Standard Provisions

The following provisions are defined in the DSM specification, so that
packages have a standard way of requiring the features.

@vtable @samp
@cindex djgpp-dev-env
@item djgpp-dev-env
This denotes DJGPP 2.03's support of using @file{/dev/env}-style paths
(@pxref{Changes in 2.03, , Changes in 2.03, kb}).
@cindex DPMI
@item DPMI 0.9
@item DPMI 1.0
@item DPMI 1.0: function 0x0506
@item DPMI 1.0: function 0x0507
@item DPMI 1.0: function 0x0508
@item DPMI 1.0: function 0x0509
@item DPMI 1.0: function 0x0E01
@cindex info-reader
@item info-reader
This denotes ability to read documentation in info format.
@cindex LFN
@item LFN
This denotes the Windows '95 Long FileName API for DOS boxes.
@cindex web-browser
@item web-browser
This denotes a program capable of displaying HTML pages.
@end vtable

@node Changelog, GNU Free Documentation License, Standard Provisions, Top
@chapter Changelog

@section Version 0.6.0

@itemize @bullet

@item
Package names should now be treated insensitively of case.

@item
The @samp{type} directive, the @samp{duplicate-action} directive,
the platform component of the @samp{version} directive, feature names
and qualifiers (in dependencies) should now be treated insensitively
of case.

@item
Added the @samp{tar-bzip2} directive for specifying archives created
with tar and bzip2.

@item
Removed the @samp{keep-file} directive from the required directives section,
since its use is up to package maintainers.

@item
@samp{binaries-dsm} is now forbidden in a DSM for a binaries package;
@samp{sources-dsm} is now forbidden in a DSM for a sources package;
@samp{documentation-dsm} is now forbidden in a DSM for
a documentation package.
@end itemize

@section Version 0.5.1

@itemize @bullet

@item
Added @samp{release} to the version of package, to allow multiple releases
of a package.  Added @samp{keep-file}, to allow certain files to be preserved
on installation/uninstallation of a package - e.g.: configuration files.
@end itemize

@section Version 0.5.0

@itemize @bullet

@item
Added new standard provisions: @samp{djgpp-dev-env}, @samp{web-browser}.

@item
Renamed @samp{dsm-type} to @samp{type}.
@end itemize

@section Version 0.4.4

@itemize @bullet

@item
Changelog added

@item
Support for pre-release versions added (@pxref{Descriptive Directives}).
@end itemize

@node GNU Free Documentation License, Concept Index, Changelog, Top
@appendix GNU Free Documentation License

@include fdl.txi

@node Concept Index, Variable Index, GNU Free Documentation License, Top

@unnumbered Concept Index

@printindex cp

@node	Variable Index,	,	Concept Index,	Top
@unnumbered Variable Index

@printindex vr

@contents
@bye
