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 ...] [@responseFile]
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 <path> |
Specify a base path to locate all files; the default value is the current working directory. |
|
-bcgg |
Use backwards compatible guid generation algorithm (rarely needed). |
|
-bf |
Bind files into a wixout; this switch is only valid when also providing the -xo option. |
|
-binder <classname> |
Specify a specific custom binder to use provided by an extension. |
|
-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](../howtos/ui_and_localization/specifying_cultures_to_build.html). |
|
-cub |
Provide a .cub file containing additional internal consistency evaluators (ICEs) to run. |
|
-d<name>=<value> |
Define a WiX variable. |
|
-dcl:level |
Set the default cabinet compression level. Possible values are low, medium, high, none, and mszip (default). |
|
-dut |
Drop unreal tables from the output image. |
|
-eav |
Exact assembly versions. If this option is not specified, the assembly version is padded with zeros
in certain cases to work around a bug that exists in the initial release of the .NET Framework 1.1.
This bug was subsequently fixed in the .NET Framework 1.1 SP1. Use this option if you require non-padded
assembly versions in the MsiAssemblyName table (or in relevant bind variables), and do not mind if your
MSI is incompatible with the initial release of the .NET Framework 1.1. For more information, see
this blog post.
|
|
-ext |
Specify an extension assembly. |
|
-fv |
Add a FileVersion attribute to each assembly in the MsiAssemblyName table (rarely needed). |
|
-ice: <ICE> |
Specify a specific internal consistency evaluator (ICE) to run. |
|
-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). |
|
-O1 |
Optimize smart cabbing for smallest cabinets (deprecated). |
|
-O2 |
Optimize smart cabbing for faster install time (deprecated). |
|
-out |
Specify an output file; by default, Light will write to the current working directory. |
|
-pdbout <output.wixpdb> |
Save the wixpdb to a specific file. The default is the same name as the output with the wixpdb extension. |
|
-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. |
|
-sloc |
Suppress localization. |
|
-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. |
|
-spdb |
Suppress outputting the wixpdb. |
|
-ss |
Suppress schema validation for documents; this switch provides a performance boost during linking. |
|
-sts |
Suppress tagging sectionId attribute on rows. |
|
-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. |
|
-swall |
Suppress all warnings (deprecated). |
|
-usf <output.xml> |
Specify an unreferenced symbols file. |
|
-v |
Generate verbose output. |
|
-wx <N> |
Treat warnings as errors. |
|
-wxall |
Treat all warnings as errors (deprecated). |
|
-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 |
!(bind.assemblyCulture.MyAssembly) |
neutral |
|
bind.assemblyFileVersion.FileID |
!(bind.assemblyFileVersion.MyAssembly) |
1.0.0.0 |
|
bind.assemblyFullName.FileID |
!(bind.assemblyFullName.MyAssembly) |
MyAssembly, version=1.0.0.0, culture=neutral, publicKeyToken=0123456789ABCDEF, processorArchitecture=MSIL Note: The publicKeyToken value is uppercased. |
|
bind.assemblyFullNamePreservedCase.FileID |
!(bind.assemblyFullNamePreservedCase.MyAssembly) |
MyAssembly, version=1.0.0.0, culture=neutral, publicKeyToken=0123456789abcdef, processorArchitecture=MSIL Note: The publicKeyToken value's casing is preserved. |
|
bind.assemblyName.FileID |
!(bind.assemblyName.MyAssembly) |
MyAssembly |
|
bind.assemblyProcessorArchitecture.FileID |
!(bind.assemblyProcessorArchitecture.MyAssembly) |
MSIL |
|
bind.assemblyPublicKeyToken.FileID |
!(bind.assemblyPublicKeyToken.MyAssembly) |
0123456789abcdef Note: The value is uppercased for managed assemblies. |
|
bind.assemblyPublicKeyTokenPreservedCase.FileID |
!(bind.assemblyPublicKeyTokenPreservedCase.MyAssembly) |
0123456789abcdef Note: The value's casing is preserved. |
|
bind.assemblyType.FileID |
!(bind.assemblyType.MyAssembly) |
win32 |
|
bind.assemblyVersion.FileID |
!(bind.assemblyVersion.MyAssembly) |
1.0.0.0 |
Properties
You can also reference property values from the Property table at bind time; however, you cannot reference properties as binder variables within other properties, including the attributes on the Product element - many of which are compiled into the Property table. You can reference other binder variables like file information above in properties, or even localization and custom binder variables documented below.
Specializations for each field of the ProductVersion property are also provided as shown below. If you have defined properties like ProductVersion.Major in your package authoring they will not be overwritten, but will be used instead of the automatic binder variables with the same name.
|
Variable name |
Example usage |
Example value |
|
bind.property.Property |
!(bind.property.ProductVersion) |
1.2.3.4 |
|
bind.property.ProductVersion.Major |
!(bind.property.ProductVersion.Major) |
1 |
|
bind.property.ProductVersion.Minor |
!(bind.property.ProductVersion.Minor) |
2 |
|
bind.property.ProductVersion.Build |
!(bind.property.ProductVersion.Build) |
3 |
|
bind.property.ProductVersion.Revision |
!(bind.property.ProductVersion.Revision) |
4 |
Package Properties
You can reference the following properties from packages in your bundle. This allows developers to use property values already defined in their packages to set attributes in their bundle.
|
Variable name |
Example usage |
Example value |
|
bind.packageDescription.PackageID |
!(bind.packageDescription.MyProduct) |
Description of My Product |
|
bind.packageLanguage.PackageID |
!(bind.packageLanguage.MyProduct) |
1033 |
|
bind.packageManufacturer.PackageID |
!(bind.packageManufacturer.MyProduct) |
My Company |
|
bind.packageName.PackageID |
!(bind.packageName.MyProduct) |
My Product |
|
bind.packageVersion.PackageID |
!(bind.packageVersion.MyProduct) |
1.2.3.4 |
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.