wix:patch

Full name:

com.github.wix-maven:wix-maven-plugin:0.4.0-SNAPSHOT:patch

Description:

Goal which executes WiX torch & pyro to create msp files.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: compile.
  • Binds by default to the lifecycle phase: package.

Required Parameters

Name Type Since Description
<baseArtifactItem> ArtifactItem - ArtifactItem to use as base. (ArtifactItem contains groupId, artifactId, version, type, classifier) See Usage for details.
<baseline> String - Baseline id... needs to match the baseline in the patch file, why then is it needed...I don't get how this works... Can we just read this from the input xml?
User property is: wix.baseline.
<harvestInputDirectory> File - Harvest input sources directory
Default value is: ${project.build.directory}/heat.
User property is: wix.harvestInputDirectory.
<intDirectory> File - Intermediate directory - will have ${arch} appended - may have ${locale} appended, when using compilePerLocale
Default value is: ${project.build.directory}/wixobj/Release.
User property is: wix.intDirectory.
<packaging> String - The output type:
  • msi - Windows installer
  • msm - Merge Module
  • wixlib - Wix library
  • msp - Windows patch
  • bundle - wix bootstrapper

Default value is: ${project.packaging}.
User property is: wix.packaging.
<patchedArtifactItem> ArtifactItem - ArtifactItem to use as patch. (ArtifactItem contains groupId, artifactId, version, type, classifier) See Usage for details.
<toolDirectory> File - Where to unpack the wix tools TODO: might need to do something about including tools version in path, or manage the unpacking more cleanly
Default value is: ${project.build.directory}/wix-tools.
User property is: wix.toolsPath.
<toolDirectoryOverwrite> boolean - When to unpack the wix tools. Default is to unpack the tools every time and overwrite, set to false to only overwrite if the tools are newer. This is provided to allow newer WIX test binaries to be dropped in, rather than having to install/deploy the wix-tools.
Default value is: true.
User property is: wix.toolDirectoryOverwrite.
<unpackDirectory> File - Unpack directory for dependent wix objects
Default value is: ${project.build.directory}/unpack.
User property is: wix.unpackDirectory.
<wxsGeneratedDirectory> File - Generated sources directory
Default value is: ${project.build.directory}/generated-sources/wixharvest.
User property is: wix.wxsGeneratedDirectory.
<wxsInputDirectory> File - The directory to scan for wix files. For each build type there is at least one wxs file required
Default value is: ${project.basedir}/src/main/wix.
User property is: wix.wxsInputDirectory.

Optional Parameters

Name Type Since Description
<bootstrapPluginArtifactId> String - Artifact id of the bootstrap archive to unpack.
Default value is: wix-bootstrap.
User property is: wix.bootstrapPluginArtifactId.
<bootstrapPluginClassifier> String - Classifier of the bootstrap archive to unpack.
User property is: wix.bootstrapPluginClassifier.
<bootstrapPluginGroupId> String - Group id of the bootstrap archive to unpack.
Default value is: org.wixtoolset.maven.
User property is: wix.bootstrapPluginGroupId.
<bootstrapPluginType> String - File Type of the bootstrap archive to unpack.
Default value is: jar.
User property is: wix.bootstrapPluginType.
<cabCacheDirectory> File - The cab cache directory (-cc) only added to light if reuseCab is enabled
- will have ${arch} appended
TODO: make this a formatted item so user can choose to add arch or not
Default value is: ${project.build.directory}/Release/cabs.
User property is: wix.cabCacheDirectory.
<compilePerLocale> boolean - Wix generates Id's during compilation, in some cases it is necessary to get unique id's for each locale. Useful for Patch MSP, may be useful for MSI. Ignored for Wixlib.
Default value is: false.
User property is: wix.compilePerLocale.
<externalCabs> String - The names of cabs that are not embedded Comma separated value.
ie. in wxs
<Media Id="1" Cabinet="Product1.cab" EmbedCab="no"/>
<Media Id="2" Cabinet="Product2.cab" EmbedCab="yes"/>
<Media Id="3" Cabinet="Product3.bar"/>
Could add
<externalCabs>Product1.cab,Product3.bar</externalCabs> TODO: this might need to be more like an include/exclude filter list
User property is: wix.externalCabs.
<finalName> String - Base Name of the generated wix objects.
Default value is: ${project.build.finalName}.
User property is: wix.finalName.
<localeList> Map - A locale is a language id + a culture specification each culture specification can contain a semicolon (;) separated list of cultures, this is an ordered list to fall back. ie. <localeList> <1033>en-US</1033> <1031<de-DE;en-US</1031> </localeList< Will add to light -cultures:culturespec
Will add to link each culture to the path as part of -b options - maybe should also add langid to path as -b option
Will use language id for re-packing mst bug: maven gives us a map of it's choice, rather than setting an item at a time, thus losing the prefered ordered set.
<locales> String - Similar to localeList, allow setting from properties as a single string value.
a csv of locale, where a locale is a langId:culturespec, and a culturespec is a semicolon seperate list of cultures. ie. 1033:en-US,1031:de-DE;en-US
Default value is: neutral.
User property is: wix.locales.
<mergeLevel> String - How to build the msi(s)
  • base - base culture msi only
  • default - each culture as full msi
  • trans - default + transforms & cabs for each additional culture
  • repack - trans + the additional culture (transform+cab) packed into 1 msi note: first culture listed is base

