Subversion Repositories SvarDOS

Rev

Rev 1623 | Rev 1903 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
286 mateuszvis 1
 
893 bttr 2
                        %h*** SVARDOS PACKAGE FORMAT ***
3
 
286 mateuszvis 4
Package files provide an easy way to manage software on SvarDOS. These
5
packages must adhere to a strict convention so they can be handled properly
6
by the SvarDOS package manager.
7
 
8
 
9
%hPackage filenames
10
 
11
Packages names must follow some basic rules. They shall be max. 8 letters long
12
(but should not be too short either, since a 1 or 2-letters package name might
13
be confusing), and must not be composed of characters other than a-b, 0-9 and
14
'_'. This for backward compatibility with short file names (8+3) and ISO 9660
15
file systems (used on CDROMs). The package filename is always followed by the
893 bttr 16
.svp ("SvarDOS Package") extension.
286 mateuszvis 17
 
18
 
19
%hPackage files
20
 
21
SvarDOS uses ZIP files as its package file format. This format has been chosen
22
because ZIP files under DOS have become the de facto way to distribute
23
collections of files. Also, the ZIP file format is well documented, well
24
supported, and in the public domain.
25
 
26
Here below is the recommended command line that can be used to create a
893 bttr 27
package for a program named EXAMPLE labelled as version "1.2.34" using
895 bttr 28
Info-ZIP's Zip:
286 mateuszvis 29
 
893 bttr 30
  zip -9rkDX example-1.2.34.svp subdir1 subdir2 ... subdirN
286 mateuszvis 31
 
32
If you are using 7za to create your packages, then use this:
33
 
893 bttr 34
  7za a -mm=deflate -mx=9 -tzip example-1.2.34.svp subdir1 subdir2 ... subdirN
286 mateuszvis 35
 
893 bttr 36
Note: The version in the filename is just an information for packagers so they
37
don't need to look into each package to know what version to expect there. In
38
LSM versions you might have non-filesystem-compatible stuff like "10/11/11" so
39
we don't want to enforce any kind of correlation.
286 mateuszvis 40
 
893 bttr 41
 
286 mateuszvis 42
%hPackage directory structure
43
 
44
The directory structure of a package depends on the type of packages.
45
For "core" packages, we have this:
46
 
47
  APPINFO            Put the program's LSM file here
1663 mateusz.vi 48
  BIN                Binaries, such as EXE, COM and LNG files
49
  DOC\PKGNAME        Package documentation, if any
50
  HELP\              Optional "help" documentation in AMB format (PKGNAME.AMB)
51
  NLS\PKGNAME        Localization files in the legacy, multifile (CATS) format
286 mateuszvis 52
 
53
Non-core packages use a slightly different directory organization. For
54
example, if we were to consider a package FOO, we might end up with the
55
following structure:
56
 
57
  APPINFO\FOO.LSM    Package meta file for the FOO program
58
  PROGS\FOO\FOO.EXE  The program's executable
59
  PROGS\FOO\FOO.TXT  Some documentation
60
  PROGS\FOO\FILE.DAT Data file used by the FOO program
61
 
685 bttr 62
Note the PROGS directory above. This is the category to which the package
63
belongs. The package installer might change this directory at install time,
286 mateuszvis 64
depending on the user's preferences. Possible categories are listed below:
65
 
66
Category | Description
67
DEVEL    | Development tools (mostly compilers)
68
DRIVERS  | Drivers
69
GAMES    | Games
70
PROGS    | User programs, tools...
71
 
72
Note: "DOC", "NLS", "BIN" and "HELP" directories are strictly reserved to
73
      CORE packages.
74
 
584 mateuszvis 75
 
286 mateuszvis 76
%hLSM meta-data files
77
 
78
Every package MUST contain an LSM file in its "APPINFO" directory. This LSM
79
file is a text file that contains basic information about the package. Its
80
format is very simple, it must contain at least two lines:
81
 
82
  version: x.y.z
83
  description: package description
84
 
1515 mateusz.vi 85
It may optionally contain also a line describing hardware requirements of the
86
package, such as:
87
 
88
  hwreq: 286 fpu cga hgc
89
 
90
The "hwreq" line contains a space-separated list of tokens that represent
91
hardware requirements. Following tokens are possible.
92
 
93
CPU family   : 8086 186 286 386 486 586
94
CPU features : fpu
1521 mateusz.vi 95
Graphic cards: mda cga ega mcga vga svga
1515 mateusz.vi 96
 
1605 mateusz.vi 97
If the package should display an informational message after its installation,
98
then the LSM file may contain one or more "warn" lines. These are displayed by
99
the pkg tool whenever the package is installed or updated. Example:
100
 
101
  version: 1.0
102
  description: logic game with lots of colors
1623 mateusz.vi 103
  hwreq: 386 vga
1605 mateusz.vi 104
  warn: This game will not run properly unless you define a TEMP
105
  warn: environment variable that points at a writeable directory.
106
 
286 mateuszvis 107
Any other lines are ignored by the SvarDOS package manager.
584 mateuszvis 108
 
109
 
110
%hPackage versions
111
 
112
The version present in the LSM file is meant to reflect the version of the
113
packaged software, but it may happen that a package needs to be changed to
114
fix a strictly packaging-related issue (for example a forgotten documentation
115
file or a recompilation of the binary using a better set of flags...). In such
116
case, the version of the software does not change, but the version of the
621 mateuszvis 117
package itself needs to change so users know something changed. That's where
584 mateuszvis 118
"SvarDOS revisions" come in. A version string is basically following such
119
format:
120
 
121
  UPSTREAM_VER[+SVARREV]
122
 
123
UPSTREAM_VER is the exact version string advertised by the software. It may
124
be pretty much anything. This upstream version may be optionally followed by a
621 mateuszvis 125
plus sign and the SvarDOS revision. In the event that the upstream version
584 mateuszvis 126
already contains a plus sign, then SvarDOS revision is delimited with a tilde.
127
 
687 bttr 128
The SvarDOS revision starts at 0 and increments by 1 each time that the given
584 mateuszvis 129
upstream revision is repackaged. The SvarDOS revision restarts whenever the
130
upstream version changes. The SvarDOS revision of 0 is always hidden.
131
 
132
Examples:
133
 
134
FDISK 1.54      <- originally packaged version
135
FDISK 1.54+1    <- package has been changed, but not the upstream version
136
FDISK 1.55      <- upstream version increased, so SvarDOS rev restarts
137
FDISK 1.55+1    <- new version of the package, but still contains FDISK 1.55
138
FDISK 1.55+2    <- another new version of the package, etc
689 mateusz.vi 139
 
140
The entire version string of a package must never exceed 16 characters.
141
 
142
 
143
%hSources
144
 
145
When a packaged software has its sources available, then it is recommended to
146
archive also them. To that effect, put the sources into a ZIP archive that has
893 bttr 147
the same filename as the package, but a *.zip extension (as opposed to the
148
*.svp extension of the proper package). The result would be that the packaged
689 mateusz.vi 149
software would be distributed within two files. Example for FDISK:
150
 
893 bttr 151
fdisk-1.55+2.svp       <- binaries (ZIP archive following the SVP structure)
152
fdisk-1.55+2.zip       <- sources (flat, unstructured ZIP archive)
689 mateusz.vi 153
 
154
The ZIP file must obviously contain the source code that belongs to the exact
155
same version present in the SVP package.