Basics of Driver Installers

This topic presents an overview of how Nimbus driver installers are created, managed, and customized. Other topics under the topic Creating a Driver Installer present detailed information on specific installer issues.

The Driver Setup Project and WiX

If you have Nimbus create a driver setup project as part of creating a new driver solution, the setup project will be named as follows:

<projectName>Setup

Driver setup projects added to a solution after the fact can be named arbitrarily.

This driver setup project produces an MSI installer package (.msi) when it is built. It does this by use of an installer tool called WiX (Windows Installer XML) . WiX is a toolset that builds Windows installation packages from XML source code. WiX is in wide use today, particularly within Microsoft where it is used to produce the installers for such large-scale projects as Microsoft Office, Visual Studio, and SQL Server. This technology is particularly amenable to driver installers because it exposes the full power of Windows Installer technology and because its XML source format allows for both manual modifications and automated code-generation and roundtripping, such as that performed by Nimbus.

For links to helpful WiX resources, see the topic Learning More About WiX. When working with WiX directly, keep in mind that there are several versions of WiX available. Nimbus currently uses WiX version 3.9.

Nimbus automatically installs WiX in the NimbusInstallDir\Tools\Wix3 folder, so a separate download and installation is not necessary. The WiX command-line programs installed by Nimbus are invoked automatically by the driver setup project. These programs process the XML source files in the driver setup project. The table below lists each file in a driver setup project.

Caution
All of the files listed below appear in the driver setup project, and are therefore easily accessed from within the Visual Studio Solution Explorer. You will typically not need to edit these files directly using Visual Studio's XML editor, although that capability exists for advanced scenarios where manual customization is desired.

File

Description

Setup.wxs

The main WiX source file. This file contains the product declarations, files and components, and features comprising the driver installer. Double click this file in the Solution Explorer to launch the Nimbus Driver Setup Designer. To view and edit the WiX XML in this file, right click on this file in the Solution Explorer and select View Code.

Caution
Using the Visual Studio XML editor to modify the WiX source for this file is an advanced operation. Refer to the documentation on manual customization for more information.

DriverEULA.rtf

End-user license agreement that appears in one of the setup dialog pages. It also gets installed with the driver.

This file should be customized by the developer to meet the appropriate corporate legal standards.

Readme.txt

Readme file installed with the driver.

Important
Nimbus generates only a template Readme.txt file with fields for the required IVI compliance information. This information needs to be manually populated by the driver developer before shipping the driver. Once complete, this file can be used to perform the required registration of the driver on the IVI Foundation web site.

Images\*.*

Series of graphics files (.bmp, .ico) used in various places by the installer.

Important
These files may be replaced for custom branding or other purposes, but it is critical they be replaced with files that have precisely the same image size.

Internal\*.*

Standard file and folder definitions used by driver installers.

Caution
Although these files may be modified using Visual Studio's XML file editor, doing so is an advanced operation. Refer to the documentation on manual customization for more information.

Policy Files\*.xml (IVI.NET and IVI-COM only)

Policy files for implementing backwards compatibility with previous versions of the driver. Nimbus automatically adds one of these for each compatible version listed in the General Property Page. Building the setup project creates policy file DLLs from these XML files. The resulting policy file DLLs are automatically integrated into the driver installer.

Default Behavior of the Driver Installer

Nimbus automatically generates a fully IVI-compliant and fully functional IVI driver installer. In many cases, the driver installer project can simply be built and the resulting .msi package used as is. By default, the driver installer does all of the following:

Checks for the presence of the minimum version of the IVI Shared Components, as specified in the General Page of the Driver Setup Project Properties, and aborts if not found.
For IVI.NET drivers, the installer checks for the presence of the minimum version of the IVI.NET Shared Components, as specified in the General Page of the Driver Setup Project Properties, and aborts if not found.
For IVI-COM and IVI-C drivers, the installer checks for the presence of another version of the same driver and alerts the user if one is found.
For IVI.NET drivers, the installer deploys the driver side-by-side with any other version of the same IVI.NET driver on the system. The policy files deployed with the driver ensure that applications built against earlier versions of the IVI.NET driver will load the latest version when they execute. This side-by-side deployment is the approach recommended by the IVI Foundation and the same approach employed by the IVI Shared Component installer.
Installs files as listed in the sections below, based on driver type.
Creates a Start Menu item named "<company>\<driverName>" and adds links to the following items:
- Driver help file, if available (<driverName>.chm).
- Readme file.
Updates the IVI Configuration Store with the information specified in the driver's IVI Config Store XML file (<driverName>.xml).
Merges the driver help with the Visual Studio help, if the Visual Studio help is installed.

IVI.NET Driver Files Installed

The table below lists the files that are installed as part of the IVI.NET driver:

File	Install Location	Description
<driverName>.<frameworkShortVersion>.dll e.g.: Acme.Acme4321.Fx20.dll	<IviInstallDir>\Microsoft.NET\Framework32\<frameworkVersion>\<driverName> <driverThreeDigitVersion> e.g.: C:\Program Files (x86)\IVI Foundation\IVI\Microsoft.NET\Framework32\v2.0.50727\Acme.Acme4321 0.1 AND Global Assembly Cache (GAC)	IVI.NET driver assembly.
<driverName>.<frameworkShortVersion>.xml e.g.: Acme.Acme4321.Fx20.xml	<IviInstallDir>\Microsoft.NET\Framework32\<frameworkVersion>\<driverName> <driverThreeDigitVersion>	Visual Studio IntelliSense file (only if you XML documentation is enabled on the driver assembly project's property page).
Policy.X.X.<driverName>.dll	Global Assembly Cache (GAC)	Policy file for .NET versioning. There will be one of these for each compatible version listed in the General Page of the Driver Setup Project Properties.
Source\.	<IviInstallDir>\Microsoft.NET\Framework32\<frameworkVersion>\<driverName> <driverThreeDigitVersion>\Source	Driver sources files. End users will have the option of installing driver source when they run the driver installer.
<driverName>.chm	<IviInstallDir>\Microsoft.NET\Framework32\<frameworkVersion>\<driverName> <driverThreeDigitVersion>\Help	HTML 1.0 driver help file and index (if HTML 1.0 help has been enabled on the General Page of the Driver Setup Project Properties).
<driverName>.HxS <driverName>Collection. h2reg.ini	<IviInstallDir>\Microsoft.NET\Framework32\<frameworkVersion>\<driverName> <driverThreeDigitVersion>\Help
<driverName>.msha <driverName>.mshc or <driverName>.cab	<IviInstallDir>\Microsoft.NET\Framework32\<frameworkVersion>\<driverName> <driverThreeDigitVersion>\Help	Microsoft Help Viewer driver help file for use with Visual Studio. (if Microsoft Help Viewer help has been enabled on the General Page of the Driver Setup Project Properties). The actual name of this file depends on whether or the help is signed with a certificate. Signed help files will have an extension of .mshc, while signed help files will have an extension of .cab. Refer to Signing Microsoft Help Viewer Content for instructions on how to sign help files. Regardless of whether or not the driver help file is signed, it is integrated into the Microsoft Help Viewer local content database by the driver installer.

IVI-COM Driver Files Installed

The table below lists the files that are installed as part of the IVI-COM driver:

File	Install Location	Description
<driverName>.dll	<IviInstallDir>\Bin	IVI-COM driver DLL. If an IVI-C wrapper is included with the driver, then this DLL is NOT named <driverName>.dll. Rather, the driver is named according to the IVI-C prefix -- <prefix>.dll.
<assemblyPrefix>.<driverName>.Interop.dll	<IviInstallDir>\Bin\Primary Interop Assemblies AND Global Assembly Cache (GAC)	.NET interop assembly. The <assemblyPrefix> can be set from the .NET Page of the Driver Settings Editor.
<assemblyPrefix>.<driverName>.Interop.xml	<IviInstallDir>\Bin\Primary Interop Assemblies	XML IntelliSense file for using the driver in .NET environments.
Policy.X.X.<assemblyPrefix>.<driverName>.Interop.dll	Global Assembly Cache (GAC)	Policy file for .NET versioning. There will be one of these for compatible version listed in the General Page of the Project Properties.
Source\.	<IviInstallDir>\Drivers\<driverName>\Source	Driver sources files. If an IVI-C wrapper is included with the driver, then the install location will use the IVI-C prefix in the install path instead of <driverName>.
<driverName>.chm	<IviInstallDir>\Drivers\<driverName>	HTML 1.0 driver help file and index. If an IVI-C wrapper is included with the driver, then the install location will use the IVI-C prefix in the install path instead of <driverName>.
<driverName>.HxS <driverName>Collection. h2reg.ini, h2reg.exe	<IviInstallDir>\Drivers\<driverName>
<driverName>.msha <driverName>.mshc or <driverName>.cab	<IviInstallDir>\Drivers\<prefix>	Microsoft Help Viewer driver help file for use with Visual Studio. (if Microsoft Help Viewer help has been enabled on the General Page of the Driver Setup Project Properties). The actual name of this file depends on whether or the help is signed with a certificate. Signed help files will have an extension of .mshc, while signed help files will have an extension of .cab. Refer to for instructions on how to sign help files. Regardless of whether or not the driver help file is signed, it is integrated into the Microsoft Help Viewer local content database by the driver installer.

If a MATLAB^® wrapper has been included with the driver via the MATLAB Page of the Driver Settings Editor, then Nimbus automatically integrates additional files with the driver installer. The root folder for the installed MATLAB files is:

<IviInstallDir>\\Components\MATLAB\+instrument\+driver

IVI-C Driver Files Installed

The IVI-C driver files installed are the same for standalone IVI-C drivers and for IVI-C wrappers built on top of an IVI-COM driver.

File	Install Location	Description
<prefix>.h	<IviInstallDir>\Include	IVI-C header file containing IVI-C function and attribute definitions.
<prefix>.lib	<IviInstallDir>\Lib\Msc	IVI-C import library.
<prefix>.fp	<IviInstallDir>\Drivers\<prefix>	Function panel file containing hierarchy of IVI-C functions.
<prefix>.sub	<IviInstallDir>\Drivers\<prefix>	Attribute information file containing hierarchy of IVI-C attributes.
Source\.	<IviInstallDir>\Drivers\<prefix>\Source	Driver sources files.
<prefix>.chm	<IviInstallDir>\Drivers\<prefix>	HTML 1.0 driver help file and index.
<prefix>.HxS <prefix>Collection. h2reg.ini, h2reg.exe	<IviInstallDir>\Drivers\<prefix>
<driverName>.msha <prefix>.mshc or <prefix>.cab	<IviInstallDir>\Drivers\<prefix>	Microsoft Help Viewer driver help file for use with Visual Studio. (if Microsoft Help Viewer help has been enabled on the General Page of the Driver Setup Project Properties). The actual name of this file depends on whether or the help is signed with a certificate. Signed help files will have an extension of .mshc, while signed help files will have an extension of .cab. Refer to for instructions on how to sign help files. Regardless of whether or not the driver help file is signed, it is integrated into the Microsoft Help Viewer local content database by the driver installer.

Other Resources

Manually Customizing The Driver Installer

Signing Microsoft Help Viewer Content