etc/verpatch.readme.txt

   1
   2 Verpatch - a tool to patch win32 version resources on .exe or .dll files,
   3
   4 Version: 1.0.15 (25-Oct-2016)
   5
   6 Verpatch is a command line tool for adding and editing the version information
   7 of Windows executable files (applications, DLLs, kernel drivers)
   8 without rebuilding the executable.
   9
  10 It can also add or replace Win32 (native) resources, and do some other
  11 modifications of executable files.
  12
  13 Verpatch sets ERRORLEVEL 0 on success, otherwise errorlevel is non-zero.
  14 Verpatch modifies files in place, so please make copies of precious files.
  15
  16
  17 Command line syntax
  18 ===================
  19
  20 verpatch filename [version] [/options]
  21
  22 Where
  23  - filename : any Windows PE file (exe, dll, sys, ocx...) that can have version resource
  24  - version : one to four decimal numbers, separated by dots, ex.: 1.2.3.4
  25    Additional text can follow the numbers; see examples below. Ex.: "1.2.3.4 extra text"
  26
  27 Common Options:
  28
  29 /va - creates a version resource. Use when the file has no version resource at all,
  30      or existing version resource should be replaced.
  31      If this option not specified, verpatch will read version resourse from the file.
  32 /s name "value" - add a version resource string attribute
  33      The name can be either a full attribute name or alias; see below.
  34 /sc "comment" - add or replace Comments string (shortcut for /s Comments "comment")
  35 /pv <version>   - specify Product version
  36     where <version> arg has same form as the file version (1.2.3.4 or "1.2.3.4 text")
  37 /high - when less than 4 version numbers, these are higher numbers.
  38       The string representation will have as many components as specified.
  39
  40 Other options:
  41
  42 /fn - preserves Original filename, Internal name in the existing version resource of the file.
  43 /langid <number> - language id for new version resource.
  44      Use with /va. Default is Language Neutral.
  45      <number> is combination of primary and sublanguage IDs. ENU is 1033 or 0x409.
  46 /vo - outputs the version info in RC format to stdout.
  47      This can be used with /xi to dump a version resource without modification.
  48      Output of /vo can be pasted to a .rc file and compiled with rc.
  49 /xi- test mode. does all operations in memory but does not modify the file
  50 /xlb - test mode. Re-parses the version resource after modification.
  51 /rpdb - removes path to the .pdb file in debug information; leaves only file name.
  52 /rf #id file - add or replace a raw binary resource from file (see below)
  53 /noed - do not check for extra data appended to exe file
  54 /vft2 num - specify driver subtype (VFT2_xxx value, see winver.h)
  55      The application type (VFT_xxx) is retained from the existing version resource of the file,
  56      or filled automatically, based on the filename extension (.exe->app, .sys->driver, anything else->dll)
  57
  58
  59 Examples
  60 ========
  61
  62 verpatch d:\foo.dll 1.2.33.44
  63     - Sets the file version to 1.2.33.44
  64       The Original file name and Internal name strings are set to "foo.dll".
  65       File foo.dll should already have a version resource (since /va not specified)
  66
  67 verpatch d:\foo.dll 1.2.33 /high
  68     - Sets three higher 3 numbers of the file version.
  69           The 4th number is not changed in the binary version struct,
  70           and the version as string will have three components.
  71       File foo.dll should already have a version resource.
  72
  73 verpatch d:\foo.dll 33.44  /s comment "a comment"
  74     - Replaces only two last numbers of the file version and adds a comment.
  75         File foo.dll should already have a version resource.
  76
  77 verpatch d:\foo.dll "33.44 special release" /pv 1.2.3.4
  78     - same as previous, with additional text in the version argument.
  79         - Product version is also specified
  80
  81 verpatch d:\foo.dll "1.2.33.44" /va /s description "foo.dll"
  82      /s company "My Company" /s copyright "(c) 2009"
  83    - creates or replaces version resource to foo.dll, with several string values.
  84      ( all options should be one line)
  85
  86 verpatch d:\foo.dll /vo /xi
  87     - dumps the version resource in RC format, does not update the file.
  88
  89 Misc. functions
  90 ================
  91
  92 * Add resource from a file
  93
  94 The /rf switch adds a resource from a file, or replaces a resource with same type and id.
  95
  96 The argument "#id" is a 32-bit hex number, prefixed with #.
  97 Low 16 bits of this value are resource id; can not be 0.
  98 Next 8 bits are resource type: one of RT_xxx symbols in winuser.h, or user defined.
  99 If the type value is 0, RT_RCDATA (10) is assumed.
 100 High 8 bits of the #id arg are reserved0.
 101 The language code of resources added by this switch is 0 (Neutral).
 102 Named resource types and ids are not implemented.
 103 The file is added as opaque binary chunk; the resource size is rounded up to 4 bytes
 104 and padded with zero bytes.
 105
 106 * Handling appended data
 107
 108 The program detects extra data appended to executable files, saves it and appends
 109 again after modifying resources.
 110 Command switch /noed disables checking for extra data.
 111
 112 Such extra data is used by some installers, self-extracting archives and other applications.
 113 However, the way we restore the data may be not compatible with these applications.
 114 Please, verify that executable files that contain extra data work correctly after modification.
 115 Make backup of valuable files before modification.
 116
 117 * Remove the path from debug info (.PDB) string
 118
 119 Use switch /rpdb to remove the path to the .pdb file in debug information; leave only file name.
 120
 121 Remarks
 122 =======
 123
 124 In "patch" mode (no /va option), verpatch replaces the version number in existing file
 125 version info resource with the values given on the command line.
 126 The version resource in the file  is parsed, then parameters specified on the command line are applied.
 127
 128 If the file has no version resource, or you want to discard the existing resource, use /va switch.
 129
 130 Quotes surrounding arguments are needed for the command shell (cmd.exe),
 131 for any argument that contains spaces.
 132 Also, other characters should be escaped (ex. &, |, and ^ for cmd.exe).
 133 Null values can be specified as empty string ("").
 134
 135 The command line can become very long, so you may want to use a batch file or script.
 136 See the example batch files.
 137
 138 Verpatch can be run on same PE file any number of times.
 139
 140 The Version argument can be specified as 1 to 4 dot separated decimal numbers.
 141 Additional suffix can follow the version numbers, separated by a dash (-) or space.
 142 If the separator is space, the whole version argument must be enclosed in quotes.
 143
 144 If the switch /high not specified and less than 4 numbers are given,
 145 they are considered as minor numbers.
 146 The higher version parts are retained from existing version resource.
 147 For example, if the existing version info block has version number 1.2.3.4
 148 and 55.66 specified on the command line, the result will be 1.2.55.66.
 149
 150 If the switch /high is specified and less than 4 numbers are given,
 151 they are considered as higher numbers.
 152 For example, if the existing version info has version number 1.2.3.4
 153 and 55.66 /high specified on the command line, the result will be 55.66.3.4.
 154
 155 The /high switch has been added to support the "Semantic Versioning" syntax
 156 as described here: http://semver.org
 157 The "Semantic versioning", however, specifies only 3 parts for the version number,
 158 while Windows version numbers have 4 parts.
 159 Switch /high allows 3-part version numbers with optional "tail" separated by '-' or '+'
 160 but the text representation will not be displayed by Windows Explorer in Vista or newer.
 161 The file version displayed will always have 4 parts.
 162
 163
 164 Verpatch ensures that the version numbers in the binary part
 165 of the version structure and in the string part (as text) are same,
 166 or the text string begins with the same numbers as in the binary part.
 167
 168 By default, Original File Name and Internal File Name are replaced to the actual filename.
 169 Use /fn to preserve existing values in the version resource.
 170
 171 String attribute names for option /s must be language-neutral,
 172 not translations (example: PrivateBuild, not "Private Build Description").
 173 See below for the list of known attrbute names and their aliases.
 174 The examples above use the aliases.
 175
 176 String arguments for File version and Product version parameters are handled
 177  in a special way, the /s switch should not be used to set these:
 178  - The File version can be specified as the 2nd positional argument only
 179  - The Product version can be specified using /pv switch
 180
 181
 182 ====================================================================
 183 Known string keys in VS_VERSION_INFO resource
 184 ====================================================================
 185
 186 The aliases in the right column can be used with /s switch,
 187 in place of language-neutral (LN) attribute names.
 188 Attribute names are not case sensitive.
 189
 190 -------------------+----+-------------------------------+------------
 191  Lang.Neutral name |note| English translation           | Aliases
 192 -------------------+----+-------------------------------+------------
 193 Comments                    Comments                      comment
 194 CompanyName                 Company                       company
 195 FileDescription       E     Description                   description, desc
 196 FileVersion           *1    File Version
 197 InternalName                Internal Name                 title
 198                       *2    Language
 199 LegalCopyright        E     Copyright                     copyright, (c)
 200 LegalTrademarks       E     Legal Trademarks              tm, (tm)
 201 OriginalFilename            Original File Name
 202 ProductName                 Product Name                  product
 203 ProductVersion        *3    Product Version               productversion (*)
 204 PrivateBuild                Private Build Description     pb, private
 205 SpecialBuild                Special Build  Description    sb, build
 206 OleSelfRegister       A     -
 207 AssemblyVersion       N
 208
 209 Notes
 210 *1: FileVersion, ProductVersion should not be specified with /s switch.
 211 See the command line parameters above.
 212 The string values normally begin with same 1.2.3.4 version number as in the binary header,
 213 but can be any text. Explorer of WinXP also displays File Version text in the strings box.
 214 In Win7 or newer, Explorer displays the version numbers from the binary header only.
 215
 216 *2: The "Language" value is the name of the language code specified in the header of the
 217  string block of VS_VERSION_INFO resource (or taken from VarFileInfo block?)
 218 It is displayed by Windows XP Explorer.
 219
 220 *3 When Productversion is specified as a string attribute (/s productversion)
 221    rather than with /pv, the argument string will be put literally.
 222    This can be used to specify leading zeros in version numbers.
 223
 224 E: Displayed by Windows Explorer in Vista+
 225 A: Intended for some API (OleSelfRegister is used in COM object registration)
 226 N: Added by some .NET compilers. This version number is not contained in the
 227    binary part of the version struct and can differ from the file version.
 228    To change it, use switch /s AssemblyVersion [value]. Note: this will not
 229    change the actual .NET assembly version.
 230 ====================================================================
 231
 232
 233
 234 Known issues and TO DO's:
 235 =========================
 236
 237  - Does not work on old PE files that have link version 5.x (before VC6?)
 238    No known workaround; this seems to be limitation of Windows UpdateResource API.
 239    Since the UpdateResource API is part of Windows, its behaviour may differ on
 240    different Windows releases. On Win7 SP1 you may get better results than on WinXP.
 241
 242  - Import of version resource does not work if it is not encoded in UTF-16.
 243
 244  - Does not work on files signed with digital certificates (TO DO: warn and remove certificate)
 245    Until we do this, certificates can be removed with 3rd party delcert tool.
 246
 247  -  A second version resource may be added to a file that already has a version resource
 248    in other language. Switch /va won't help.
 249    TO DO: ensure that a file has only one version resource!
 250
 251  - When verpatch is invoked from command prompt, or batch file, the string
 252    arguments can contain only ANSI characters, because cmd.exe batch files cannot be
 253    in Unicode format. If you need to include characters not in current locale,
 254    use other shell languages that fully support Unicode (Powershell, vbs, js).
 255
 256  - TO DO: In RC source output (/vo), special characters in strings are not quoted;
 257    so /vo may produce invalid RC input.
 258
 259  - The parser of binary version resources handles only the most common type of structure.
 260    If the parser breaks because of unhandled structure format, try /va switch to
 261    skip reading existing version resource and re-create it from scratch.
 262    Consider using WINE or other open source implementations?
 263
 264  - option to add extra 0 after version strings : "string\0"
 265    (tentative, requested by a reader for some old VB code)
 266
 267  - For files with extra data appended, checksum is not re-calculated.
 268    Such files usually implement their own integrity check.
 269
 270  - Switch /va does not prevent import of existing version resource. Revise.
 271
 272  - When existing version string contains "tail" but the command line parameter does not,
 273    the tail is removed. In previous versions the tail was preserved.
 274
 275  - Running verpatch on certain executables (esp. built with GNU) produce corrupt file
 276    when run on WinXP SP3, but same binaries give good result when run on Win7 or 2008R2.
 277    (Improvement of UpdateResource API?)
 278
 279
 280 Source code
 281 ============
 282 The source is provided as a Visual C++ 2013 project, it can be compiled with VC 2008, 2010, 2012 Express and newer.
 283 (The VC 2008 compatible project is in verpatch(vs2008).sln, verpatch.vcproj files. verpatch.sln, .vcxproj are for VC++ 2013).
 284 It demonstrates use of the UpdateResource and imagehlp.dll API.
 285 It does not demonstrate good use of C++, coding style or anything else.
 286 Dependencies on VC features available only in paid versions (before Community editions) have been removed.
 287
 288 UAC note: Verpatch does not require any administrator rights and may not work correctly if run elevated.
 289
 290 ~~