Windows Plugin¶
Windows packaging is completely tied to the WIX installer toolset. For any non-trivial package, it’s important to understand how WIX works. http://wix.tramontana.co.hu/ is an excellent tutorial to how to create packages using wix.
However, the native-packager provides a simple layer on top of wix that may be enough for most projects.
If it is not enough, just override wixConfig
or wixFiles
tasks. Let’s look at the layer above direct
xml configuration.
Note
The windows plugin depends on the Universal Plugin.
Build¶
sbt windows:packageBin
Required Settings¶
A windows package needs some mandatory settings to be valid. Make sure you have these settings in your build:
// general package information (can be scoped to Windows)
maintainer := "Josh Suereth <joshua.suereth@typesafe.com>"
packageSummary := "test-windows"
packageDescription := """Test Windows MSI."""
// wix build information
wixProductId := "ce07be71-510d-414a-92d4-dff47631848a"
wixProductUpgradeId := "4552fb0e-e257-4dbd-9ecb-dba9dbacf424"
0.8 or lower¶
For these versions windows packaging is automatically activated. See the Getting Started page for information on how to enable sbt-native-packager.
Configuration¶
Settings and Tasks inherited from parent plugins can be scoped with Universal
.
mappings in Windows := (mappings in Universal).value
Now, let’s look at the full set of windows settings.
Settings¶
name in Windows
- The name of the generated msi file.
candleOptions
- the list of options to pass to the
candle.exe
command.lightOptions
- the list of options to pass to the
light.exe
command. Most likely setting is:Seq("-ext", "WixUIExtension", "-cultures:en-us")
for UI.wixMajorVersion
- the major version of the Wix tool-set (e.g. when using Wix 4.0.1, major version is 4). Default is 3.
wixProductId
- The GUID to use to identify the windows package/product.
wixProductUpgradeId
- The GUID to use to identify the windows package/product upgrade identifier (See the wix docs on upgrades).
wixPackageInfo
- The information used to autoconstruct the
<Product><Package/>
portion of the wix xml. Note: unused if ``wixConfig`` is overriddenwixProductLicense
- An (optional)
rtf
file to display as the product license during installation. Defaults tosrc/windows/License.rtf
wixFeatures
- A set of windows features that users can install with this package. Note: unused if ``wixConfig`` is overridden
wixProductConfig
- inline XML to use for wix configuration. This is everything nested inside the
<Product>
element.wixConfig
- inline XML to use for wix configuration. This is used if the
wixFiles
task is not specified.wixFiles
- WIX xml source files (
wxs
) that define the build.mappings in packageMsi in Windows
- A list of file->location pairs. This list is used to move files into a location where WIX can pick up the files and generate a
cab
or embeddedcab
for themsi
. The WIX xml should use the relative locations in this mappings when referencing files for the package.
Tasks¶
windows:packageBin
- Creates the
msi
package.wixFile
- Generates the Wix xml file from wixConfig and wixProductConfig setings, unless overriden.
The native-packager plugin provides a few handy utilities for generating Wix XML. These
utilities are located in the com.typesafe.packager.windows.WixHelper
object. Among
these are the following functions:
cleanStringForId(String): String
- Takes in a string and returns a wix-friendly identifier. Note: truncates to 50 characters.
cleanFileName(String): String
- Takes in a file name and replaces any
$
with$$
to make it past the Wix preprocessor.generateComponentsAndDirectoryXml(File): (Seq[String], scala.xml.Node)
- This method will take a file and generate
<Directory>
,<Component>
and<File>
XML elements for all files/directories contained in the given file. It will return theId
settings for any generated components. This is a handy way to package a large directory of files for usage in the Features of an MSI.
Customize¶
Feature configuration¶
The abstraction over wix allows you to configure “features” that users may optionally install. These feature are higher level things, like a set of files or menu links. The currently supported components of features are:
- Files (
ComponentFile
) - Path Configuration (
AddDirectoryToPath
) - Menu Shortcuts (
AddShortCuts
)
To create a new feature, simple instantiate the WindowsFeature
class with the desired feature components that are included.
Here’s an example feature that installs a binary file (cool.jar) and a script (cool.bat), and adds a directory to the PATH:
wixFeatures += WindowsFeature(
id="BinaryAndPath",
title="My Project's Binaries and updated PATH settings",
desc="Update PATH environment variables (requires restart).",
components = Seq(
ComponentFile("bin/cool.bat"),
ComponentFile("lib/cool.jar"),
AddDirectoryToPath("bin"))
)
All file references should line up exactly with those found in the mappings in Windows
configuration. When generating a MSI, the plugin will first create
a directory using all the mappings in Windows
and configure this for inclusion in a cab
file. If you’d like to add files to include, these must first
be added to the mappings, and then to a feature. For example, if we complete the above setting to include file mappings, we’d have the following:
mappings in Windows ++= (packageBin in Compile, sourceDirectory in Windows) map { (jar, dir) =>
Seq(jar -> "lib/cool.jar", (dir / "cool.bat") -> "bin/cool.bat")
}
wixFeatures += WindowsFeature(
id="BinaryAndPath",
title="My Project's Binaries and updated PATH settings",
desc="Update PATH environment variables (requires restart).",
components = Seq(
ComponentFile("bin/cool.bat"),
ComponentFile("lib/cool.jar"),
AddDirectoryToPath("bin"))
)
Right now this layer is very limited in what it can accomplish, and hasn’t been heavily debugged. If you’re interested in helping contribute, please
do so! However, for most command line tools, it should be sufficient for generating a basic msi
that Windows users can install.