wix

Documentation

Overview

Package wix is a lightweight wrapper around the wix tooolset.

It is heavily inspired by golang's build system (2)

Background and Theory Of Operations

wix's toolchain is based around compiling xml files into installers. Wix provides a variety of tools that can help simply this. This package leverages them.

The basic steps of making a package:

1. Start with a xml file (TODO: consider a struct?)
2. Create a packageRoot directory structure
3. Use `heat` to harvest the file list from the packageRoot
4. Use `candle` to take the wxs from (1) and (3) and make a wixobj
5. Use `light` to compile thje wixobj into an msi

While this is a somewhat agnostic wrapper, it does make several assumptions about the underlying process. It is not meant as a complete wix wrapper.

So Many Guids

Windows uses guids to identify how MSIs related to one another. Windows defines three codes:

• UpgradeCode: Consistent for all releases of a product -- guid(name, identifier)
• ProductCode: Identifies a product release -- guid(name, identifier, hostname, version)
• PackageCode: Identifies a MSI package itself. WiX recommends this be left blank, and auto-generated

For a given input, we need a stable guid. Convinently, md5 produces a string of the correct length for these guids.

Note: MSIs can get quiet unhappy if they PackageCode changes, while the ProductCode remains the same. That will result in an error about "Another version of this product is already installed"

References

1. http://wixtoolset.org/
2. https://github.com/golang/build/blob/790500f5933191797a6638a27127be424f6ae2c2/cmd/release/releaselet.go#L224
3. https://blogs.msdn.microsoft.com/pusu/2009/06/10/what-are-upgrade-product-and-package-codes-used-for/
4. https://docs.microsoft.com/en-us/windows/desktop/Msi/preparing-an-application-for-future-major-upgrades
5. https://docs.microsoft.com/en-us/windows/desktop/Msi/productcode
6. https://www.firegiant.com/wix/tutorial/upgrades-and-modularization/

Index

• Constants
• func FindWixInstall() string
• func New(packageRoot string, mainWxsContent []byte, wixOpts ...WixOpt) (*wixTool, error)
• type ErrorControlType
• type InstallUninstallType
• type Service
  • func NewService(matchString string, opts ...ServiceOpt) *Service
  • func (s *Service) Match(line string) (bool, error)
  • func (s *Service) Xml(w io.Writer) error
• type ServiceConfig
• type ServiceControl
• type ServiceInstall
• type ServiceOpt
  • func ServiceArgs(args []string) ServiceOpt
  • func ServiceDescription(desc string) ServiceOpt
  • func ServiceName(name string) ServiceOpt
  • func WithDelayedStart() ServiceOpt
  • func WithDisabledService() ServiceOpt
• type StartType
• type UtilServiceConfig
• type WixOpt
  • func As32bit() WixOpt
  • func As64bit() WixOpt
  • func SkipCleanup() WixOpt
  • func SkipValidation() WixOpt
  • func WithBuildDir(path string) WixOpt
  • func WithDocker(image string) WixOpt
  • func WithFile(name string, content []byte) WixOpt
  • func WithService(service *Service) WixOpt
  • func WithUI() WixOpt
  • func WithWix(path string) WixOpt
• type YesNoType

Constants

const (
	ErrorControlIgnore   ErrorControlType = "ignore"
	ErrorControlNormal                    = "normal"
	ErrorControlCritical                  = "critical"
)

const (
	StartAuto     StartType = "auto"
	StartDemand             = "demand"
	StartDisabled           = "disabled"
	StartBoot               = "boot"
	StartSystem             = "system"
	StartNone               = ""
)

const (
	InstallUninstallInstall   InstallUninstallType = "install"
	InstallUninstallUninstall                      = "uninstall"
	InstallUninstallBoth                           = "both"
)

Functions

func FindWixInstall

func FindWixInstall() string

FindWixInstall will return the path wix will be executed from. This is exposed here, and not an internal method, as a convinience to `package-builder`

func New

func New(packageRoot string, mainWxsContent []byte, wixOpts ...WixOpt) (*wixTool, error)

New takes a packageRoot of files, and a wxsContent of xml wix configuration, and will return a struct with methods for building packages with.

Types

type ErrorControlType

type ErrorControlType string

type InstallUninstallType

type InstallUninstallType string

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service represents a wix service. It provides an interface to both ServiceInstall and ServiceControl.

func NewService

func NewService(matchString string, opts ...ServiceOpt) *Service

New returns a service

func (*Service) Match

func (s *Service) Match(line string) (bool, error)

Match returns a bool if there's a match, and throws an error if we have too many matches. This is to ensure the configured regex isn't broader than expected.

func (*Service) Xml

func (s *Service) Xml(w io.Writer) error

Xml converts a Service resource to Xml suitable for embedding

type ServiceConfig

type ServiceConfig struct {
	// TODO: this should need a namespace, and yet. See https://github.com/golang/go/issues/36813
	XMLName          xml.Name  `xml:"http://schemas.microsoft.com/wix/2006/wi ServiceConfig"`
	DelayedAutoStart YesNoType `xml:",attr,omitempty"`
	OnInstall        YesNoType `xml:",attr,omitempty"`
	OnReinstall      YesNoType `xml:",attr,omitempty"`
	OnUninstall      YesNoType `xml:",attr,omitempty"`
}

