INFO: How Setup Wizard and PDW Use Dependency Files
Symptoms
A dependency (.DEP) file contains information about the run-timerequirements of an application or component; it contains informationregarding which files are needed, how the files are to be registered, andwhere they should be installed on the target computer. You can createdependency files for standard Visual Basic projects, ActiveX controls,ActiveX documents, and other ActiveX components.
When a component is used in another project, the dependency information forthe component is incorporated into the project’s dependency information.This dependency information is used by the Setup Wizard (known as thePackage and Deployment Wizard or PDW in Visual Basic 6.0). When you use theSetup Wizard or PDW to generate a setup for your project, the wizard refersto the project’s dependency information to determine which files should bedistributed with your project and how those files should be installed.
All of the ActiveX controls that ship with Visual Basic have a companiondependency file. It is strongly recommended that you generate a dependencyfile for your component, especially if you intend that the component beused in other Visual Basic projects. The Setup Wizard and PDW give you theoption to generate a dependency file for your project or component. Thedependency file may also be generated using a text editor if you cannot usethe Setup Wizard or PDW to create one. The remainder of this articledescribes the syntax for a dependency file.
Resolution
A dependency file is a standard Windows .INI file and can be read andwritten to using the standard Windows APIs (GetPrivateProfileString andWritePrivateProfileString).
There are a few items to note for dependency files:
Dependency files may have multiple sections. The section orderis not significant.Entries are not case-sensitive.Comments are allowed when preceded by a semi-colon (;).The dependency file name is important. The file name prefixmust match the file name of the component it describes. Forexample, a dependency file MyOCX.DEP would correspond to acomponent, such as MyOCX.OCX or MyOCX.DLL.Each section in a .DEP file uses the following syntax:
[Component File Name]Dest=<Destination>UsesN=<Dependent File>Register=<Method of Registration>Version=<Component version>Date=<Component Date>Time=<Component Time>ProgramIconTitle=<Title for Shortcut>ProgramIconCmdLine=<Command Line for Shortcut>
Dest=The Dest= key indicates the destination folder for the component. Thisvalue may be a relative path, a full path, or a path based on any of thefollowing macros (for example, it may be simply a macro, or it may be amacro followed by a backslash and a relative path):
$(AppPath)Indicates the path the user selectsduring setup. $(WinSysPath)Indicates the \Windows\System or\Winnt\System32 folder. $(WinPath)Indicates the \Windows or \Winnt folder. $(ProgramFiles)Indicates the folder specified atHKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\ProgramFilesDir. $(CommonFiles)Indicates the folder specified atHKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\CommonFilesDir. $(CommonFilesSys)Indicates $(CommonFiles)\System inWindows 95, Windows 98, NT 4.0, and Windows 2000,or the same as $(WinSysPath) in NT 3.51. $(MSDAOPath)The location stored in the registryfor DAO components. The Dest= key applies only to the component to which the section applies.By default, all files dependent on the component will also be placed in thesame location. To override the location for a “child,” you can create asection for the “child” and specify a different destination in thatsection.
UsesN=The UsesN= key (where N is an integer) indicates a dependent file for thecomponent. A file specified by a UsesN= key is required for the componentdefined by that section. In a section, N must be sequential and must startwith 1. For an illustration, refer to the following sample section:
[MyOCX.OCX]Dest=$(WinSysPath)Uses1=MyDLL.DLLUses2=MyOCX.TXT In this example, MyOCX.OCX depends upon (or requires) MyDLL.DLL andMyOCX.TXT.
NOTE: If the UsesN keys are not ordered sequentially, or if a number isskipped, dependent files may not be recognized in the section and may notbe acknowledged by the Setup Wizard or PDW.
Register=The Register= key indicates whether the file should be registered and, ifso, how it should be registered. The valid values for this key are:
NoneIf a value is omitted for this key,the file is not registered.$(DllSelfRegister)The file supports self-registrationand self-unregistration via a DLLentry point.$(ExeSelfRegister)The file is a local server thatsupports self-registration throughthe command-line parameter”/RegServer” and self-unregistrationthrough the command-line parameter”/UnRegServer.”$(TLBRegister)The file is a .TLB file and should beregistered.FilenameThe file is registered by callingRegedit.exe with this filename as aCommand-line parameter.$(Remote)Used only by Visual Basic to indicatethat the file is a .VBR file. If the Register= key is omitted altogether, the file is not registered.
Version=(Optional)
The Version= key indicates the version of the component that is needed. TheSetup Wizard and PDW can detect that a .dep file is out-of-date using theVersion= key. The version is specified in the format a.b.c.d, as in thefollowing example:
Version=4.50.10.11
Date=(Optional)
The Date= key is the date stamp of the component that is needed. The SetupWizard and PDW can detect that a .DEP file is out-of-date using this key.This value must always be in the format d/m/yyyy or dd/mm/yyyy, even whenusing a localized Setup Wizard or PDW. For example:
Date=10/5/1996 -or-
Date=04/03/1997 NOTE: This key is ignored if a value is specified for the Version= key.
Time=(Optional)
The Time= key is the time stamp of the component that is needed. The SetupWizard and PDW can detect that a .DEP file is out-of-date using this key.This value must always be in the 24-hour format hh:mm:ss, even when using alocalized Setup Wizard or PDW. For example:
Time=14:05:32 NOTE: This key is ignored if a value is specified for the Version= key.
ProgramIconTitle= and ProgramIconCmdLine=(Optional)
The ProgramIconTitle= key indicates that a shortcut (or Program Managericon for Windows NT 3.51) should be created if the file is installed. Thevalue for the ProgramIconTitle= key is the title given to the shortcut (oricon). The value may be quoted or unquoted. For example:
ProgramIconTitle=My Program Title If you indicate that a shortcut should be created, you can give the commandline for the shortcut by specifying a value for the ProgramIconCmdLine=key. The path that you use for the command-line value may contain themacros listed for the Dest= key. For example:
ProgramIconCmdLine=$(AppPath)\Readme.txt
Localized ComponentsSome components may have different dependencies based on the language. Toinstall a component based on the language setting for the client’scomputer, you may specify a section with the component name followed by thelanguage ID.
For example, VBRUN500.DLL has a satellite DLL for all languages (with theexception of English):
[VBRUN500.DLL]Dest=$(WinSysPath)[VBRUN500.DLL <000C>];000C = primary language ID for FrenchUses1=VB5FR.DLL[VBRUN500.DLL <0007>];0007 = primary language ID for GermanUses1=VB5DE.DLL In this example, if VBRUN500.DLL is installed and the client’s languagesettings are French, VB5FR.DLL will also be installed. Likewise, ifVBRUN500.DLL is installed and the client’s language settings are German,VB5DE.DLL will be installed.
Sample Dependency FileThe following is a sample .DEP file for a component named MyOCX.OCX. Thisdependency file would be named MyOCX.DEP:
[MyOCX.OCX]Register=$(DLLSelfRegister)Dest=$(WinSysPath)Date=1/23/1996Time=10:15:33Version=1.1.13.6Uses1=MyDLL.DLLUses2=MyServer.EXEUses3=VBRUN500.DLL[MyServer.EXE]Dest=$(WinPath)Date=1/23/1996Time=18:52:48Version=1.0.1.0Uses1=VBRUN500.DLLRegister=$(ExeSelfRegister)ProgramIconTitle=My ProgramProgramIconCmdLine=$(WinSysPath)\MyOCX.OCX[MyDLL.DLL]Register=$(DLLSelfRegister)Version=1.0.1.0[VBRUN500.DLL]Dest=$(WinSysPath);Additional Files for International Support[VBRUN500.DLL <0007>]Uses1=VB5DE.DLL[VBRUN500.DLL <000C>]Uses1=VB5FR.DLL MyOCX.OCX is a self-registering file that is installed in theWindows\System folder (or Winnt\System32 folder on NT or Windows 2000). MyOCX.OCX depends upon (requires) three files: MyDLL.DLL, MyServer.EXE, and VBRUN500.DLL.
MyServer.EXE is a self-registering file that is installed in the Windowsfolder (or Winnt folder on NT or Windows 2000). MyServer.EXE has only one dependent file, VBRUN500.DLL. If MyServer.EXE is installed during setup, a shortcut is created with the title “My Program” and the command lineWindows\System\MyOCX.OCX (or Winnt\System32\MyOCX.OCX on NT or Windows 2000).
MyDLL.DLL is also a self-registering file. A destination for MyDLL.DLL isnot specified; thus, it will be placed in the destination path for itsparent, MyOCX.OCX.
VBRUN500.DLL will not be registered because a Register= key is notspecified in its section. VBRUN500.DLL will be placed in the Windows\System(or Winnt\System32) folder. If VBRUN500.DLL is installed during setup,VB5DE.DLL will be installed if the language setting is German and VB5FR.DLLwill be installed if the language setting is French. If the languagesetting is set to something other than French or German, no additionalfiles will be installed.
How Setup Wizard and PDW Search for Dependency InformationWhen the Setup Wizard and PDW need to find dependency information for afile (for example, MyOCX.OCX), they follow a specific path. The wizards usethe following methods to locate a section entitled [MyOCX.OCX]; when thesection is found, the search ends.
If the file has been located in a .DEP file, it will use theinformation in the .DEP file in which it was first found.The Setup Wizard will look in the default master dependencyfile for Visual Basic 5.0 (VB5DEP.INI). The PDW will look in thedefault master dependency file for Visual Basic 6.0 (VB6DEP.INI).Information that is placed in the default master dependency fileoverrides that which might be found elsewhere.The Setup Wizard and PDW will look for a dependency file namedMyOCX.DEP. If the dependency file is found, the wizard will searchfor the section entitled [MyOCX.OCX].It will search for a .DEP file associated with the parent ofMyOCX.OCX and possibly continue up the parent chain until asection entitled [MyOCX.OCX] is located.
