WiX provides two ways of identifying a setup package’s payload – the files that are included in the setup and installed on the user’s machine.
- By file name and directory tree.
- By explicit source file.
Compiling, linking, and binding
The WiX toolset models a typical C/C++ compiler is how authored is built, with a compiler that parses the WiX source authoring to object files and a linker that combines the object files into an output. For WiX, the output is an .msi package, .msm merge module, or .wixlib library, which have a third phase: binding payload files into the output. Light.exe includes both the linker and binder.
Though WiX source authoring refers to payload files, the compiler never looks at them; instead, only the binder does, when it creates cabinets containing them or copies them to an uncompressed layout.
You can provide the binder with one or more base input paths it uses to look for files. It also looks for files relative to the current working directory. Light.exe’s –b switch and the BaseInputPaths .wixproj property let you specify one or more base input paths.
Identifying files by name and directory tree
When you use the File/@Name attribute and don’t use the File/@Source attribute, the compiler constructs an implicit path to the file based on the file’s parent component directory plus the name you supply. So, for example, given the partial authoring
<Directory Id="TARGETDIR">
<Directory Name="foo">
<Directory Name="bar">
<Component>
<File Name="baz.txt" />
the binder looks for a file foo\bar\baz.txt in the base input paths.
Overriding implicit payload directories
The FileSource attribute for the Directory and DirectoryRef elements sets a new directory for files in that directory or any child directories. For example, given the partial authoring
<Directory Id="TARGETDIR">
<Directory Name="foo" FileSource="build\retail\x86">
<Directory Name="bar">
<Component>
<File Name="baz.txt" />
the binder looks for a file build\retail\x86\bar\baz.txt in the base input paths.
The FileSource attribute can use preprocessor variables or environment variables. If the value is an absolute path, the binder’s base input paths aren’t used.
Preferred use
If the build tree serving as your payload source is almost identical to the tree of your installed image and you have a moderate-to-deep directory tree, using implicit paths will avoid repetition in your authoring.
Source directories
The Directory/@SourceName attribute controls both the name of the directory where Light.exe looks for files and the "source directory" in the .msi package. Unless you also want to control the source directory, just use FileSource.
Identifying payload by source files
The File/@Source attribute is a path to the payload file. It can be an absolute path or relative to any base input path. If File/@Source is present, it takes precedence over the implicit path created by Directory/@Name, Directory/@FileSource, and File/@Name.
If you specify File/@Source, you can omit File/@Name because the compiler automatically sets it to the filename portion of the source path.
Preferred use
If the build tree serving as your payload source is different from the tree of your installed image, using File/@Source makes it easy to pick explicit paths than are different than the .msi package’s directory tree. You can use multiple base input paths to shorten the File/@Source paths.
For example, the WiX setup .wixproj project points to the output tree for the x86, x64, and ia64 platforms WiX supports and the WiX source tree. Unique filenames can be referred to with just their filenames; files with the same name across platforms use relative paths.
See the WiX authoring in src\Setup\*.wxs for examples.