Windows 95 Application Setup Guidelines for Independent Software Vendors

Teri Schiele

May 1995

Abstract

This article describes a standard set of guidelines for installing applications on the Microsoft® Windows® 95 operating system. The purpose of these guidelines is to encourage all application developers to support the same general method of installation for all applications. The prime benefit is to users, many of whom have said they prefer a consistent installation method so that they do not need to learn a different method with each new software purchase. These guidelines also benefit the application developer by helping to standardize the organization and management of application files, thereby making initial installations, updates, and application removals easier.

Installation Program

The installation program plays the primary role in carrying out application installation. The program retrieves information from the user and the computer and installs the files and information needed to run the application successfully. Every installation program carries out these basic steps:

  1. Determines the user's hardware and software configuration and available disk space.

  2. Copies application executable and data files to the appropriate directories on the hard disk.

  3. Sets up the execution environment for the application by modifying existing files and adding entries to the registry.

An installation program (or a companion program) should also be prepared to update or remove an already installed application.

You are responsible for designing and implementing the installation program for your application. Windows does not provide a default installation program, but it does provide an Add/Remove Programs application in Control Panel that helps guide the user through starting the installation, update, or removal process. When the user chooses to install an application, Add/Remove Programs automatically checks the floppy and compact disc read-only memory (CD-ROM) drives for installation programs, searching for filenames such as SETUP.EXE and INSTALL.EXE. If a file is found and the user agrees to finish the installation, Add/Remove Programs starts the program and exits. After that, the started program is responsible for guiding the user through the rest of the installation process.

Designing the Installation Program

Your installation program should be a "good" Windows-based application, employing the standard Windows graphical user interface (GUI) to present users with options and status. It is recommended that you use the InstallShield SE Toolkit provided in the Microsoft Win32® Software Development Kit (SDK) to develop your installation programs. You should also read relevant sections of the Windows Interface Guidelines for Software Design for guidelines on how to design an application that is consistent with the look and feel of the Windows shell. It will also give you information on easy-to-implement features that will add value to your application and make use of new usability features in the shell.

Your installation program should always offer setup options. The following options are recommended:

Typical setup Installs the application with all of the most common settings and copies the most commonly used files. This should be the default setup option.
Compact setup Copies the fewest number of files needed to operate your application. This option is useful for laptops and computers on which disk space is at a premium.
Custom setup Allows the user to determine the details of the installation, such as the directories to receive the files and the application features to enable. This option, which is typically used by the power user, should also include an option to set up components left out during original setup.
Silent setup Runs the setup without user interaction. This should simply be a command line option so that your setup program can be run within a batch script.

Your installation program should always supply defaults. In particular, it should make sure you supply a common response to every option so all the user has to do is press the enter key.

Your installation program should never ask the user to install a disk more than once. The computer should beep when it is time for the user to insert a new disk.

Your installation program should always use a progress indicator to show users how far along they are in the setup procedure.

Your installation program should always give the user a chance to cancel setup before it is finished. Your program should keep a log of files that have been copied and settings that have been made so that it can clean up a canceled installation. If the installation is canceled, your program should remove any registry entries it may have made, remove any shortcuts it may have added to the desktop, and delete any files it may have copied onto the user's hard disk.

Determining the Configuration

Your installation program should determine the hardware and software configuration of the user's computer before copying files and setting the environment. It is important for the installation program to verify that everything needed to successfully run the application is available. For example, if your application depends on specific hardware or software, your installation program should make sure the hardware or software is present. If it is not, the program should notify the user immediately and recommend a course of action.

Your installation program should always tell the user how much disk space is needed. For custom setup, the installation program should adjust the "space needed" figure as the user selects and deselects options. Your installation program should verify that there is enough disk space for the options that the user selects. If there is not enough free space, the program should notify the user, but give the user the option to override the safety check.