ServiceConfig implements https://wixtoolset.org/documentation/manual/v3/xsd/wix/serviceconfig.html This is used needed to set DelayedAutoStart

type ServiceControl

type ServiceControl struct {
	Name   string               `xml:",attr,omitempty"`
	Id     string               `xml:",attr,omitempty"`
	Remove InstallUninstallType `xml:",attr,omitempty"`
	Start  InstallUninstallType `xml:",attr,omitempty"`
	Stop   InstallUninstallType `xml:",attr,omitempty"`
	Wait   YesNoType            `xml:",attr,omitempty"`
}

ServiceControl implements http://wixtoolset.org/documentation/manual/v3/xsd/wix/servicecontrol.html

type ServiceInstall

type ServiceInstall struct {
	Account           string             `xml:",attr,omitempty"`
	Arguments         string             `xml:",attr,omitempty"`
	Description       string             `xml:",attr,omitempty"`
	DisplayName       string             `xml:",attr,omitempty"`
	EraseDescription  bool               `xml:",attr,omitempty"`
	ErrorControl      ErrorControlType   `xml:",attr,omitempty"`
	Id                string             `xml:",attr,omitempty"`
	Interactive       YesNoType          `xml:",attr,omitempty"`
	LoadOrderGroup    string             `xml:",attr,omitempty"`
	Name              string             `xml:",attr,omitempty"`
	Password          string             `xml:",attr,omitempty"`
	Start             StartType          `xml:",attr,omitempty"`
	Type              string             `xml:",attr,omitempty"`
	Vital             YesNoType          `xml:",attr,omitempty"` // The overall install should fail if this service fails to install
	UtilServiceConfig *UtilServiceConfig `xml:",omitempty"`
	ServiceConfig     *ServiceConfig     `xml:",omitempty"`
}

ServiceInstall implements http://wixtoolset.org/documentation/manual/v3/xsd/wix/serviceinstall.html

type ServiceOpt

type ServiceOpt func(*Service)

func ServiceArgs

func ServiceArgs(args []string) ServiceOpt

ServiceArgs takes an array of args, wraps them in spaces, then joins them into a string. Handling spaces in the arguments is a bit gnarly. Some parts of windows use ` as an escape character, but that doesn't seem to work here. However, we can use double quotes to wrap the whole string. But, in xml quotes are _always_ transmitted as html entities -- " or ". Luckily, wix seems fine with that. It converts them back to double quotes when it makes the service

func ServiceDescription

func ServiceDescription(desc string) ServiceOpt

func ServiceName

func ServiceName(name string) ServiceOpt

func WithDelayedStart

func WithDelayedStart() ServiceOpt

func WithDisabledService

func WithDisabledService() ServiceOpt

type StartType

type StartType string

type UtilServiceConfig

type UtilServiceConfig struct {
	XMLName                      xml.Name `xml:"http://schemas.microsoft.com/wix/UtilExtension ServiceConfig"`
	FirstFailureActionType       string   `xml:",attr,omitempty"`
	SecondFailureActionType      string   `xml:",attr,omitempty"`
	ThirdFailureActionType       string   `xml:",attr,omitempty"`
	RestartServiceDelayInSeconds int      `xml:",attr,omitempty"`
	ResetPeriodInDays            int      `xml:",attr,omitempty"`
}

UtilServiceConfig implements http://wixtoolset.org/documentation/manual/v3/xsd/util/serviceconfig.html This is used to set FailureActions. There are some limitations. Notably, reset period is in days here, though the underlying `sc.exe` command supports seconds. (See https://github.com/wixtoolset/issues/issues/5963)

Docs are a bit confusing. This schema is supported, and should work. The non-util ServiceConfig generates unsupported CNDL1150 errors.

type WixOpt

type WixOpt func(*wixTool)

func As32bit

func As32bit() WixOpt

func As64bit

func As64bit() WixOpt

func SkipCleanup

func SkipCleanup() WixOpt

func SkipValidation

func SkipValidation() WixOpt

If you're running this in a virtual win environment, you probably need to skip validation. LGHT0216 is a common error.

func WithBuildDir

func WithBuildDir(path string) WixOpt

func WithDocker

func WithDocker(image string) WixOpt

func WithFile

func WithFile(name string, content []byte) WixOpt

func WithService

func WithService(service *Service) WixOpt

func WithUI

func WithUI() WixOpt

func WithWix

func WithWix(path string) WixOpt

type YesNoType

type YesNoType string

http://wixtoolset.org/documentation/manual/v3/xsd/wix/serviceinstall.html http://wixtoolset.org/documentation/manual/v3/xsd/wix/servicecontrol.html https://helgeklein.com/blog/2014/09/real-world-example-wix-msi-application-installer/

const (
	Yes YesNoType = "yes"
	No            = "no"
)