Default value is: default.
User property is: wix.merge.
<narUnpackDirectory> File - Target directory for Nar file unpacking.
Default value is: ${project.build.directory}/nar.
User property is: wix.narUnpackDirectory.
<outputDirectory> File - Output directory
  • in future may have 'configuration' appended (default to Release, but not appended yet)
  • will have ${arch} appended
  • may also have ${culture} appended

Default value is: ${project.build.directory}/Release.
User property is: wix.outputDirectory.
<packLevel> String - What of the steps should be packaged
  • default - step output (msi/msp/mst/repack)
  • wixpdb - the wixpdbs for all cultures
  • mst - the mst (ie. add to a mergeLevel repack build if used with default)
  • package - all the msi/msp (ie. add to a mergeLevel trans or repack build if used with default)
  • culture_cab - externalCabs for each arch/culture
  • cached_cab - externalCabs from the cabCacheDirectory(s) for each arch
  • trans_cab - cabs for each arch/culture generated by transform (msi with diff per culture) Comma separated value, default is "default,wixpdb,cached_cab"

Default value is: default,wixpdb,cached_cab.
User property is: wix.pack.
<patchProperties> Properties - Properties catch all in case we missed some configuration. Passed directly to pyro
<platforms> Set - The Platforms (Archictecture) for the msi.
Some choices are: x86, intel, x64, intel64, or ia64
If list is empty default-value="x86"
Will set: candle -dPlatform= -arch
<preserveUnmodified> boolean - Preserve unmodified content in the output.
Default value is: true.
User property is: nar.preserveUnmodified.
<relativeBase> File - A relative base path to shorten command line references to files in the project. Default is the project base directory, if alternate locations are given for wxs, wxl files it may be appropriate to change this.
Default value is: ${project.basedir}.
User property is: wix.relativeBase.
<reuseCabs> boolean - Re use cabinet files across multiple linkages. (-reusecab)
Default value is: false.
User property is: wix.reuseCab.
<skip> boolean - Skip running of all wix plugin goals altogether.
Default value is: false.
User property is: wix.skip.
<suppress> Set - Suppress [-s]
  • com suppress COM elements
  • frag suppress fragments
  • rd suppress harvesting the root directory as an element
  • reg suppress registry harvesting
  • uid suppress unique identifiers for files, components and directories
  • vb6 suppress VB6 COM elements
  • w<N> suppress all warnings or a specific message ID (example: w1011 w1012)
