wix:candle

Full name:

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

Description:

Goal which executes WiX candle to create a .wixobj file. The following project dependency inclusion patterns apply
Dependent NAR project 'Foo' with possible nar output redefined as 'bar'
  • -dFoo.TargetDir=Foo-version\
  • -dFoo.TargetExt=.wixlib
  • -dFoo.TargetFileName=bar.type
  • -dFoo.TargetName=bar

Attributes:

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

Required Parameters

Name Type Since Description
<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.
<staleMillis> int - The granularity in milliseconds of the last modification date for testing whether a source needs re-compilation
Default value is: 1000.
User property is: wix.staleMillis.
<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.
<candleProperties> Properties - Properties catch all in case we missed some configuration. Passed directly to candle
<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.
<definitions> Set - Definitions (pre) Compilation (-d option)
<excludes> Set - A set of exclusion filters.
<finalName> String - Base Name of the generated wix objects.
Default value is: ${project.build.finalName}.
User property is: wix.finalName.
<includePaths> String[] - Include paths (-I option)
<includes> Set - The set of files/patterns to include Defaults to "**\/*.wxs"
<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.
<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
<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.
<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)
<timestampDirectory> File - The directory to store the time-stamp file for the processed aid files.
Defaults to outputDirectory.
Only used with xsdTimestampFile being set.
Default value is: ${project.build.directory}/mapping/cpp.
User property is: wix.timestampDirectory.
<timestampFile> String - Set this value if you wish to have a single timestamp file to track changes rather than cxx,hxx comparison.
The time-stamp file for the processed xsd files.
User property is: wix.timestampFile.
<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

<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

<candleProperties>

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

<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

<definitions>

Definitions (pre) Compilation (-d option)
  • Type: java.util.Set
  • Required: No

<excludes>

A set of exclusion filters.
  • Type: java.util.Set
  • Required: No

<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

<includePaths>

Include paths (-I option)
  • Type: java.lang.String[]
  • Required: No

<includes>

The set of files/patterns to include Defaults to "**\/*.wxs"
  • Type: java.util.Set
  • Required: No

<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

<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}

<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

<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}

<skip>

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

<staleMillis>

The granularity in milliseconds of the last modification date for testing whether a source needs re-compilation
  • Type: int
  • Required: Yes
  • User Property: wix.staleMillis
  • Default: 1000

<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

<timestampDirectory>

The directory to store the time-stamp file for the processed aid files.
Defaults to outputDirectory.
Only used with xsdTimestampFile being set.
  • Type: java.io.File
  • Required: No
  • User Property: wix.timestampDirectory
  • Default: ${project.build.directory}/mapping/cpp

<timestampFile>

Set this value if you wish to have a single timestamp file to track changes rather than cxx,hxx comparison.
The time-stamp file for the processed xsd files.
  • Type: java.lang.String
  • Required: No
  • User Property: wix.timestampFile

<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