Subversion Repositories SvarDOS

                        %h*** SVARDOS PACKAGE FORMAT ***

Package files provide an easy way to manage software on SvarDOS. These

packages must adhere to a strict convention so they can be handled properly

by the SvarDOS package manager.

%hPackage filenames

Packages names must follow some basic rules. They shall be max. 8 letters long

(but should not be too short either, since a 1 or 2-letters package name might

be confusing), and must not be composed of characters other than a-b, 0-9 and

'_'. This for backward compatibility with short file names (8+3) and ISO 9660

file systems (used on CDROMs). The package filename is always followed by the

.svp ("SvarDOS Package") extension.

%hPackage files

SvarDOS uses ZIP files as its package file format. This format has been chosen

because ZIP files under DOS have become the de facto way to distribute

collections of files. Also, the ZIP file format is well documented, well

supported, and in the public domain.

Here below is the recommended command line that can be used to create a

package for a program named EXAMPLE labelled as version "1.2.34" using

Info-ZIP's Zip:

  zip -9rkDX example-1.2.34.svp subdir1 subdir2 ... subdirN

If you are using 7za to create your packages, then use this:

  7za a -mm=deflate -mx=9 -tzip example-1.2.34.svp subdir1 subdir2 ... subdirN

If you have access to the advzip pogram, you may use it to squeeze the archive

slightly more (esp. interesting for CORE packages since these are distributed

on floppy disks):

  advzip -zpk4 -i 100 example-1.2.34.svp

Note: The version in the filename is just an information for packagers so they

don't need to look into each package to know what version to expect there. In

LSM versions you might have non-filesystem-compatible stuff like "10/11/11" so

we don't want to enforce any kind of correlation.

%hPackage directory structure

The directory structure of a package depends on the type of packages.

For "core" packages, we have this:

  APPINFO            Put the program's LSM file here

  BIN                Binaries, such as EXE, COM and LNG files

  DOC\PKGNAME.TXT    Documentation, if it is a single file

  DOC\PKGNAME\*      Documentation, if more than one file

  NLS\PKGNAME        Localization files in the legacy, multifile (CATS) format

Non-core packages use a slightly different directory organization. For

example, if we were to consider a package FOO, we might end up with the

following structure:

  APPINFO\FOO.LSM    Package meta file for the FOO program

  PROGS\FOO\FOO.EXE  The program's executable

  PROGS\FOO\FOO.TXT  Some documentation

  PROGS\FOO\FILE.DAT Data file used by the FOO program

Note the PROGS directory above. This is the category to which the package

belongs. The package installer might change this directory at install time,

depending on the user's preferences. Possible categories are listed below:

Category | Description

DEVEL    | Development tools (mostly compilers)

DRIVERS  | Drivers

GAMES    | Games

PROGS    | User programs, tools...

Note: "DOC", "NLS", "BIN" and "HELP" directories are strictly reserved to

      CORE packages.

%hLSM meta-data files

Every package MUST contain an LSM file in its "APPINFO" directory. This LSM

file is a text file that contains basic information about the package. Its

format is very simple, it must contain at least two lines:

  version: x.y.z

  description: package description

It may optionally contain also a line describing hardware requirements of the

package, such as:

  hwreq: 286 fpu cga hgc

The "hwreq" line contains a space-separated list of tokens that represent

hardware requirements. Following tokens are possible.

CPU family   : 8086 186 286 386 486 586

CPU features : fpu

Graphic cards: mda cga ega mcga vga svga

If the package should display an informational message after its installation,

then the LSM file may contain one or more "warn" lines. These are displayed by

the pkg tool whenever the package is installed or updated. Example:

  version: 1.0

  description: logic game with lots of colors

  hwreq: 386 vga

  warn: This game will not run properly unless you define a TEMP

  warn: environment variable that points at a writeable directory.

Any other lines are ignored by the SvarDOS package manager.

%hPackage versions

The version present in the LSM file is meant to reflect the version of the

packaged software, but it may happen that a package needs to be changed to

fix a strictly packaging-related issue (for example a forgotten documentation

file or a recompilation of the binary using a better set of flags...). In such

case, the version of the software does not change, but the version of the

package itself needs to change so users know something changed. That's where

"SvarDOS revisions" come in. A version string is basically following such

format:

  UPSTREAM_VER[+SVARREV]

UPSTREAM_VER is the exact version string advertised by the software. It may

be pretty much anything. This upstream version may be optionally followed by a

plus sign and the SvarDOS revision. In the event that the upstream version

already contains a plus sign, then SvarDOS revision is delimited with a tilde.

The SvarDOS revision starts at 0 and increments by 1 each time that the given

upstream revision is repackaged. The SvarDOS revision restarts whenever the

upstream version changes. The SvarDOS revision of 0 is always hidden.

Examples:

FDISK 1.54      <- originally packaged version

FDISK 1.54+1    <- package has been changed, but not the upstream version

FDISK 1.55      <- upstream version increased, so SvarDOS rev restarts

FDISK 1.55+1    <- new version of the package, but still contains FDISK 1.55

FDISK 1.55+2    <- another new version of the package, etc

The entire version string of a package must never exceed 16 characters.

%hSources

When a packaged software has its sources available, then it is recommended to

archive also them. To that effect, put the sources into a ZIP archive that has

the same filename as the package, but a *.zip extension (as opposed to the

*.svp extension of the proper package). The result would be that the packaged

software would be distributed within two files. Example for FDISK:

fdisk-1.55+2.svp       <- binaries (ZIP archive following the SVP structure)

fdisk-1.55+2.zip       <- sources (flat, unstructured ZIP archive)

The ZIP file must obviously contain the source code that belongs to the exact

same version present in the SVP package.