OSRLogo
OSRLogoOSRLogoOSRLogo x Subscribe to The NT Insider
OSRLogo
x

Everything Windows Driver Development

x
x
x
GoToHomePage xLoginx
 
 

    Fri, 20 Oct 2017     115100 members

   Login
   Join


 
 
Contents
  Online Dump Analyzer
OSR Dev Blog
The NT Insider
Downloads
ListServer / Forum
Driver Jobs
  Express Links
  · The NT Insider Digital Edition - May-June 2016 Now Available!
  · Windows 8.1 Update: VS Express Now Supported
  · HCK Client install on Windows N versions
  · There's a WDFSTRING?
  · When CAN You Call WdfIoQueueP...ously

Keep Version Resources Up-To-Date

As any savvy developer knows, the only way to keep track of what version of your software a customer is running is by adding a version resource to your image. This version resource, once created, is something that is understood and can by viewed with Explorer. Until now, keeping version resource information up to date required manual editing. This article introduces the reader to version resources and to OSR's, now publicly available, automatic Increment Versioning kit (IV). Of course, this kit is available as yet another free download at www.osronline.com.

Adding a Version Resource

A Version Resource is created by entering a VERSIONINFO resource definition statement into a resource script file, usually named with an ".RC" suffix. This ".RC" file is a text file that is specified in the "SOURCES=" line of your project "SOURCES" file and is compiled with the RC compiler. The resulting output then becomes part of your binary image.

A VERSIONINFO resource can contain the following information about your image:

  • CompanyName
  • FileDescription
  • FileVersion
  • InternalName
  • LegalCopyright
  • OriginalFilename
  • ProductName
  • ProductVersion
  • FileVersion
  • ProductVersion

This information can be viewed from Explorer by right-clicking on the image file, selecting the "Properties" menu item, and then selecting the "Version" tab. For example, by using a simple resource file and included config.h file, (see Figures 1 and 2 immediately below), we see the results shown in Figure 3 on (further below).

Figure 1 -- config.h

Figure 2 -- config.h

Figure 3

What many people do not realize is that this version resource information can be generated, maintained, and updated programmatically, and that is what OSR's IV kit does.

The IV Kit

IV is a kit that consists of 3 components: The IV program, which programmatically maintains the version information for your project and its component pieces; a set of template files that you use to integrate IV with your project; and an example project, named TestDrv, which uses IV. Let us discuss each component.

  • IV Program - The IV program is an image that is run each time your project is compiled. Its responsibility is to update the version information of your image if directed to via the IV command line, or if any project component has changed.
  • IV Templates - The IV templates consist of the following components to be integrated with the project to be built:
      • o a set of ".h" files

        o a "SOURCES" file template with include files

        o a MAKEFILE.INC template

        o an ".RC" template

  • TestDrv - TestDrv is an example project which utilizes the components of the IV kit. This should give developers a good start at adding IV to their projects.

Let us explore each of these in more detail.

IV Program

IV is a console mode program designed to update the version information for a component of a project based on information contained within the file "Version.h".

Its command line is shown below with parameter descriptions:

IV [-r] [-h] [-n] [-a] [-i] [-b buildType] [-f headerfile] [-v version] fileList

-r reports everything done by IV to stdout

-h prints out the help

-n no increment, just prints the current version to stdout

-a always modifies the version file, even if it is read-only. The default is not to modify a read-only version of "version.h".

-i always increments version

-b indicates what type of build is being done, where

"M" means VER_MAJOR++, VER_MINOR=0, VER_BASELEVEL=0, VER_PRODUCTBUILD=0

"I" means VER_MINOR++, VER_BASELEVEL=0, VER_PRODUCTBUILD=0

"A" means VER_BASELEVEL=1, VER_PRODUCTBUILD=0 or VER_PRODUCTBUILD++, if VER_BASELEVEL same since last build

"B" means VER_BASELEVEL=2, VER_PRODUCTBUILD=0 or VER_PRODUCTBUILD++, if VER_BASELEVEL same since last build

-f name of the version file to be updated. This usually is specified as ".\version.h"

-v sets VER_MAJOR to the indicated value

fileList a list of the files making up this component. Usually "$(SOURCES)" is specified.

IV Template Files

The IV Template files are files that you add to both your project and to all the components (exe,sys,dll) that make up your project. The template files allow you to define project-wide version information as well as component-specific version information.

Table 1 contains a list of the template files included with the kit and their purpose.

Template File Name

Purpose

Resource.rc

This is the Resource file template that is to be compiled as part of a project component that you are building, for example a program or a driver.?? This file pulls in Prjresource.h.

Prjresource.h