Your installation program should always determine whether any of the files to be installed are already on the hard disk. This is especially important for shared files, such as commonly used dynamic-link libraries (DLLs). If the files already exist, your installation program should check the version number to ensure that it is not replacing a file with an older version. In other words, the program should always make sure the most recent version of a file is installed in the user's disk.

Copying Files

Your installation program should copy all necessary executable and data files to the appropriate directories. It should never copy files to the \WINDOWS or \SYSTEM directories. Instead, it should create your own directory in the \Program Files directory and copy its files there. If the \Program Files directory does not exist on the root of the hard disk, the installation program should create it.

It is recommended that your program use a long filename for the directory, such as the application name or another descriptive and unique name. Your program should copy the main executable file for your application and any other executable or data files that the user may want to open directly to the newly created directory. For example, if your application's name is My Wizzy Application.Exe, your installation program should create a directory called \Program Files\My Wizzy Application, and copy My Wizzy Application.Exe to that directory.

If you have any other executable or data files, such as .DLL and .HLP files that are specific to your application, your installation program should create yet another directory, named \System, in your application's directory. It should copy the remaining files (except shared files) to this new directory. For example, if your application has a .DLL named MWASUP.DLL, your installation program should create a directory called \Program Files\My Wizzy Application\System and copy the .DLL there.

If any of your executable or data files are shared, your installation program needs to copy the files to yet another directory, depending on how widely the file is to be shared. A file is a system-wide shared file if many applications from different vendors use it. For example, the VBRUN300.DLL file is a system-wide shared file because it is used by any application built with Visual Basic®. A file is a shared file if it is shared by a set of applications from the same vendor. A common example of this would be an office suite that might use the same drawing program for its word processor that it uses for its spreadsheet.

Your installation program should copy all system-wide shared files to the Windows \SYSTEM directory. If a given file already exists in this directory, the program should overwrite it with your application file only if your file is a more recent version. The GetFileTime, GetFileVersionInfo, and GetFileInformationByHandle functions can be used to determine which file is more recent. After copying a .DLL file, your installation program must make sure to increment the usage counter for that DLL in the registry. (For more information about the usage counter, see the section titled "Adding Entries to the Registry.")

Your installation program should copy all shared files to a \System directory in the \Program Files\Common Files directory. If the directory does not exist, the program should create it. Again, it is recommended that your program use a descriptive and unique name. For example, if there is a shared file named My Wizzy Speller.Exe, your program should create a directory called \Program Files\Common Files\System and copy the file there. The location of the \Program Files and \Common Files directories is registered under the HKEY_LOCAL_MACHINE root under the SOFTWARE\Microsoft\Windows\CurrentVersion key (use the REGSTR_PATH_SETUP macro). The value names are ProgramFilesDir and CommonFilesDir.

When your program installs applications on computers running Win32s® with Windows 3.x, it needs to be aware that the system does not support long filenames. It will need to use the 8.3 equivalent for Program Files and Common Files, which would be Progra~1 and Common~1, respectively.

Using a WININIT.INI File to Replace DLLs

Installation programs often need to replace old DLL files with new versions. However, the system does not allow a DLL file to be replaced if the DLL is currently loaded into memory. To solve this problem, your installation program must copy the new DLLs to the user's machine, giving each new DLL a temporary name that is different from that of the corresponding old DLL. Your installation program must also copy a file called WININIT.INI to the user's machine. The WININIT.INI file is processed by the WININIT.EXE program when the system is restarted, before any DLLs are loaded. The WININIT.INI file specifies the destination path and filename for each new DLL.

The WININIT.INI file contains a [rename] section that specifies the source and destination path and filenames for the new DLLs. The entries in the [rename] section have the following syntax:

DestinationFileName=SourceFileName

Use the following syntax to delete a file:

NUL=SourceFileName

The following example shows a [rename] section from a WININIT.INI file:

[rename]
C:\WINDOWS\Fonts\arial.ttf=C:\WINDOWS\Fonts\arial.win
C:\WINDOWS\SYSTEM\advapi32.dll=C:\WINDOWS\SYSTEM\advapi32.tmp

