Distribution HOWTO

Using The FreeDOS Install Program

Table of contents

1.0 Overview
2.0 Running the install program
3.0 Setting up the install program
4.0 Disk series
5.0 Structure of the package file

This documentation is intended not for general users, but for those who want to use the FreeDOS Install program to create their own software distributions. If you are a software distributor, you may freely use the FreeDOS Install program as your software installer, but my source code must be made available to your end users. This may be done by including the zip file with the source, or by indicating my web page, which contains the source code.

1.0 Overview

I wrote my install program when I realized that most of the Internet's comments about FreeDOS hovered around "Well, it's okay, but it's a pain to install properly." DOS should not be the most difficult operating system to install. In fact, given the simple, flat nature of the operating system, it should be one of the simplest around. But that's ideal.

My install program is simple in concept. I started out with only a few goals for version 1.0:

It should be package-based, so that the user can decide what packages (utilities, tools, and applications) to install on his system.
Packages should be divided into major groups, which the user can also decide whether or not to install. For example, you might collect all the FreeDOS utilities, plus the kernel, plus the COMMAND.COM, and bundle them into one group called Base. Drivers might be similarly grouped together, as are games, editors, and other program groups.
In addition to allowing the user to install what packages and groups to install, the install program should allow the distributor to hard-code some choices for you. For example, a package or a group of packages might be obviated by another. In this case, the distributor might want to simply deactivate the package or group. Or, you might want to force the user to install a minimum set of utilities and drivers.

The install program assumes nothing about the distribution media. Floppies are just as acceptable as a CD-ROM distribution. The only difference is that a floppy-based distribution requires certain flag files be present on each disk. We will go into what these flag files are named, and how they are constructed, in a moment.

I plan to add more features to the install program, making it easier to use. The following is a description of the complete release plan, starting at v.1.0:

v.1.0: The basic install program. Allows the user to select what packages to install. Released 28 Nov 1997.

v.1.1: Fixed a bug where package name was case sensitive. Released 26 Jan 1998.
v.1.2: Fixed a few minor bugs. Now tracks the number of problems encountered during the install. Released 13 Apr 1998.
v.1.2.1: Fixed the control files to work with the Beta 1 (Orlando) distribution. Released 23 Apr 1998.

v.2.0: Added the Unzip code to the program. Also added support for Red Hat RPH files. Released 12 Jul 1998.

v.2.1: Added support for Debian DSC files. Released 16 Aug 1998.
v.2.2: Added support for Linux LSM files. Major code clean up in preparation for v.3.0. Released 10 Sep 1998.

v.3.0: Added a UNIX curses-based interface. This release really sucked, and I didn't actually post it anywhere.

v3.1: Major code cleanup. Moved from a curses-based interface to using conio, which is a lot better for DOS. This program also compiles under UNIX, so I provided a conio compatibility library there. Dropped support for package info files other than LSM (Linux Software Map) files. If you want to support other info files, you'll have to write your own. Standardized the strings, so it will be easier to migrate to using MSGLIB for internationization. Released 26 Jan 1999.
v3.11: Added a patch to support color. Released 7 Feb 1999.
v3.12: Added a patch to only accept y or n when the program asks a yes/no question. Released 14 Feb 1999

v.4.0: Will add package management using an RPM-like database.

2.0 Running the install program

To run the install program, simply type the following at a DOS prompt:

  INSTALL

Future versions of the program may allow certain command line arguments to pre-select the source and target directories, and control other behavior of the program.

The first thing the install program will do is ask you where you keep the package files. This is the source directory, where the package files of the distribution live. In most cases, you will want to use A: for the source.

Then the program asks where you want to install the software. This is the target directory.

A description of each disk series will appear. A disk series is just a group of packages. Some series will be hard-coded as Required such as the Base disk series, and some as Skipped. Others will allow you to select if the series should be installed. If the distribution is fairly large, most of the series will probably be marked as Optional, meaning that you get to choose whether or not you want to install the series.

When you have selected whether or not to install each series, the install program will go ahead and install the software that you selected. Note that some disk series will let you choose which packages to install, while some may select to install all the software for you. Just watch the screen, and respond to the prompts. Change disks as requested by the program.

