The FreeDOS Install Program, 2.2

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.

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 do plan to continue maintaining my FreeDOS install program. The current version [2.2] supports installing from floppy disk, hard disks, or CD-ROM. You may run the install program from a boot floppy. The next few major releases will incorporate these features:

Version 3.0 - Will change from a text-oriented program to a full-screen install application. This version will incorporate colors, progress indicators, and all sorts of bells and whistles.
Version 4.0 - Will add better package management tools.

There may be maintenance releases (bug fixes) between each major version.

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.

You will then see a prompt asking you if you really want to proceed with the installation. I put this prompt here in case you have run this install program without meaning to. I don't want someone to mistakenly allow Windows 95 to run an install program if you only wanted to run a directory of the boot disk! Press y to continue with the installation, or q to quit the Install program and return to the DOS prompt.

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 and Drivers 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 (the Beta 1 distribution is about 8MB) should be able to 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.

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:

Install.exe
This is the install program.

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.

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: ?

name.TXT
The name.TXT file replaces the INSTALL.TXT file. This file contains a description of the disk series, and will be printed to the screen when the Install program needs to display the description. The name.TXT file is named by replacing name with the name of the disk series. For example, for the Base disk series, the file would be BASE.TXT.

Here is an example SOURCE.TXT file, for the Source disk series:

  Source to all the FreeDOS programs.  This can get pretty
  large, so you should not install it unless you plan to
  contribute to the FreeDOS project.

Disk series

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

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

  COMMAND: Y
  KERNEL: ?

Package info files
There are a number of package info files that the current release [2.2] of the Install program will support:

package.RPH
This is a Red Hat Package Header file, which is simply the header for an RPM file. For more information on creating RPH files, read the RPM Howto.
The RPM Howto does not specifically address RPH files, because an RPH file is not really part of the Red Hat Package definition. However, I have spoken with Erik Troan at Red Hat Software about RPH files, and he indicates that my definition and usage does not conflict with anything that Red Hat is doing.
The following is an example of a Red Hat Package Header file:
```
  Name: hello
  Version: 1.2
  Release: 1
  #Author: Jim Hall
  Summary: this is the short summary.  you can continue to \
  the next line using a '\' at the end of a line.
  Icon: file.gif
  Source: http://www.isd.net/jhall1/hello12x.zip
  Patch: http://www.isd.net/jhall1/hello12.fix
  Copyright: GPL
  Root: (ignored)
  Group: (ignored)
  %description
  This is the long description.  This can be many lines long, and is
  terminated either with a blank line, or by the end of the file,
  whichever comes first.
```

package.DSC
This is a Debian Description File. For more detail on how to create a Debian Description File, please refer to Making a Debian Package and Debian Package Manual.

The following is an example of a Debian Description File:

  Source: empire
  Section: games
  Priority: extra
  Maintainer: Jaldhar H. Vyas 
  Standards-Version: 2.3.0.0
  
  Package: empire
  Architecture: any
  Depends: ${shlibs:Depends}
  Description: an empire-building strategy game
   A solitaire empire game (sometimes called 'VMS Empire'), colorized and
   speed tuned and with a save-interval option.
   .
   In this game a player has to try to build and defend an empire.

package.LSM
This is a standard Linux Software Map file. [This will be implemented in version 2.2] 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

Note that the name of the package is the base name. The install program currently uses Zip as its package manager, but the name of the package does not include the .ZIP extension.

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, plus package info files.

Modifying the FreeDOS Distribution

My FreeDOS distribution is based on 1.44MB disks. I chose this size because most of our current FreeDOS users have 1.44MB disk drives.

However, there are probably some of you who think I am an idiot, because FreeDOS is supposed to run on all PC's, including the XT, and your XT only has a 360kb floppy drive. What do you do now?

Well, you have two options:

Download the entire FreeDOS distribution to your XT's local hard disk, and make sure all the packages and DAT and END files are put into a single directory. The FreeDOS program will have no problems installing from a single directory, so long as all the install files are in that same directory.
You can convert your 1.44MB floppies to 360kb floppies.

Here is how to convert the 1.44MB install disks to any other size floppy:

First, divvy up the packages from a disk series onto as many 360kb floppies that you need. If the, say, Base series takes two 1.44MB floppies, then you'll probably need about eight 360kb floppies.
Don't forget to keep the package info file with the package file (ZIP file), or you won't be able to see the package description before the package is installed.
On each of the disks in a disk series, create a name.n file. For the Base series, the first disk will have a file called BASE.1, the second disk will have BASE.2, and so on. Each file must contain a list of the files on that install disk, with the package's rank.
To make it easy on yourself, you can give all the packages a rank of Y. This will install everything, which is probably more than you need, but it won't hurt anything except your disk space.
On the last disk in a disk series, make sure there is a name.END file. For the Base disk series, you need a BASE.END file. This can be an empty file; the contents of the file do not matter.

That's it. The contents of the Install disk (the INSTALL.DAT file, etc.) do not need to be modified. Now, just run the Install program, and if you followed the steps carefully, everything should be okay.

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. It applies its own standard when it creates its releases. 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.

Comments and suggestions on this document are welcome! Please email me at jhall1@isd.net

Back to FreeDOS page