When the system is restarted, it searches for a WININIT.INI file and, if it finds one, runs WININIT.EXE on the file. After processing the file, WININIT.EXE renames it to WININIT.BAK.

Setting Up the Environment

Your installation program needs to set up the proper environment for your application. The environment consists of application-specific entries in the initialization files, the registry, and the Start button.

Setting Initialization Files

Windows 95 does not require the AUTOEXEC.BAT and CONFIG.SYS files. Because these files may not be present on the hard disk, you should make sure that your application does not require entries in those files.

Windows 95 does not require you to modify the PATH environment variable. Instead, it looks for your .EXE and .DLL files in the "per-application" path specified in the registry. Your installation program is responsible for setting the per-application path when it installs the application.

Windows 95 does not require that your application load device drivers at boot time. This means your application does not need to specify drivers in the CONFIG.SYS file. Instead, your application can dynamically load the drivers when it starts by using the virtual device loader functions of Windows or the CreateFile and DeviceIOControl functions of Win32.

Your installation program should not make entries in the WIN.INI file. It should use the registry instead. If you have information that you do not want to put in the registry, your installation program should create a private initialization file and place it in the same directory that contains your application's executable files.

Adding Entries to the Registry

Your installation program should add information about your application to the registry. In particular, it should always add the following entries:

HKEY_LOCAL_MACHINE\SOFTWARE\CompanyName\ProductName\Version

Store information pertaining to this particular copy of the application here.

HKEY_CURRENT_USER\SOFTWARE

Store user preferences on a per-user basis here. This is information that application vendors used to store in the WIN.INI file. For example, Word for Windows might store the fact that a user wants the autosave feature turned off here.

Your installation program should always add per-application paths to the registry for your application. If your program registers a path, Windows sets the PATH environment to be the registered path when it starts your application. Your program sets the path in the HKEY_LOCAL_MACHINE root under the \SOFTWARE\Microsoft\Windows\CurrentVersion\AppPaths key (use the REGSTR_PATH_APPPATHS macro). Your program must create a new key having the same name as your application's executable file. Under this new key, it creates the Path value name and assigns it a path using the same format as expected by the PATH environment variable.

The following example shows application-specific paths for both Excel.Exe and My Wizzy Application.Exe:

HKEY_LOCAL_MACHINE
  SOFTWARE\Microsoft\Windows\CurrentVersion\AppPaths
    Excel.Exe 
      Default=D:\Program Files\MS Office\Excel\Excel.exe
      Path= D:\Program Files\MS Office\Excel\Excel.exe;D:\Program Files\Common Files\MS Office;

    My Wizzy App.EXE
      Default=d:\Program Files\My Wizzy Application\My Wizzy Application.Exe
      Path= D:\Program Files\My Wizzy Application;D:\Program Files\My Wizzy Application\Application Extensions;

In the preceding example, the Default value specifies the full path to the corresponding executable file. This value is typically used by Windows in the Start Run command. If the user types the name of your application but Windows fails to find it in the current path, Windows uses this value to locate and start your application.

Your installation program should keep track of shared DLLs. When installing an application that uses shared DLLs, it should increment the use counter for the DLL in the registry. When removing an application, it should decrement the use counter. If the result is zero, the user should be given the option of deleting the DLL. The user should be warned that other applications may actually use this DLL and will not work if it is missing. The following example shows the general format for usage counters in the registry:

\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDLLs
    C:\Program Files\Common Files\System\vbrun300.DLL=3

Supporting Context Menu Operations

Your installation program can provide support for Context menu operations, such as Open, Print, and Print To, by setting appropriate registry entries. The Context appears when the user clicks the right mouse button on a document associated with your application.

Enabling "Print" in the registry gives the shell instructions about what to execute when the user selects Print from the Context menu. Usually an application will display a dialog that says "Printing page X of N on LPTX".

