The Microsoft Setup Toolkit for Windows -- A TutorialLast reviewed: July 23, 1997Article ID: Q89572 |
3.10
WINDOWS
kbtool
The information in this article applies to:
SUMMARYThe information below demonstrates the basic functionality of the Microsoft Setup Toolkit for Windows that is included with version 3.1 of the Microsoft Windows Software Development Kit (SDK). The Setup Toolkit is a collection of tools and programs designed to build a "setup" disk, that is, a disk (or group of disks) that install one or more files onto a client's computer system. Because the Setup program itself is designed for the Microsoft Windows graphical environment, the Toolkit is primarily aimed at building installation disks for the Windows environment. Functions in the Toolkit copy software and other data files to the target disk, add groups and items to the Microsoft Windows Program Manager, and create or modify initialization (.INI) files. This tutorial does not discuss all of these features; it concentrates on using the setup disk layout tools and on creating a "basic" setup disk. This tutorial covers the following topics:
This tutorial does not discuss the following tasks:
MORE INFORMATIONThe Setup Toolkit contains three major component groups:
As outlined in the "Setup Toolkit for Windows" manual provided with the Windows SDK, using the Setup Toolkit involves seven steps, as follows:
This tutorial concentrates on steps 1, 2, and 6. The remainder of this article is organized as follows:
Identify the Files to InstallTo build setup disks, it is necessary to determine the files to install on the target system. This tutorial outlines the procedures to install the Generic application, one of the sample applications discussed in the Windows SDK "Guide to Programming" manual. Feel free to substitute other files if Generic is not readily available. Under normal circumstances, installing an application would not involve installing source code (source code might be an optional item). However, the steps outlined below install the source code to Generic along with its executable file. The source files are listed below in the discussion of directory structure. NOTE: Make sure that you build the Generic executable before the first exercise. For more information, see Chapter 1 of the "Guide to Programming" manual. In addition to the installed files, you must include some Setup Toolkit files on the setup disks. The process marks these files to prevent them from being installed on the client's system.
Design a Directory StructureGiven the list of files to install, determine where the files belong on the client's system. As a practical matter, it helps to build the directory structure and to copy the files into it. Then you can build setup disks from these files. If disk space is very tight, you may not be able to build the complete tree structure. In that case, remember that the Dsklayt utility cannot change directories. Therefore, you must start it in a directory that can access all the needed files, including the Toolkit files. This tutorial discusses these considerations in more detail below.
Exercise 1: Files and DirectoriesThis exercise uses the following directory structure:
Root | +Generic | +SourcesIn other words, the GENERIC directory is a child of the root and it has a subdirectory named SOURCES. Copy all the files from the SDK Guide samples GENERIC directory into the GENERIC\SOURCES directory. Move GENERIC.EXE from the SOURCES directory to the GENERIC directory. Copy the following files from the SDK Setup Toolkit directory into the GENERIC directory: all .EXE files, all .DLL files, all .INC files, SAMPLE1.MST, and SETUP.LST. The files marked with "<<<" in the list below are not required for all installations. The FILEDESC.WRI file details when these files are needed. Although it is always safe to include these files, they consume space on the setup disks. If you create the GENERIC directory from the root of the C drive, the MS-DOS TREE utility (tree \generic /f /a) shows the directory structure as follows:
C:GENERIC | GENERIC.EXE | _MSSETUP.EXE | _MSTEST.EXE | MSCOMSTF.DLL | MSCUISTF.DLL | MSDETECT.INC | MSDETSTF.DLL | MSINSSTF.DLL | MSREGDB.INC <<< | MSSHARED.INC <<< | MSSHLSTF.DLL | MSUILSTF.DLL <<< | SAMPLE1.MST | SETUP.EXE | SETUP.LST | SETUPAPI.INC | \---SOURCES GENERIC.C GENERIC.DEF GENERIC.H GENERIC.MAK GENERIC.OBJ GENERIC.RC GENERIC.RES GENERIC.STS MAKEFILE User Parameters, Dialog Boxes, and ScriptsDuring the process of designing how to install an application, it is necessary to determine items that the user must select or specify. These could include optional files (such as the source directory in this example), the drive and directory to install to, the registered owner's name, and so forth. After gathering this information, the next step is to modify the dialog boxes and rebuild the resource dynamic- link library (DLL) that Setup uses. Choose one of the sample setup scripts and modify it as required. The exercises below involve some minor modifications to the SAMPLE1.MST script. For more information on the resource DLL, see the Setup BDLCUI (build customer interface) directory.
Creating the Setup Disk ImagesThe user runs the Setup program from floppy disks. The Toolkit provides two programs that arrange the files and create floppy disks. Dsklayt, the first layout program, runs in the Windows environment. Use this tool to specify the files to include in the setup disk images and the characteristics of the files. Dsklayt2, the second layout program, runs in the MS-DOS environment (outside Windows) and reads the layout (.LYT) file that Dsklayt creates. Dsklayt2 creates disk images and the information (.INF) file the Setup program uses to install files from the floppy disks to the target system. Because the Toolkit program files must be on the first setup disk but should not be installed on the target system, you must edit the information file that Dsklayt2 creates. Note the following considerations when building the file layout and disk images:
Exercise 2: Using the Dsklayt ProgramThe Dsklayt utility runs in the Windows environment. If you use the Toolkit often, you might find it convenient to create an icon in the Program Manager that runs the Dsklayt utility. When the program first starts, Dsklayt determines if you want to create a new layout or open an existing layout. For this exercise, create a new layout. For the source directory, specify the GENERIC directory created in Exercise 1. Dsklayt displays all the files in the specified directory, including all the files in all the subdirectories. Initially, each file is selected to be included on the setup disks and each has the following attributes:
Exercise 3: Modifying the SETUP.LST FileThe SETUP.LST file is included with the Toolkit. It lists the files that the Setup program copies into a temporary directory. The default SETUP.LST file assumes that the other Toolkit files are not compressed. To correct this assumption, you must edit the file. SETUP.LST contains two sections, labeled [Params] and [Files]. The [Files] section of the default SETUP.LST file is as follows:
[Files] sample1.mst = sample1.mst sample1.inf = sample1.inf setupapi.inc = setupapi.inc msdetect.inc = msdetect.inc mscomstf.dll = mscomstf.dll msinsstf.dll = msinsstf.dll msuilstf.dll = msuilstf.dll msshlstf.dll = msshlstf.dll mscuistf.dll = mscuistf.dll msdetstf.dll = msdetstf.dll _mstest.exe = _mstest.exe _mssetup.exe = _mssetup.exeIt is necessary to modify entries in this section to indicate that some of the files are compressed. To ease the process of identifying a compressed file, the last character of the filename extension of a compressed file is replaced with an underscore (_) character. Use any file editor (for example, the Edit application for MS-DOS or the Notepad application for Windows) to change the [Files] section as follows:
[Files] sample1.ms_ = sample1.mst sample1.inf = sample1.inf setupapi.in_ = setupapi.inc msdetect.in_ = msdetect.inc mscomstf.dl_ = mscomstf.dll msinsstf.dl_ = msinsstf.dll msuilstf.dl_ = msuilstf.dll msshlstf.dl_ = msshlstf.dll mscuistf.dl_ = mscuistf.dll msdetstf.dl_ = msdetstf.dll _mstest.ex_ = _mstest.exe _mssetup.ex_ = _mssetup.exeThe SAMPLE1.INF file (the information file created with Dsklayt2 in Exercise 5 below) will not be compressed. You will edit this file later in Exercise 5.
Exercise 4: Modifying the SAMPLE1.MST Script FileThe SAMPLE1.MST script file performs a few steps that are not necessary for this example. SAMPLE1.MST creates an initialization (.INI) file for the installed application and it adds a program group and icon to the Windows Program Manager. Although these steps are useful for an actual Setup program, they create unnecessary work for testing purposes. This exercise modifies the setup script to eliminate these unnecessary steps. Instead of removing lines from the setup script, this exercise involves inserting the comment character at the beginning of the unnecessary lines of the file. (In an actual setup script, removing lines is more efficient and uses less disk space.) An apostrophe (') character at the beginning of a line marks the line as a comment. Using a file editor, comment out lines 182 and 184-197. After inserting the comment characters, lines 182 through 198 appear as follows: <line 181 follows> AddSectionFilesToCopyList "Files", SrcDir$, DEST$ ' AddSectionKeyFileToCopyList "Options", OPTCUR$, SrcDir$, DEST$ CopyFilesInCopyList ' ini$ = MakePath(DEST$, "DEMO.INI") ' CreateIniKeyValue "WIN.INI", "MSSetup Sample 1", "Option",OPTCUR$, cmoNone ' CreateIniKeyValue ini$, "Section 1", "Key 1", "Value 1" , cmoNone ' CreateIniKeyValue ini$, "Section 2", "Key 2", "Value 2" , cmoNone ' CreateIniKeyValue ini$, "Section 3", "Key 3", "Value 3" , cmoNone ' CreateProgmanGroup "MSSetup Sample 1", "", cmoNone ' ShowProgmanGroup "MSSetup Sample 1", 1, cmoNone ' CreateProgmanItem "MSSetup Sample 1", "dialogs", "dlgedit.exe"+MakePath(DEST$,"dialogs.res"), "", cmoOverwrite ' CreateProgmanItem "MSSetup Sample 1", "dlgprocs.c", "notepad.exe"+MakePath(DEST$,"dlgprocs.c"), "", cmoOverwrite
' AddDos5Help "YOURAPP", "A brief help text for your Windows-basedapplication."+chr$(10)+"It can be continued on another line with chr$(10).", cmoNone
CloseLogFile<last line was 198> NOTE: Due to the margins of this document, a few of the lines in the file "wrapped" and require more than one line above.
Exercise 5: Using the Dsklayt2 programDsklayt2 is an application for MS-DOS that reads the layout information file that Dsklayt creates (in this case SAMPLE1.LYT) and creates two items: a set of disk images and an information file. The disk images are used to build setup disks. The Setup program uses the information file to place the files on the target disk. The Dsklayt2 program accepts several parameters, some of which are required for the application to work. For this exercise, set the current directory to the GENERIC directory created in Exercise 1 and issue the following command:
dsklayt2 sample1.lyt c:\disk1\sample1.inf /k144 /f /dc:\ /cc:\compThe individual terms of this command line are as follows:
[Source Media Descriptions] "1", "disk1", "_mstest.exe", "..\disk1"[Default File Settings] "STF_BACKUP" = "" "STF_COPY" = "YES""STF_DECOMPRESS" = "YES" "STF_OVERWRITE" = "ALWAYS" "STF_READONLY" = "YES" "STF_ROOT" = "" "STF_SETTIME" = "YES" "STF_TIME" = "0" "STF_VITAL" = "YES"[Files] 1, generic.h,,,, 1992-03-23,,,, !READONLY,, sources\generic.h 1, generic.rc,,,, 1992-03-23,,,, !READONLY,, sources\generic.rc 1, generic.res,,,, 1992-06-04,,,, !READONLY,, sources\generic.res 1, generic.def,,,, 1992-03-23,,,, !READONLY,, sources\generic.def 1, generic.mak,,,, 1992-05-21,,,, !READONLY,, sources\generic.mak 1, makefile,,,, 1992-03-23,,,, !READONLY,, sources\makefile 1, generic.sts,,,, 1992-06-30,,,, !READONLY,, sources\generic.sts 1, generic.c,,,, 1992-03-23,,,, !READONLY,, sources\generic.c 1, generic.obj,,,, 1992-06-04,,,, !READONLY,, sources\generic.obj 1, generic.exe,,,, 1992-06-04,,,, !READONLY,,,,,, 30456,,,,,
Exercise 6: Create Setup Disks and TestAt this stage of the process, an installation disk image is available in the C:\DISK1 directory. (If you chose to specify 720K disks, you probably have two disk image directories: C:\DISK1 and C:\DISK2.) To create installation disks, copy all the files from each disk image directory to a corresponding floppy disk (label the disks to keep them in order). To test the installation, place the first disk in a floppy disk drive and run the Setup program from the Program Manager or the File Manager. Because these exercises did not change the setup script (in any major way) or modify the dialog boxes, the Setup program includes some screens that are not required by this particular demonstration. Specify any desired target drive and directory. If you choose the default, C:\DEMO, SETUP creates a DEMO directory that contains two files, GENERIC.EXE and a .LOG file, and a SOURCES subdirectory with the other files.
SummaryThis tutorial covered the following topics:
|
Additional reference words: 3.10 MSSetup tool kit
© 1998 Microsoft Corporation. All rights reserved. Terms of Use. |