<toolsPluginArtifactId> String - Artifact id of the toolset jar to unpack.
Default value is: wix-toolset.
User property is: wix.toolsPluginArtifactId.
<toolsPluginClassifier> String - Classifier of the toolset jar to unpack.
User property is: wix.toolsPluginClassifier.
<toolsPluginGroupId> String - Group id of the toolset jar to unpack.
Default value is: org.wixtoolset.maven.
User property is: wix.toolsPluginGroupId.
<toolsPluginType> String - File Type of the toolset jar to unpack.
Default value is: jar.
User property is: wix.toolsPluginType.
<validate> String - Should validation be run, and when.
  • linking - Run validation during linking from light/lit.
  • unit - Run validation as unit test, suppressing validation during linking (light/lit).
  • both - Run validation during linking from light/lit and also as unit test.
  • suppress - Suppressing validation during linking (light/lit)

Default value is: unit.
User property is: wix.validate.
<verbose> boolean - Show additional info such as the wix toolset logo
Default value is: false.
User property is: wix.verbose.
<warn> Set - Treat specific warning messages as errors [-w]
  • x<N> suppress a specific message ID (example: x1011 x1012)
<wixExtensions> Set - v4-style NuGet extension names to pass as -ext <name> on the WiX v4+ unified CLI. Ignored when using WiX v3 (use Maven wixext dependencies instead). Example: 

<wixExtensions>
  <ext>WixToolset.UI.wixext</ext>
  <ext>WixToolset.Util.wixext</ext>
</wixExtensions>

Parameter Details

<baseArtifactItem>

ArtifactItem to use as base. (ArtifactItem contains groupId, artifactId, version, type, classifier) See Usage for details.
  • Type: com.github.wix_maven.ArtifactItem
  • Required: Yes

<baseline>

Baseline id... needs to match the baseline in the patch file, why then is it needed...I don't get how this works... Can we just read this from the input xml?
  • Type: java.lang.String
  • Required: Yes
  • User Property: wix.baseline

<bootstrapPluginArtifactId>

Artifact id of the bootstrap archive to unpack.
  • Type: java.lang.String
  • Required: No
  • User Property: wix.bootstrapPluginArtifactId
  • Default: wix-bootstrap

<bootstrapPluginClassifier>

Classifier of the bootstrap archive to unpack.
  • Type: java.lang.String
  • Required: No
  • User Property: wix.bootstrapPluginClassifier

<bootstrapPluginGroupId>

Group id of the bootstrap archive to unpack.
  • Type: java.lang.String
  • Required: No
  • User Property: wix.bootstrapPluginGroupId
  • Default: org.wixtoolset.maven

<bootstrapPluginType>

File Type of the bootstrap archive to unpack.
  • Type: java.lang.String
  • Required: No
  • User Property: wix.bootstrapPluginType
  • Default: jar

<cabCacheDirectory>

The cab cache directory (-cc) only added to light if reuseCab is enabled
- will have ${arch} appended
TODO: make this a formatted item so user can choose to add arch or not
  • Type: java.io.File
  • Required: No
  • User Property: wix.cabCacheDirectory
  • Default: ${project.build.directory}/Release/cabs

<compilePerLocale>

Wix generates Id's during compilation, in some cases it is necessary to get unique id's for each locale. Useful for Patch MSP, may be useful for MSI. Ignored for Wixlib.
  • Type: boolean
  • Required: No
  • User Property: wix.compilePerLocale
  • Default: false

<externalCabs>

The names of cabs that are not embedded Comma separated value.
ie. in wxs
<Media Id="1" Cabinet="Product1.cab" EmbedCab="no"/>
<Media Id="2" Cabinet="Product2.cab" EmbedCab="yes"/>
<Media Id="3" Cabinet="Product3.bar"/>
Could add
<externalCabs>Product1.cab,Product3.bar</externalCabs> TODO: this might need to be more like an include/exclude filter list
  • Type: java.lang.String
  • Required: No
  • User Property: wix.externalCabs

<finalName>

Base Name of the generated wix objects.
  • Type: java.lang.String
  • Required: No
  • User Property: wix.finalName
  • Default: ${project.build.finalName}

<harvestInputDirectory>

Harvest input sources directory
  • Type: java.io.File
  • Required: Yes
  • User Property: wix.harvestInputDirectory
  • Default: ${project.build.directory}/heat

