part of The FreeDOS Project

Package

A package provides an easy way to install new software on FreeDOS.

Package files

FreeDOS uses zip files as the package file format. We chose zip files for several reasons, not the least of them the fact that zip files under DOS have become the de facto way to distribute collections of files. The zip file format is well-known, well-supported, and in the public domain. FreeDOS prefers Info-ZIP to create packages. FreeDOS packages must only contain files fitting the 8.3 convention (up to 8 characters for the filename and 3 characters for the extension) due to legacy concerns.

This is the recommended command line to create a package for a program named EXAMPLE:

ZIP −9 -r -k EXAMPLE.ZIP subdir1 subdir2 ... subdirN

If you use 7za to create packages, use this command line:

7za a -mm=deflate -mx=9 -tzip EXAMPLE.ZIP subdir1 subdir2 ... subdirN

Note that 7za allows to use a different compression algorithms. The FreeDOS package manager FDNPKG supports two compression methods: Deflate and LZMA. Usually LZMA provides better compression than Deflate, however it is not recommended for general use because LZMA decompression requires much more memory than Deflate. LZMA decompression needs about 24MiB of memory, which is often more than the total available memory on most DOS systems. LZMA might be used for packages that assume high-end systems (for example: 3D games, etc). But it’s always safer to stick to Deflate.

Nevertheless, if you wish to create a package using LZMA, use this:

7za a -mm=lzma -tzip EXAMPLE.ZIP subdir1 subdir2 ... subdirN

Package filenames

Packages names must follow some basic rules: They must be no longer than 8 characters long (but should not be too short either, since a 1-letter or 2-letter package name might be confusing) and may only be composed of characters a-b, 0-9 or underscore. This is for backward compatibility with short file names (8.3) and ISO 9660 file systems (used on CD-ROM). FreeDOS package filenames always use the .ZIP extension.

FreeDOS 1.1 package structure

FreeDOS 1.1 uses a single package file that includes binary and source code. The Installer can choose to not extract sources at install time. The directory structure is otherwise the same as 1.0:

FreeDOS 1.1 package structure
Path Meaning
APPINFO Put the program’s LSM file here
BIN Binaries, such as EXE and COM programs
DOC\%PKGNAME% Package documentation, with each package having its own directory
HELP The help files
NLS\%PKGNAME% Optional localizations (NLS language files) of the package
SOURCE\%PKGNAME% The complete source code (when installed) with each package having its own directory

Packages should only include subdirectories of the install target. For example, do not specify C:\FREEDOS in the path. The install target may be referred to after installation using the %DOSDIR% variable.

Programs that are not part of the core FreeDOS system (such as third party applications or games), can also be packaged using the same format described above, although they will probably need to have all files in their own directory most of the time. For example, for a package FOO containing a program that is not part of the FreeDOS core, we might have a package with the following structure:

FreeDOS 1.1 package structure
Path Meaning
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
LINKS\FOO.BAT A batch file to launch the program, see the “Links” below
SOURCE\FOO\* All source code for the FOO program

Note the PROGS directory above. This is a category to which the package belong. The package installer might change this directory at install time, depending on the user’s preferences. Possible categories include:

Program categories
Category Meaning
DEVEL Devlepment tools, like compilers and assembleres
DRIVERS Hardware drivers
GAMES Fun games
PROGS Other user programs and tools

Links

Many utilities are meant to be used from the command line to work on files. Such tools are often expected to be somewhere in the PATH variable, so the user doesn’t need to change to the directory where the said utility is stored to use it. A good example of such tools are archivers (like ZIP and UNRAR) but there are others, too.

For such tools, the FreeDOS package format provides a “linking” provision. A package that wishes to put one or more of its executable in the PATH will have to use a LINKS directory, and in this directory a batch file for every executable that needs to be listed in the PATH. The batch file must contain only the path and filename to the target executable (as stored in the zip package). During installation, the FreeDOS package manager will substitute these batch files with proper content.

LSM Files

The Linux Software Map file, or LSM for short, is a text file used to describe the software in a FreeDOS package. The FreeDOS LSM uses version 3, the newest version is 4 on ibiblio.com

The structure is as follows, each entry should be on a line of it own. The file starts with the word Begin3 on a line of its own, and ends with the word End again an its own line.

The other fields are as follows:

Note: In the past, when a URL no longer points to a valid page, the entry often get’s prefixed with Defunct-*. For example, the original website no longer exists and we do not want it displayed on various web pages. But, we want to keep the URL in the LSM file for a reference. Storing it as Defunct-Original-site accomplishes that.

Translation LSMs

These files go into the same directory as the primary LSM using a file extension based on the DOS language code. They are used by programs like FDIMPLES and PKGINFO to display package information in the users preferred language. Only the fields which need translated should be included (plus an additional required field). Only the following fields should be present and will override the information contained in the default English version of the LSM.

FreeDOS 1.0 package structure

This section is obsolete. See FreeDOS 1.1 package structure, above.

FreeDOS 1.0 used separate packages for binaries (“pkg”) and source code (“spkg”). The below directories are subdirectories of the base install directory. This format is obsolete, and should not be used for any new packages.

Binary packages used this directory structure:

FreeDOS 1.0 package structure
Path Meaning
APPINFO Put the program’s LSM file here. The LSM file must have the exact same name as the package filename, except for the file’s extension.
BIN Binaries, such as EXE and COM programs. If a program uses a BAT file, that goes in BIN too.
DOC Package documentation, with each package having its own directory. This allows a complicated package such as a compiler or programmable editor to include more than just a README file such as sample code for the compiler, technical notes or other references.
HELP The help files.

Source packages used this directory structure:

FreeDOS 1.0 package structure
Path Meaning
SOURCE The complete source code (when installed) with each package having its own directory.