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.

Requirements

You need the following applications installed

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 <[email protected]>"
packageSummary := "test-windows"
packageDescription := """Test Windows MSI."""

// wix build information
wixProductId := "ce07be71-510d-414a-92d4-dff47631848a"
wixProductUpgradeId := "4552fb0e-e257-4dbd-9ecb-dba9dbacf424"

1.0 or higher

Enables the windows plugin

enablePlugins(WindowsPlugin)

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.

Windows / mappings := (Universal / mappings).value

Now, let’s look at the full set of windows settings.

Settings

Windows / name

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 overridden

wixProductLicense

An (optional) rtf file to display as the product license during installation. Defaults to src/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.

``Windows / packageMsi / mappings ``

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 embedded cab for the msi. 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 the Id 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:

  1. Files (ComponentFile)

  2. Path Configuration (AddDirectoryToPath)

  3. 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 Windows / mappings configuration. When generating a MSI, the plugin will first create a directory using all the Windows / mappings 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:

Windows / mappings ++= (Compile / packageBin, Windows / sourceDirectory) 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.