If you have the install disks on a CD-ROM or directory on your hard drive, you will not need to change any disks. All of the distribution will fit on one CD-ROM, and if the install program has been properly configured, then the install will proceed smoothly. Otherwise, floppy-based installs will require the user to load new disks from time to time.

At the end of the installation, you will see the message:

  The install program completed successfully.

This message really tells you that the program has completed what it set out to do, and freed all the memory that it had allocated. If there were errors during the installation, then you will instead see how many errors or warnings were encountered.

If a required package could not be installed, then that is an error. If an optional package could not be installed, then that is a warning.

3.0 Setting up the install program

Let's say that you're a brave chap, and you want to set up a FreeDOS distribution of your own. How very kind of you. The Internet community thanks you ahead of time. Just be sure to include cool software, and follow these instructions for configuring the install program.

These files must be present on an install floppy:

3.1 INSTALL.EXE

This is the install program.

3.2 OEM.TXT

You can have the Install program display your company logo, or some text to help your users, by creating a file called OEM.TXT. This file must appear in the same directory as the Install program. If the file is not present, that's okay; the user will not see an error message.

This file is printed to the screen without regard to its content. If you embed ANSI sequences that use ANSI.SYS to display color, that is fine with me. Just don't forget to turn off the blinking text, or whatever other attributes you used, at the end of your message or the rest of the Install program text will look funny.

3.3 disk.TXT

These disk-set description files are simply text files. The contents describe the disk-set that can be installed.

3.4 INSTALL.DAT

The INSTALL.DAT file is the first file that the install program reads. It is a very important file, and without it the install program will abort with an ugly message asking you where the hell you put the INSTALL.DAT file.

This file tells the install program about which disk series will be available during installation, and what their rank is. The rank is one of three possibilities:

Y
The series is required for installation, and will be installed no matter what the user wants. Be very careful about making series required for installation. Make too many of them required, and you'll piss off your users for filling up their hard disks.
N
The series has been deactivated for some reason. You may have decided not to install this series because it includes broken software, or because you are changing how you arrange the packages and series. In any case, a deactivated series will not be installed, and will not prompt the user.
?
The series is optional, and the install program should ask the user whether or not it should be installed. I would suggest making most of your disk series an optional series, to allow the greatest flexibility in a user configuring their own system. This flag can really be anything other than Y or N, but I recommend you stick with ?.

Under DOS, the INSTALL.DAT file is not case sensitive but I recommend you make the series names in all uppercase. This will make the names really stand out in the program. (Yes, the Install program runs under UNIX, and under UNIX the INSTALL.DAT file is sensitive to case.)

Here is a sample INSTALL.DAT file:

  BASE: y
  DRIVERS: y
  SOURCE: ?
  LANG: ?
  APPS: n
  GAMES: ?
  EDITORS: ?

4.0 Disk series

4.1 name.n

Every disk series needs to have a name.n file on it somewhere. This is much like the INSTALL.DAT file, except that it is for a particular diskette. Where the INSTALL.DAT file contained the names of the available disk series, the name.n file contains the names of the available packages.

Here is how to find the name.n file: If this were the first disk in the Base series, the name.n file would be named BASE.1 and the name.n file for the second disk in the Drivers series would be DRIVERS.2.

The BASE.1 file would contain entries for every package on the floppy, with the package's rank. When you sell your FreeDOS distribution, the label on the floppy would probably be something like Base-1 and this is what the install program will ask for. No, that is not the volume label. I am talking about the sticky label on the outside of the floppy disk.

Again, your options for the rank are Y for required packages, N for obsolete files, and ? for optional ppackages.

The following is an example of a name.n file:

  COMMAND: Y
  KERNEL: ?

4.2 package.LSM

This is a standard Linux Software Map file. For more information on what can appear in an LSM file, please read the LSM-TEMP (LSM Template) that is included with my Install program.

Lars Wirzenius wrote a small (and still fragile) tool to make it easier to browse and update the LSM. It will only work on a new style database (09AUG94). UNIX source only.

The following is an example of a Linux Softare Map file:

  Begin3
  Title:          Foo
  Version:        1.0
  Entered-date:   20 July 1998
  Description:    Prints the text "Hello world" to the screen.
  Keywords:       hello world foo
  Author:         Jim Hall 
  Maintained-by:  Jim Hall 
  Primary-site:   ftp://ftp.isd.net/jhall1/freedos/foo10s.zip (1k)
  Alternate-site: ftp://ftp.foo.com/pub/foo/foo10s.zip (1k)
  Original-site:  ftp://ftp.isd.net/jhall1/freedos/foo10s.zip (1k)
  Platforms:      DOS (Borland C), UNIX (gcc)
  Copying-policy: GPL
  End