<intDirectory>

Intermediate directory - will have ${arch} appended - may have ${locale} appended, when using compilePerLocale
  • Type: java.io.File
  • Required: Yes
  • User Property: wix.intDirectory
  • Default: ${project.build.directory}/wixobj/Release

<localeList>

A locale is a language id + a culture specification each culture specification can contain a semicolon (;) separated list of cultures, this is an ordered list to fall back. ie. <localeList> <1033>en-US</1033> <1031<de-DE;en-US</1031> </localeList< Will add to light -cultures:culturespec
Will add to link each culture to the path as part of -b options - maybe should also add langid to path as -b option
Will use language id for re-packing mst bug: maven gives us a map of it's choice, rather than setting an item at a time, thus losing the prefered ordered set.
  • Type: java.util.Map
  • Required: No

<locales>

Similar to localeList, allow setting from properties as a single string value.
a csv of locale, where a locale is a langId:culturespec, and a culturespec is a semicolon seperate list of cultures. ie. 1033:en-US,1031:de-DE;en-US
  • Type: java.lang.String
  • Required: No
  • User Property: wix.locales
  • Default: neutral

<mergeLevel>

How to build the msi(s)
  • base - base culture msi only
  • default - each culture as full msi
  • trans - default + transforms & cabs for each additional culture
  • repack - trans + the additional culture (transform+cab) packed into 1 msi note: first culture listed is base
  • Type: java.lang.String
  • Required: No
  • User Property: wix.merge
  • Default: default

<narUnpackDirectory>

Target directory for Nar file unpacking.
  • Type: java.io.File
  • Required: No
  • User Property: wix.narUnpackDirectory
  • Default: ${project.build.directory}/nar

<outputDirectory>

Output directory
  • in future may have 'configuration' appended (default to Release, but not appended yet)
  • will have ${arch} appended
  • may also have ${culture} appended
  • Type: java.io.File
  • Required: No
  • User Property: wix.outputDirectory
  • Default: ${project.build.directory}/Release

<packLevel>

What of the steps should be packaged
  • default - step output (msi/msp/mst/repack)
  • wixpdb - the wixpdbs for all cultures
  • mst - the mst (ie. add to a mergeLevel repack build if used with default)
  • package - all the msi/msp (ie. add to a mergeLevel trans or repack build if used with default)
  • culture_cab - externalCabs for each arch/culture
  • cached_cab - externalCabs from the cabCacheDirectory(s) for each arch
  • trans_cab - cabs for each arch/culture generated by transform (msi with diff per culture) Comma separated value, default is "default,wixpdb,cached_cab"
  • Type: java.lang.String
  • Required: No
  • User Property: wix.pack
  • Default: default,wixpdb,cached_cab

<packaging>

The output type:
  • msi - Windows installer
  • msm - Merge Module
  • wixlib - Wix library
  • msp - Windows patch
  • bundle - wix bootstrapper
  • Type: java.lang.String
  • Required: Yes
  • User Property: wix.packaging
  • Default: ${project.packaging}

<patchProperties>

Properties catch all in case we missed some configuration. Passed directly to pyro
  • Type: java.util.Properties
  • Required: No

<patchedArtifactItem>

ArtifactItem to use as patch. (ArtifactItem contains groupId, artifactId, version, type, classifier) See Usage for details.
  • Type: com.github.wix_maven.ArtifactItem
  • Required: Yes

<platforms>

The Platforms (Archictecture) for the msi.
Some choices are: x86, intel, x64, intel64, or ia64
If list is empty default-value="x86"
Will set: candle -dPlatform= -arch
  • Type: java.util.Set
  • Required: No

<preserveUnmodified>

Preserve unmodified content in the output.
  • Type: boolean
  • Required: No
  • User Property: nar.preserveUnmodified
  • Default: true

<relativeBase>

A relative base path to shorten command line references to files in the project. Default is the project base directory, if alternate locations are given for wxs, wxl files it may be appropriate to change this.
  • Type: java.io.File
  • Required: No
  • User Property: wix.relativeBase
  • Default: ${project.basedir}