This file contains component specific version information.? This file pulls in globalresource.h and verrc.h, as well as the version.h file, which is maintained by the IV program.

GlobalResource.h

This file contains the global version information.? For a project consisting of multiple components, for example, executables, DLLs, and drivers, this file would contain Product version information that is common for all.

Makefile.inc

This file is a template makefile.inc that is added to project components which will contain version information.? This file runs the IV program, which maintains the version information for this component.

Sources

This file is a template sources file which shows how a project utilizes the IV kit.?? The user should note where the .RC file is specified and NTTARGETFILE0=version line, which results in the makefile.inc file being run prior to project compilation.?? This file references the ?Versionmake.def? file for common build definitions.

Verrc.h

This is a template include file that is added to project components which will contain version information.? This file must be updated by the developer since it contains component specific information such as file type and file subtype information.?? This file then includes Microsoft?s ?common.ver? which constructs the Version Resource for the project.

Versionmake.def, Versionmake-net.def, Versionmake-w2k.def,

Versionmake-wxp.def

Build definition files used in conjunction with a ?Sources? File to provide platform-specific definitions to the IV versioning program.?? These files are usually put at the root of your project and all components of your project will reference Versionmake.def.?? See the template ?Sources? file for details.

Table 1

TestDrv

The TestDrv component included in the kit demonstrates the use of the versioning technology discussed in this article. It should give the user ample information on how to add the IV components to any project.

How IV works

IV works by maintaining the file "VERSION.H" (see Figure 4), which it creates upon first being run as part of a component compilation.

Figure 4 -- version.h

The "VERSION.H" file contains the 5 lines which IV uses for maintaining versioning information. The lines are:

  • VER_MAJOR - contains the Major Version number of the component
  • VER_MINOR - contains the Minor Version number of the componentVER_BASELEVEL - 0 = Major, 1 = Minor, 2 = Alpha, 3 = Beta
  • VER_PRODUCTBUILD - contains the build generation number. This number would typically be updated if the modification time of a file in the project is later than the modified time of the "Version.h" file.
  • VER_PLATFORM - contains the name of the platform that this product was built on.

For each subsequent compilation, IV updates the information contained within this file if a project file has changed or if directed to by a command line option. IV is run as part of building a component which uses the template "makefile.inc" and "sources" files distributed with this kit. For example, consider the sources in Figure 5.

Figure 5 -- sources

IV is invoked when building a project because the "Sources" file contains the line "NTTARGETFILE0=version". This line causes "build" to run the "version" dependency rule contained in the "makefile.inc" file (see Figure 6) prior to compiling the component.

Figure 6 -- makefile.inc

In Figure 6 you will notice the "-b $(BUILDTYPE)" option. This indicates the type of build being done. The value of the "$(BUILDTYPE)" variable is set according to the setting of the PROJECT_BUILDTYPE environment variable that the developer can set prior to doing a project build (The default value is "A" for Alpha release, but the default can be changed in the file "versionmake.def"). IV understands 4 build types: Major, Intermediate (Minor), Beta, and Alpha (Default). The build type is determined by the value of the PROJECT_BUILDTYPE environment variable, defined in versionmake.def. The different settings of this variable result in a product version number prefixed by "V" (if "M" or "I" are specified), "B" (if "B" is specified), or "A" (if "A" is specified). The setting of this variable at the time of the build is reflected in the setting of the VER_BASELEVEL variable within "VERSION.H".

Summary

While IV may not be the optimal solution for your project, this article should give you the information you need to programmatically create and maintain your version resources and eliminate the need for manual editing of your version information.

Check the Downloads section of www.osronline.com to download this kit.

User Comments
Rate this article and give us feedback. Do you find anything missing? Share your opinion with the community!
Post Your Comment

Post Your Comments.
Print this article.
Email this article.

Writing WDF Drivers I: Core Concepts
LAB

Nashua (Amherst), NH
15-19 May 2017

Writing WDF Drivers II: Advanced Implementation Techniques
LAB

Nashua (Amherst), NH
23-26 May 2017

Kernel Debugging and Crash Analysis
LAB

Dulles (Sterling), VA
26-30 Jun 2017

Windows Internals and Software Driver Development
LAB

Nashua (Amherst), NH
24-28 Jul 2017

 
 
 
 
x
LetUsHelp
 

Need to develop a Windows file system solution?

We've got a kit for that.

Need Windows internals or kernel driver expertise?

Bring us your most challenging project - we can help!

System hangs/crashes?

We've got a special diagnostic team that's standing by.

Visit the OSR Corporate Web site for more information about how OSR can help!

 
bottom nav links