4.3 name.END

The name.END file belongs only on the last disk in a series. It is a special marker file for the install program, which tells the install program that there are no more disks in this series. Note that this may cause a problem if you decide to get cute and copy all of your installation floppies from floppy to a single directory on your hard drive. Your installation from this massive directory will not install what you think it will - each series will stop after installing the first disk in each series.

The content of the name.END file can be anything, or the file may be empty. The install program doesn't care. It only checks if this file exists on the disk, and if it does, stops processing the disk series.

Note that the install program will always install at least the first disk in each series. We do this because it's possible to have a one-disk series (especially if you decide to distribute your software on CD-ROM) and so you will have only a name.1 file and name.END per each series.

5.0 Structure of the package file

As I said, I am using zip as my package manager. I chose zip 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 file format is well known, well supported, and in the public domain.

Zip files lack certain features that I may one day build into the install program, such as dependencies, so I may one day switch file formats. But for now, zip files are my standard.

When you create your packages, remember that the user is already choosing what the target directory will be. Therefore, your packages should only extract directories that are subdirectories of the target.

If you are using PKZIP to create your packages, you will want to use a command line like this one:

  PKZIP -ex -Pr package.zip subdir\*.*

If you are using Info-zip to create your packages, you will want to use a command line like this:

  ZIP -9 -r -k package.zip subdir

Each package should include only the files and directories which are necessary to run that program. For example, if you are creating a package for the CLS program, you might only want to include the program and its help file. In this case, the Info-zip command line would look like this:

  ZIP -9 -r -k CLS.ZIP BIN\CLS.COM HELP\CLS.HLP

The FreeDOS Install program does not have any firm standards on what its directories should be named. However, I strongly recommend adhering to these few rules when creating packages for installations:

Do not name the C:\FREEDOS path. Your package should only include subdirectories of the C:\FREEDOS directory. You will want to do this because one user might prefer the path C:\DOS, and another might use C:\FDOS.
Programs and .SYS files related to the FreeDOS project should go under a subdirectory called BIN. For example, the BIN directory will contain the XCOPY, FORMAT, FDISK, and other utilities typically associated with DOS. You may or may not choose to install your editors here.
Help files for installed programs should go in the HELP subdirectory. The extensions on those help files will depend on what help viewer you are using. A help system based on GNU Info might use .INF, while one based on HTML files might use .HTM.
Source code should go under a subdirectory called SOURCE. Each package should have its own subdirectory under the SOURCE directory. For example, source code to this install program would go under SOURCE\INSTALL. Source to the CLS program should go under SOURCE\CLS.
Documentation that is not part of a help system (for example, release notes) should go under a separate directory called DOC. Each package should have its own subdirectory under the DOC directory. For example, release notes and other non-help documentation for the install program would go under DOC\INSTALL.

If you need to create other directories as part of your own standard, and you would like for me to mention it here, please send me an email describing your new standard, what files you put there, and how it is used. Also describe for me why the BIN, HELP, SOURCE, and DOC directories don't work for this.

For example, with my FreeDOS distribution, I put the Micro-C compiler, Arrow Assembler, and VAL Linker all in the directory called CC. I did this because they all can be used for developing new software, and I wanted to keep them separate from the main FreeDOS programs.

Unless otherwise stated, FD-DOC HOWTO documents are copyrighted by their respective authors. FD-DOC HOWTO documents may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies. Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions.

All translations, derivative works, or aggregate works incorporating any FD-DOC HOWTO documents must be covered under this copyright notice. That is, you may not produce a derivative work from a HOWTO and impose additional restrictions on its distribution. Exceptions to these rules may be granted under certain conditions; please contact the FD-DOC HOWTO coordinator at the address given below.

In short, we wish to promote dissemination of this information through as many channels as possible. However, we do wish to retain copyright on the HOWTO documents, and would like to be notified of any plans to redistribute the HOWTOs.

If you have any questions, please contact the FD-DOC coordinator at jhall1@isd.net.