DOCUMENT:Q89572 04-NOV-1999 [win16sdk] TITLE :The Microsoft Setup Toolkit for Windows -- A Tutorial PRODUCT :Microsoft Windows Software Development Kit PROD/VER:WINDOWS:3.1 OPER/SYS: KEYWORDS:kb16bitonly ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - Microsoft Windows Software Development Kit (SDK) 3.1 ------------------------------------------------------------------------------- SUMMARY ======= The 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: - Selecting the files to install on the client's system - Including the required Toolkit files on the setup disks - Creating the required directory structure on the client's system - Controlling file compression - Using the Dsklayt and Dsklayt2 utilities in the Setup Toolkit This tutorial, which uses the sample script file included with the Toolkit (with minor modifications), is designed to provide an overview of the capabilities of the Toolkit. Before applying the Toolkit to any particular task, additional information and preparation is required. This tutorial does not discuss the following tasks: - Modifying the dialog boxes in Setup. - Modifying the setup scripts (beyond the minimum changes required to accomplish the tutorial's objectives). - Using the Setup procedures. (Even though the tasks in this tutorial use Setup procedures, the tutorial does not discuss them in any detail.) MORE INFORMATION ================ The Setup Toolkit contains three major component groups: 1. The disk layout utilities that create "setup" disks. A client uses the setup disks to install software onto a target system. The primary focus of this tutorial is these utilities and how to use them. 2. The setup tools required to install the software. Microsoft provides the setup tools in the SDK. The setup tools must be included on the setup disks. This tutorial discusses the setup tools only briefly. 3. Dialog boxes, sample setup scripts, and other files that control the appearance and operation of the Setup program. These factors are either ignored by this tutorial or are discussed at only the most basic level. The Setup Toolkit directory (by default, C:\WINDEV\MSSETUP or C:\C700\MSSETUP) contains two information files in Microsoft Windows Write format: README.WRI and FILEDESC.WRI. These files provide a great deal of reference information. As outlined in the "Setup Toolkit for Windows" manual provided with the Windows SDK, using the Setup Toolkit involves seven steps, as follows: 1. Identify the files to install. 2. Design a directory structure for those files. 3. Identify all user-defined parameters. 4. Design the required dialog boxes. 5. Modify the sample script files. 6. Create images of the installation disks. 7. Test the setup disks. This tutorial concentrates on steps 1, 2, and 6. The remainder of this article is organized as follows: - Discuss steps 1 and 2 (identify files and directories) - Exercise 1: Create a directory of files to install - Briefly discuss steps 3, 4, and 5 (parameters, dialog boxes, script files) - Discuss step 6 (create disk images) - Exercise 2: Use the Dsklayt utility - Exercise 3: Modify the setup list file - Exercise 4: Modify the script file - Exercise 5: Use the Dsklayt2 utility - Exercise 6: Create and test the setup disks Identify the Files to Install ----------------------------- To 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 Structure ---------------------------- Given 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 Directories --------------------------------- This exercise uses the following directory structure: Root | +Generic | +Sources In 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 Scripts ------------------------------------------ During 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 Images ------------------------------ The 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: - Because Dsklayt cannot change directories, all Toolkit files must be in the same directory as the project code. Although Dsklayt reads subdirectories, it does not read parent directories. The GENERIC directory was designed as outlined above to address this limitation. - In the Dsklayt utility, place the Toolkit files on disk 1. The default file settings specify compressed files. Two of the Toolkit files, SETUP.EXE and SETUP.LST, must not be compressed. If you compress the other files, you must edit the SETUP.LST file to account for the compression. The exercises below show how to do this. - Dsklayt2 builds an .INF file, which is required by the Setup program. When you run Dsklayt to specify the files to include in the disk images, the .INF file has not yet been created, which prevents you from listing it in the disk images. Dsklayt2 compensates for this and places the .INF file on setup disk 1 as required. However, Dsklayt2 compresses the .INF file and places a compressed copy of the .INF file with the extenxion .IN_ in the disk image directory. To work around this, copy the .INF file to the disk image directory before copying the files to the floppy disks. - The .INF file that Dsklayt2 creates instructs the Setup program to copy all the files. The only method of preventing the Setup program from copying the Toolkit files (SETUP.EXE and so forth) along with the program is to edit the INF file. Instructions on modifying the .INF file are presented in the exercises below. - The Dsklayt2 program provides the /k option to build 360K setup disks. However, most of the Toolkit files must be compressed to fit on a 360K disk. Exercise 2: Using the Dsklayt Program ------------------------------------- The 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: - Install on any disk - Vital file (this file must be present or the Setup program fails) - Compress file when laying out setup disks - Check for version information - Always overwrite existing file on target disk - Decompress file when installing on target disk - Mark file as read-only on target disk These options are not the best for most situations. They cause particular problems when they are applied to the Toolkit files. Therefore, change these default attributes as follows: 1. Select all the files by clicking the mouse on the first file in the files list box and dragging to the last file. Alternatively, use the arrow keys to place the cursor on the first file, press the SPACEBAR to select the file, and press SHIFT+END to select all the files. 2. Cancel the selection for the following options: - Check For Version - Mark As Read-Only 3. Select SETUP.EXE and clear the Compress check box. 4. Select SETUP.LST and clear the Compress check box. 5. Select all the Toolkit files. (In this exercise, these are all the files in the GENERIC directory except for GENERIC.EXE.) Mark these files for setup disk 1. 6. To create the SOURCES directory on the target disk and place the source files in this new directory, each file in the SOURCES directory must be renamed when the Setup program copies it from the setup disks. To rename the files: a. Select the first file in the SOURCES directory. b. Select the Rename Copied File check box. c. In the Edit box, type "sources\" (without the quotation marks) followed by the name of the file. d. Repeat steps a-c for each file in the SOURCES directory. For example: a. Select the GENERIC.C file in the Sources directory. b. Select the Rename Copied File check box. c. Type the following in the Edit box: " sources\generic.c " (without the quotation marks) 7. From the File menu, choose Save to store the layout. Give it the name SAMPLE1.LYT. Be sure to specify the GENERIC directory. The default in Dsklayt is to save the file in the MSSETUP\DISKLAY directory. 8. Close Dsklayt. Exercise 3: Modifying the SETUP.LST File ---------------------------------------- The 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.exe It 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.exe The 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 File ------------------------------------------------- The 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: 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-based application."+chr$(10)+"It can be continued on another line with chr$(10).", cmoNone CloseLogFile 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 program -------------------------------------- Dsklayt2 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:\comp The individual terms of this command line are as follows: - "dsklayt2": The filename of the Dsklayt2 application. Because the Toolkit installs Dsklayt2 in the Windows SDK MSSETUP\DISKLAY directory, the full path to this file is required unless this directory is in the MS-DOS PATH environment variable. If you use this utility often, you might want to add the directory to the PATH or place the full command into a batch file. - "sample1.lyt": The layout file produced by the Dsklayt utility. - "c:\disk1\sample1.inf": The filename for the created information file. Specifying this path ensures that Dsklayt2 places the information file on setup disk 1 (see the discussion of the /d parameter, below). - "/k144": The size of the setup disks. Valid options are 360 (for 360K disks), 720 (for 720K disks), 12 (for 1.2 MB disks), 144 (for 1.44 MB disks), and N (for a network installation). - "/f": Overwrite the .INF file if one already exists. This parameter is not required unless you run Dsklayt2 more than once and specify the same destination directory. - "/dc:\": The destination directory for the disk images. If you omit the /d option, Dsklayt2 creates only an .INF file (no disk images). Specifying "c:\" causes Dsklayt2 to create the disk images in directories named "disk1," "disk2," and so forth in the root directory of drive C. - "/cc:\comp": Storage for compressed files before they are copied into the disk images. This parameter is optional. However, if it is necessary to build the disk images more than once, specifying a location to store the compressed files speeds the process considerably. After running Dsklayt2, you must edit the information file (C:\DISK1\SAMPLE1.INF) to prevent the Toolkit files from being copied to the target disk. Use a file editor to remove the lines in the [Files] section that refer to the Toolkit files. The resulting file contains only references to the files in the Generic sample application and look like the text below. Note that the lines in the [Files] section have been edited to fit the margins of this document. [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 Test --------------------------------------- At 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. Summary ------- This tutorial covered the following topics: - Creating a target directory structure for files to install and placing the files into the structure - Using the Dsklayt utility to map the files onto setup disks - Using the Dsklayt2 utility to create disk images - Modifying the setup script and information file to make the setup process flow smoothly and to prevent extra files from being created - Copying the disk images onto floppy disks - Testing the setup disks to verify that the disks work correctly The following directories were created by the exercises in this tutorial if the directory names listed were used: COMP, DEMO, DEMO\SOURCES, DISK1, GENERIC, and GENERIC\SOURCES. (If you selected 720K disks, a DISK2 directory was created as well). Delete the files in these directories and the directories themselves, if desired. Additional query words: 3.10 MSSetup tool kit ====================================================================== Keywords : kb16bitonly Technology : kbAudDeveloper kbWin3xSearch kbSDKSearch kbWinSDKSearch kbWinSDK310 Version : WINDOWS:3.1 ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 1999.