<reuseCabs>

Re use cabinet files across multiple linkages. (-reusecab)
  • Type: boolean
  • Required: No
  • User Property: wix.reuseCab
  • Default: false

<skip>

Skip running of all wix plugin goals altogether.
  • Type: boolean
  • Required: No
  • User Property: wix.skip
  • Default: false

<suppress>

Suppress [-s]
  • com suppress COM elements
  • frag suppress fragments
  • rd suppress harvesting the root directory as an element
  • reg suppress registry harvesting
  • uid suppress unique identifiers for files, components and directories
  • vb6 suppress VB6 COM elements
  • w<N> suppress all warnings or a specific message ID (example: w1011 w1012)
  • Type: java.util.Set
  • Required: No

<toolDirectory>

Where to unpack the wix tools TODO: might need to do something about including tools version in path, or manage the unpacking more cleanly
  • Type: java.io.File
  • Required: Yes
  • User Property: wix.toolsPath
  • Default: ${project.build.directory}/wix-tools

<toolDirectoryOverwrite>

When to unpack the wix tools. Default is to unpack the tools every time and overwrite, set to false to only overwrite if the tools are newer. This is provided to allow newer WIX test binaries to be dropped in, rather than having to install/deploy the wix-tools.
  • Type: boolean
  • Required: Yes
  • User Property: wix.toolDirectoryOverwrite
  • Default: true

<toolsPluginArtifactId>

Artifact id of the toolset jar to unpack.
  • Type: java.lang.String
  • Required: No
  • User Property: wix.toolsPluginArtifactId
  • Default: wix-toolset

<toolsPluginClassifier>

Classifier of the toolset jar to unpack.
  • Type: java.lang.String
  • Required: No
  • User Property: wix.toolsPluginClassifier

<toolsPluginGroupId>

Group id of the toolset jar to unpack.
  • Type: java.lang.String
  • Required: No
  • User Property: wix.toolsPluginGroupId
  • Default: org.wixtoolset.maven

<toolsPluginType>

File Type of the toolset jar to unpack.
  • Type: java.lang.String
  • Required: No
  • User Property: wix.toolsPluginType
  • Default: jar

<unpackDirectory>

Unpack directory for dependent wix objects
  • Type: java.io.File
  • Required: Yes
  • User Property: wix.unpackDirectory
  • Default: ${project.build.directory}/unpack

<validate>

Should validation be run, and when.
  • linking - Run validation during linking from light/lit.
  • unit - Run validation as unit test, suppressing validation during linking (light/lit).
  • both - Run validation during linking from light/lit and also as unit test.
  • suppress - Suppressing validation during linking (light/lit)
  • Type: java.lang.String
  • Required: No
  • User Property: wix.validate
  • Default: unit

<verbose>

Show additional info such as the wix toolset logo
  • Type: boolean
  • Required: No
  • User Property: wix.verbose
  • Default: false

<warn>

Treat specific warning messages as errors [-w]
  • x<N> suppress a specific message ID (example: x1011 x1012)
  • Type: java.util.Set
  • Required: No

<wixExtensions>

v4-style NuGet extension names to pass as -ext <name> on the WiX v4+ unified CLI. Ignored when using WiX v3 (use Maven wixext dependencies instead). Example: 

<wixExtensions>
  <ext>WixToolset.UI.wixext</ext>
  <ext>WixToolset.Util.wixext</ext>
</wixExtensions>
  • Type: java.util.Set
  • Required: No

<wxsGeneratedDirectory>

Generated sources directory
  • Type: java.io.File
  • Required: Yes
  • User Property: wix.wxsGeneratedDirectory
  • Default: ${project.build.directory}/generated-sources/wixharvest

<wxsInputDirectory>

The directory to scan for wix files. For each build type there is at least one wxs file required
  • Type: java.io.File
  • Required: Yes
  • User Property: wix.wxsInputDirectory
  • Default: ${project.basedir}/src/main/wix