Linker (light)

The Windows Installer XML linker is exposed by light.exe. Light is responsible for processing one or more .wixobj files, retrieving metadata from various external files and creating a Windows Installer database (MSI or MSM). When necessary, light will also create cabinets and embed streams in the created Windows Installer database.

The linker begins by searching the set of object files provided on the command line to find the entry section. If more than one entry section is found, light fails with an error. This failure is necessary because the entry section defines what type of Windows Installer database is being created, a MSI or MSM. It is not possible to create two databases from a single link operation.

While the linker was determining the entry section, the symbols defined in each object file are stored in a symbol table. After the entry section is found, the linker attempts to resolve all of the references in the section by finding symbols in the symbol table. When a symbol is found in a different section, the linker recursively attempts to resolve references in the new section. This process of gathering the sections necessary to resolve all of the references continues until all references are satisfied. If a symbol cannot be found in any of the provided object files, the linker aborts processing with an error indicating the undefined symbol.

After all of the sections have been found, complex and reverse references are processed. This processing is where Components and Merge Modules are hooked to their parent Features or, in the case of Merge Modules, Components are added to the ModuleComponents table. The reverse reference processing adds the appropriate Feature identifier to the necessary fields for elements like, Shortcut, Class, and TypeLib.

Once all of the references are resolved, the linker processes all of the rows retrieving the language, version, and hash for referenced files, calculating the media layout, and including the necessary standard actions to ensure a successful installation sequence. This part of the processing typically ends up generating additional rows that get added associated with the entry section to ensure they are included in the final Windows Installer database.

Finally, light works through the mechanics of generating IDT files and importing them into the Windows Installer database. After the database is fully created, the final post processing is done to merge in any Merge Modules and create a cabinet if necessary. The result is a fully functional Windows Installer database.

Usage Information

light.exe [-?] [-b basePath] [-nologo] [-out outputFile] objectFile [objectFile ...]

Light supports the following command line parameters:

Switch	Meaning
-ai	Allow identical rows; identical rows will be treated as a warning
-au	Allow unresolved references; this will cause invalid output to be created
-b	Specify a base path to locate all files; the default value is the current working directory
-bf	Bind files into a wixout; this switch is only valid when also providing the -xo option
-cc	Specify a path to cache built cabinet files; the path will not be deleted after linking
-ct <N>	Specify the number of threads to use when creating cabinets; the default is the %NUMBER_OF_PROCESSORS% environment variable
-cultures:<cultures>	Specifies a semicolon or comma delimited list of localized string cultures to load from .wxl files and libraries. Precedence of cultures is from left to right. For more information see Specifying cultures to build.
-cub	Provide a .cub file containing additional internal consistency evaluators (ICEs) to run
-d<name>=<value>	Define a WiX variable
-ext	Specify an extension assembly
-fv	Add a FileVersion attribute to each assembly in the MsiAssemblyName table (rarely needed)
-loc <loc.wxl>	Provide a .wxl file to read localization strings from
-nologo	Skip printing Light logo information
-notidy	Prevent Light from deleting temporary files after linking is complete (useful for debugging)
-out	Specify an output file; by default, Light will write to the current working directory
-pedantic	Display pedantic output messages
-reusecab	Reuse cabinets from the cabinet cache instead of rebuilding cabinets
-sa	Suppress assemblies: do not get assembly name information for assemblies
-sacl	Suppress resetting ACLs (useful when laying out an image to a network share)
-sadmin	Suppress adding default Admin sequence actions
-sadv	Suppress adding default Advt sequence actions
-sdut	Suppress dropping unreal tables to the output image; this switch is set by default when the -xo switch is provided
-sice:<ICE>	Suppress running internal consistency evaluators (ICEs) with specific IDs
-sma	Suppress processing the data in the MsiAssembly table
-sf	Suppress files: do not get any file information; this switch is equivalent to the combination of the -sa and -sh switches
-sh	Suppress file information: do not get hash, version, language and other file properties
-sl	Suppress layout creation
-ss	Suppress schema validation for documents; this switch provides a performance boost during linking
-sui	Suppress adding default UI sequence actions
-sv	Suppress intermediate file version mismatch checking
-sval	Suppress MSI/MSM validation
-sw<N>	Suppress warnings with specific message IDs
-ts	Tag sectionId attribute on rows; this switch is set by default when the -xo switch is provided
-tsa	Tag sectionId attribute on rows and generate the rows when null; this switch is set by default when the -xo switch is provided
-usf <output.xml>	Specify an unreferenced symbols file
-v	Generate verbose output
-wx	Treat warnings as errors
-xo	Generate XML output instead of an MSI
-?	Display Light help information

Binder Variables

Standard Binder Variables

Some properties are not available until the linker is about to generate, or bind, the final output. These variables are called binder variables and supported binder variables are listed below.

All Versioned Files

The following standard binder variables are available for all versioned binaries.

Variable name	Example usage	Example value
bind.fileLanguage.FileID	!(bind.fileLanguage.MyFile)	1033
bind.fileVersion.FileID	!(bind.fileVersion.MyFile)	1.0.0.0

Assemblies

The following standard binder variables are available for all managed and native assemblies (except where noted), where the File/@Assembly attribute is set to ".net" or "win32".

Variable name	Example usage	Example value
bind.assemblyCulture.FileID (managed only)	!(bind.assemblyCulture.MyAssembly)	neutral
bind.assemblyFileVersion.FileID	!(bind.assemblyFileVersion.MyAssembly)	1.0.0.0
bind.assemblyFullName.FileID (managed only)	!(bind.assemblyName.MyAssembly)	MyAssembly, version=1.0.0.0, culture=neutral, publicKeyToken=0123456789abcdef, processorArchitecture=MSIL
bind.assemblyName.FileID	!(bind.assemblyName.MyAssembly)	MyAssembly
bind.assemblyProcessorArchitecture.FileID	!(bind.assemblyProcessorArchitecture.MyAssembly)	MSIL
bind.assemblyPublicKeyToken.FileID	!(bind.assemblyPublicKeyToken.MyAssembly)	0123456789abcdef
bind.assemblyType.FileID (native only)	!(bind.assemblyType.MyAssembly)	win32
bind.assemblyVersion.FileID	!(bind.assemblyVersion.MyAssembly)	1.0.0.0

Localization Variables

Variables can be passed in before binding the output file from a WiX localization file, or .wxl file. This process allows the developer to link one or more .wixobj files together with diferent .wxl files to produce different localized packages.

Localization variables are in the following format:

!(loc.VariableName)

Custom Binder Variables

You can create your own binder variables using the WixVariable element or by simply typing your own variable name in the following format:

!(bind.VariableName)

Custom binder variables allow you to use the same .wixobj files but specify different values when linking, similar to how localization variables are used. You might use binder variables for different builds, like varying the target processor architecture.