Enabling "Print To" in the registry specifies the default action for "drag print." "Print To" displays the same dialog box as "Print" when you drag to a specific printer. The "Print To" option is not displayed on the menu, so it does not bring up anything (that is, it cannot be selected).

The following example shows how to set commands for the Context menu for files having the .TXT and .RTF filename extensions:

HKEY_CLASSES_ROOT\.txt = txtfile
HKEY_CLASSES_ROOT\txtfile = Text File
HKEY_CLASSES_ROOT\txtfile\DefaultIcon = c:\chicago\WRITEPAD.EXE,0
HKEY_CLASSES_ROOT\txtfile\shell\open\command = WRITEPAD.EXE %1
HKEY_CLASSES_ROOT\txtfile\shell\print\command = WRITEPAD.EXE /p %1
HKEY_CLASSES_ROOT\txtfile\shell\printto\command = WRITEPAD.EXE /p %1

HKEY_CLASSES_ROOT\.rtf = rtffile
HKEY_CLASSES_ROOT\rtffile = Rich Text File
HKEY_CLASSES_ROOT\rtffile\DefaultIcon = c:\chicago\WRITEPAD.EXE,0
HKEY_CLASSES_ROOT\rtffile\shell\open\command = WRITEPAD.EXE %1
HKEY_CLASSES_ROOT\rtffile\shell\print\command = WRITEPAD.EXE /p %1

Adding the Application to the Start Button

Your installation program can still create a "Program Group" in the Programs folder by using dynamic data exchange (DDE) as used in Windows version 3.1. However, this is no longer the preferred method. Instead, your installation program should add an icon for your primary application to the Start Programs menu. The program can, optionally, prompt the user to choose which program icons to place in the menu, but icons should not be added for every application in your package and an extensive hierarchy of programs and folders should not be created on this menu.

To add an icon to the Start program menu, your installation program should create a link to your application's executable file and place the link in the \WINDOWS\STARTMEN\PROGRAMS directory. (Note that the \WINDOWS directory should actually be the path returned by the GetWindowsDirectory function.) An installation program can create a link by using the IShellLink interface.

Using Filename Extensions

In Windows 95, filename extensions should always describe a file type. Your installation program should not rename old or backup files by changing them to filename extensions such as .001 or .BAK or .XX1. If the file type does not change, the program should give the file a new name. For example, it can use long filenames to change the old version of a filename, such as SAMPLE.DLL, to Copy of SAMPLE.DLL.

The following table lists filename extensions currently used in Windows. Do not use these filename extensions unless your file fits the given type description.

Extension Type description
386 Windows virtual device driver
3GR Screen grabber for MS-DOS®–based applications
GR3 Windows 3.0 screen grabber
ACM Audio compression manager driver
ADF Administration configuration files
ANI Animated mouse cursor
AVI Video clip
AWD Fax viewer document
AWP Fax key viewer
AWS Fax signature viewer
BAK Backed-up file
BAT MS-DOS batch file
BFC Briefcase
BIN Binary data file
BMP Picture (Windows bitmap)
CAB Windows Setup file
CAL Windows Calendar file
CDA CD audio track
CFG Configuration file
CNT Help contents
COM MS-DOS program
CPD Fax cover page
CPE Fax cover page
CPI International code page
CPL Control Panel application
CRD Windows Cardfile document
CSV Command-separated data file
CUR Cursor (pointer)
DAT System data file
DCX Fax viewer document
DLL Application extension (dynamic-link library)
DOC WordPad document
DOS MS-DOS file (also extension for NDIS2 net card and protocol drivers)
DRV Device driver
EXE Application
FND Saved search results
FON Font file
FOT Shortcut to font
GR3 Windows 3.0 screen grabber
GRP Program group file
HLP Help file
HT HyperTerminal file
ICM Image color matching (ICM) profile
ICO Icon
IDF MIDI instrument definition
INF Setup information
INI Configuration settings
KBD Keyboard layout
LGO Windows logo driver
LIB Static-link library
LNK Shortcut
LOG Log file
MCI MCI command set
MDB File viewer extension
MID MIDI sequence
MIF MIDI instrument file
MMF Microsoft Mail message file
MMM Animation
MPD Mini-port driver
MSG Microsoft Exchange mail document
MSN The Microsoft Network home base
MSP Windows Paintbrush picture
NLS Natural language services driver
PAB Microsoft Exchange personal address book
PCX Picture (PCX format)
PDR Port driver
PF ICM profile
PIF Shortcut to MS-DOS–based application
PPD PostScript printer description file
PRT Printer formatted file (result of Print to File option)
PST Microsoft Exchange personal information store
PWL Password list
QIC Backup set for Microsoft Backup
REC Windows Recorder file
REG Application registration file
RLE Picture (RLE format)
RMI MIDI sequence
RTF Document (rich-text format)
SCR Screen saver
SET File set for Microsoft Backup
SHB Shortcut into a document
SHS Scrap
SPD PostScript printer description file
SWP Virtual memory storage
SYS System file
TIF Picture (TIFF format)
TMP Temporary file
TRN Translation file
TSP Windows telephony service provider
TTF TrueType font
TXT Text document
VBX Visual Basic control file
VER Version description file
VXD Virtual device driver
WAV Sound wave
WPC WordPad file converter
WRI Windows Write document
XAB Microsoft Mail address book

Also investigate extensions commonly used by popular applications so you can avoid creating a new extension that might conflict with them, unless you intend to replace or supersede the functionality of those applications.

Register Document Types

Your installation program should register every file type used that is not provided by Windows 95.

Network Issues

Most corporate customers would like to run their applications from a network server. To support running from a server, you need to provide your application in both a server and client package. The server package consists of executable files, DLLs, data files, and any files that must be shared across the network. The client package consists of the portions of the application that are user-specific, including registry settings, the user's configuration information, and information on how to locate the server package.

Generally, you should have two setup programs or modes for installing the packages: an administrative setup program that an administrator runs for preparing the server, and a client setup program that runs on each client machine and sets up the connection to the server. The client setup program should also have a batch or silent installation option so that an administrator can deploy your application with automatic software distribution tools. Ideally, the client setup functions are built into the application so that it configures itself when it starts (perhaps by reading options set by the administrative setup program).

Corporate customers typically run Windows from a shared copy on a server. The following directories are stored on the server. Your application and client setup program may or may not have write access to these directories.

\Windows
    \Command
    \Inf
    \Fonts
    \Help
    \Hyperterm
    \Pif
    \System
        \Color
        \Iosubsys
        \Viewers
        \VMM32

To find the System directory, use the GetSystemDirectory function. To find the Windows directory, look in the following registry location:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Setup
    SharedDir=

Your application should store files that cannot be shared (machine-specific files) in a "home" directory with write access. The home directory should not contain any executable files. You can find the home directory by calling the GetWindowsDirectory function. The following files and directories are stored in the home directory:

Files Directories
WIN.COM \Spool
WININIT.EXE \Desktop
*.INI \Startmen
*.GRP \Nethood

Your application and setup program should fully support Universal Naming Convention (UNC) paths. If an application is being installed on a network path, the installation program should store a UNC path in any shortcuts it makes for the Start menu. Your program can use the Windows network functions (WinNet*) to determine if a path is a network path.

You should consider what configuration settings an administrator might want to set for a user and what restrictions an administrator might want to place on a user (for example, not letting a user access a configuration menu). You should put these settings and restrictions in a System Policy template file.

CD-ROM Considerations

Auto-run is a feature that is supported on CD-ROM drives. When the user loads a compact disc (CD) into the drive, Windows 95 automatically runs a file on the CD. The file to run must be specified in an AUTORUN.INF file located in the CD's root directory. The following example shows a typical entry in an AUTORUN.INF file:

[AutoRun]
OPEN=myprog.exe

The auto-run feature can be disabled by the device manager or by an entry in the SYSTEM.INI file. Your application must not rely on the auto-run feature being available. Also, the auto-run feature should not be used to automatically install your application on the user's hard disk without asking the user first.

If you provide your application on a CD, your installation program should give the user the choice of running the application from the CD-ROM or installing it on the hard disk. You should keep the following points in mind:

Installing Fonts

By using the following procedure, you can write a single font installation routine that works for both Windows NT and Windows 95:

  1. Determine whether the platform is Windows 95 or Windows NT. This is important because Windows 95 allows a shared network installation where most system files, including fonts, are stored on a centrally managed server. To determine the platform, look in the following registry location for a "SharedDir" key:
    HKeyLocalMachine\Software\Microsoft\Windows\CurrentVersion\Setup
    

    The data value of the "SharedDir" key is the UNC name of the server and sharepoint of the shared directory. In most cases, a shared directory is marked as read-only by the system administrator, so your program should also check to see if it can write to this location. If it cannot, it should let the user install the fonts in a different location, or stop the setup process.

  2. Check to see if the TrueType® font being installed is already present on the system, by using the EnumFontsEx function. If a font is present, the program should check to see if its version is newer by matching the installed font name with the filename on the disk. The font name is stored in the following registry location for both Windows 95 and Windows NT:
    HKeyLocalMachine\Software\Microsoft\Windows\CurrentVersion\Fonts
    

    The subkeys in this registry location contain the full name of the font file as the value key, followed by the name of the .TTF file as the key data. If the filename in the registry is simply a filename with no path information, the font is installed in the \WINDOWS\FONTS directory for Windows 95, or the \WINDOWS\SYSTEM directory for Windows NT. Because TrueType font files do not carry a version resource, your program will need to retrieve the version string from the 'name' table in the .TTF file.

Removing an Application

By adding the following entries to the registry, your installation program can direct the Add/Remove Programs application in Control Panel to list your application as an application that can be "automatically removed":

HKEY_LOCAL_MACHINE
\Software\Microsoft\Windows\CurrentVersion\Uninstall\application-name
   DisplayName=product-name
   UninstallString=full-path-to-program command-line-parameters

Add/Remove Programs displays the product name specified by the DisplayName value in its list of applications that can be removed. Windows uses the value specified by the UninstallString value to start the program to carry out the removal of the application. This string needs to completely specify the command-line parameters needed to execute the program and remove the application. A full path is required. If both the DisplayName and UninstallString values are not complete, Add/Remove Programs will not list the application.

Windows 95 needs to know when the removal of the application is done, so it requires that the UninstallString value specify the program that actually carries out the removal. A batch file or other program that starts the removal program should not be specified.

Your installation program should use casual names, including spaces, for the application-name and DisplayName value. This helps keep the tree comprehensible for users who browse the registry. The registry locations are defined as constants for C programmers in the REGSTR.H header file. The macros are:

REGSTR_PATH_UNINSTALL Path to uninstall branch
REGSTR_VAL_UNINSTALLER_DISPLAYNAME DisplayName
REGSTR_VAL_UNINSTALLER_COMMANDLINE UninstallString

The uninstall program must display a user interface that informs the user that the removal process is taking place. It is recommended that you use the sample uninstall program in the InstallShield SE Toolkit as the starting point for your own program. The sample illustrates the appropriate user interface and application removal tasks.

Your uninstall program should provide a silent option that allows the user to run it remotely. The uninstall program should also display clear and helpful messages for any errors it encounters during the removal of the application. Windows will only detect and report a failure to start the uninstall program.

Because computers running Win32s and Windows NT do not provide the Add/Remove Programs in Control Panel, your installation program needs to provide an icon in the applications program group for the user to launch the uninstall program.

To summarize, an uninstall program should complete the following steps:

Quick Checklist

You should keep the following points in mind when you plan an installation program for your application: