Menu
▾
▴
[WiX-commits] wix/src/chm/html bind_variables.htm, NONE, 1.1 localization.htm, NONE, 1.1 localized_extensions.htm, NONE, 1.1 localizing.htm, NONE, 1.1 extension_development.htm, 1.2, 1.3 light.htm, 1.3, 1.4 preprocessor.htm, 1.3, 1.4
Update of /cvsroot/wix/wix/src/chm/html In directory sc8-pr-cvs9.sourceforge.net:/tmp/cvs-serv6964/src/chm/html Modified Files: extension_development.htm light.htm preprocessor.htm Added Files: bind_variables.htm localization.htm localized_extensions.htm localizing.htm Log Message: RobMen: SFBUG:1653864 - fix off by 1 error in SQL String reading. HeathS: Added support for @RequiredVersion to WiX extension elements HeathS: Added support for attribute references in schemas MiCarls: Add a light error when trying to put an assembly that has no strong name into the MsiAssembly table, with "File_Application" column empty (installing to the GAC). HeathS: Converted chm.build to chm.proj HeathS: Added topics on bind variables and localization BobArnso: Switch to Server 2008 SDK build of .cubs to avoid false hits on MSI 4.0 features (sfbug:1841830, sfbug:1841341). MiCarls: Fix various exceptions related to bad file paths specified on the commandline also, stop parsing commandline parameters when "-?" is encountered. BobArnso: - Make the Extension element attribute-extensible - Modernize IniFile Name/LongName in Decompiler WixBuild: Version 3.0.3829.0 MGhazna: Implemented the ShowAllFiles feature for Votive projects. MilenL: Fix various project properties related bugs, mostly UI fit & finish VaraBall: Fixed Light and Lit targets authoring to pass project references. BobArnso: - Add Error table automatically if summary info schema set to <=100 (to avoid ICE40 warning). - Add link-time checking for IsolatedComponent table that require MSI 1.1+ with summary info schema set to <110. - Add link-time checking for Shortcut columns that require MSI 4.0+ with summary info schema set to <400. - Suppress ICE66 by default: The above checks make it obsolete and it incorrectly reports *any* Shortcut table with the MSI 4.0 columns as a warning, even if the column values are NULL. MiCarls: Cleaner warnings when scheduling rollback fails in SecureObjects CA PMarcu: Fixing error when multiple instance transforms have the same Id. Fix for instance transform generation failure when Product/@Id="*". MiCarls: Ensure Wow64 filesystem redirection is enabled when we get the MSXML interface BobArnso: SFBUG:1909111 - Add en-us strings to MSMQ and COM+ extensions. --- NEW FILE: localizing.htm --- <html> <head> <link rel="stylesheet" type="text/css" href="style.css"> <title>Localizing Packages</title> </head> <body> <h1>Localizing Packages</h1> <p>You can create localized Windows Installer packages using WiX by defining single product sources, but with multiple localization files, or .wxl files.</p> <h2>Compile Once</h2> <p>Because Windows Installer packages themselves are not localizable for the most part, you need to build multiple packages. But maintaining multiple sources can be difficult and error prone. WiX allows you to define single sources but to use binder variables for localized fields, or localization variables. In the example below, you'll see these expressions as !(loc.<i>variableName</i>).</p> <pre><?xml version="1.0" encoding="utf-8"?> <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi"> <Product Id="!(loc.ProductCode)" Name="!(loc.ProductName)" Language="!(loc.ProductLanguage)" Version="1.0.0.0" Manufacturer="Northwind" UpgradeCode="!(loc.UpgradeCode)"> <Package Languages="!(loc.ProductLanguage)" Description="!(loc.Description)" Comments="!(loc.Description)" InstallerVersion="200" Compressed="yes" SummaryCodepage="!(loc.CodePage)" /> <Media Id="1" Cabinet="product.cab" /> <Feature Id="MyFeature" Level="1" Description="!(loc.MyFeatureDescription)"> <ComponentRef Id="MyComponent" /> </Feature> <Directory Id="TARGETDIR" Name="SourceDir"> <Directory Id="LocalizedDir" Name="!(loc.ProductLanguage)" ComponentGuidGenerationSeed="8987128B-1430-4AC9-81F2-C51B60A3084C"> <!-- Assign auto-generated GUID --> <Component Id="MyComponent" Guid="*" DiskId="1"> <File Id="Example.txt" Name="Example.txt" Source="!(loc.ProductLanguage)\Example.txt" KeyPath="yes" /> </Component> </Directory> </Directory> </Product> </Wix></pre> <p>Author 1033\Example.txt with an example string, then compile your sources to a location to be linked and localized later.</p> <pre>candle.exe example.wxs -out example.wixobj</pre> <h2>Link and Localize Multiple Times</h2> <p>Once the package is compiled, you can link the .wixobj multiple times with different .wxl files. But first you must define your .wxl file, which is just a collection of strings.</p> <pre><?xml version="1.0" encoding="utf-8"?> <WixLocalization Culture="en-us" xmlns="http://schemas.microsoft.com/wix/2006/localization"> <String Id="CodePage" Localizable="no">Windows-1252</String> <String Id="Description">Installs the Localization Example</String> <String Id="MyFeatureDescription">Example Feature</String> <String Id="ProductCode" Localizable="no">{000C1109-1033-0000-D000-000000000046}</String> <String Id="ProductLanguage" Localizable="no">1033</String> <String Id="ProductName">Localization Example</String> <String Id="UpgradeCode" Localizable="no">{84108EA9-1033-4A62-9BB4-7093DD4CDC89}</String> </WixLocalization></pre> <p>Define separate .wxl files like en-us.wxl shown above for each language you will support. Be sure to set the WixLocalization/@Culture attribute to different culture names.</p> <p>Now link and localize your package to a culture-specific directory.</p> <pre>mkdir en-us light.exe example.wixobj -cultures:en-us -loc en-us.wxl -out 1033\example.msi</pre> <p>The -cultures switch is used to pick resources in extensions like the <a href="WixUI_dialog_library.htm">WixUIExtension</a>.</p> <p>You can build localized packages using WiX by compiling a single set of sources and linking to separate packages using different localized files. This makes maintaining sources for localized packages easier and less prone to inconsistencies.</p> </body> </html> Index: light.htm =================================================================== RCS file: /cvsroot/wix/wix/src/chm/html/light.htm,v retrieving revision 1.3 retrieving revision 1.4 diff -C2 -d -r1.3 -r1.4 *** light.htm 22 Feb 2008 09:35:34 -0000 1.3 --- light.htm 7 Mar 2008 08:34:20 -0000 1.4 *************** *** 26,31 **** <h2>Additional Topics</h2> <ul> <li><a href='light_usage.htm'>Light usage information</a></li> </ul> </body> ! </html> \ No newline at end of file --- 26,32 ---- <h2>Additional Topics</h2> <ul> + <li><a href='bind_variables.htm'>Binder variables</a></li> <li><a href='light_usage.htm'>Light usage information</a></li> </ul> </body> ! </html> Index: extension_development.htm =================================================================== RCS file: /cvsroot/wix/wix/src/chm/html/extension_development.htm,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -d -r1.2 -r1.3 *** extension_development.htm 22 Feb 2008 09:35:34 -0000 1.2 --- extension_development.htm 7 Mar 2008 08:34:20 -0000 1.3 *************** *** 22,27 **** </ul> <h2>Considerations</h2> ! Before investing in an extension, one should evaluate whether an external tool and the ?include syntax (from the preprocessor) will provide the needed flexibility for your technical needs. ! Multiple extensions and extension types are supported, but there is no guarantee of the order in which a particular class of extensions will be processed. As a result, there must not be any sequencing dependencies between extensions within the same extension class. </body> ! </html> \ No newline at end of file --- 22,41 ---- </ul> <h2>Considerations</h2> ! <p>Before investing in an extension, one should evaluate whether an external tool and the ?include syntax (from the preprocessor) will provide the needed flexibility for your technical needs.</p> ! <p>Multiple extensions and extension types are supported, but there is no guarantee of the order in which a particular class of extensions will be processed. As a result, there must not be any sequencing dependencies between extensions within the same extension class.</p> ! <p>Extension developers might also implement a RequiredVersion attribute on the <a href="wix_xsd_wix.htm">Wix</a> element. This allows setup developers using your extension to require a specific version of the extension in case a new feature is introduced or a breaking change is made. You can add an attribute to the Wix element in an extension as shown in the following example.</p> ! <pre><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" ! xmlns:xse="http://schemas.microsoft.com/wix/2005/XmlSchemaExtension"> ! <xs:attribute name="RequiredVersion" type="xs:string"> ! <xs:annotation> ! <xs:documentation> ! The version of this extension required to compile the defining source. ! </xs:documentation> ! <xs:appinfo> ! <xse:parent namespace="http://schemas.microsoft.com/wix/2006/wi" ref="Wix" /> ! </xs:appinfo> ! </xs:annotation> ! </xs:attribute> ! </xs:schema></pre> </body> ! </html> --- NEW FILE: localization.htm --- <html> <head> <link rel="stylesheet" type="text/css" href="style.css"> <title>Localization</title> </head> <body> <h1>Localization</h1> <p>WiX provides robust localization features. You can build multiple localized packages from a single set of source files, as well as build extensions that support one or more languages.</p> <ul> <li><a href="localizing.htm">Localizing Packages</a></li> <li><a href="localized_extensions.htm">Localized Extensions</a></li> </ul> </body> </html> --- NEW FILE: bind_variables.htm --- <html> <head> <link rel="stylesheet" type="text/css" href="style.css"> <title>Binder Variables</title> </head> <body> <h1>Binder Variables</h1> <h2>Standard Binder Variables</h2> <p>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.</p> <h3>All Versioned Files</h3> <p>The following standard binder variables are available for all versioned binaries.</p> <table border="1" cellspacing="0" cellpadding="2"> <tr> <td><p><b>Variable name</b></p></td> <td><p><b>Example usage</b></p></td> <td><p><b>Example value</b></p></td> </tr> <tr> <td><p><nobr>bind.fileLanguage.<i>FileID</i></nobr></p></td> <td><p><nobr>!(bind.fileLanguage.MyFile</nobr></p></td> <td><p>1033</p></td> </tr> <tr> <td><p><nobr>bind.fileVersion.<i>FileID</i></nobr></p></td> <td><p><nobr>!(bind.fileVersion.MyFile)</nobr></p></td> <td><p>1.0.0.0</p></td> </tr> </table> <h3>Assemblies</h3> <p>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".</p> <table border="1" cellspacing="0" cellpadding="2"> <tr> <td><p><b>Variable name</b></p></td> <td><p><b>Example usage</b></p></td> <td><p><b>Example value</b></p></td> </tr> <tr> <td><p><nobr>bind.assemblyCulture.<i>FileID</i><br><i>(managed only)</i></nobr></p></td> <td><p><nobr>!(bind.assemblyCulture.MyAssembly)</nobr></p></td> <td><p>neutral</p></td> </tr> <tr> <td><p><nobr>bind.assemblyFileVersion.<i>FileID</i></nobr></p></td> <td><p><nobr>!(bind.assemblyFileVersion.MyAssembly)</nobr></p></td> <td><p>1.0.0.0</p></td> </tr> <tr> <td><p><nobr>bind.assemblyFullName.<i>FileID</i><br><i>(managed only)</i></nobr></p></td> <td><p><nobr>!(bind.assemblyName.MyAssembly)</nobr></p></td> <td><p>MyAssembly, version=1.0.0.0, culture=neutral, publicKeyToken=0123456789abcdef, processorArchitecture=MSIL</p></td> </tr> <tr> <td><p><nobr>bind.assemblyName.<i>FileID</i></nobr></p></td> <td><p><nobr>!(bind.assemblyName.MyAssembly)</nobr></p></td> <td><p>MyAssembly</p></td> </tr> <tr> <td><p><nobr>bind.assemblyProcessorArchitecture.<i>FileID</i></nobr></p></td> <td><p><nobr>!(bind.assemblyProcessorArchitecture.MyAssembly)</nobr></p></td> <td><p>MSIL</p></td> </tr> <tr> <td><p><nobr>bind.assemblyPublicKeyToken.<i>FileID</i></nobr></p></td> <td><p><nobr>!(bind.assemblyPublicKeyToken.MyAssembly)</nobr></p></td> <td><p>0123456789abcdef</p></td> </tr> <tr> <td><p><nobr>bind.assemblyType.<i>FileID</i><br><i>(native only)</i></nobr></p></td> <td><p><nobr>!(bind.assemblyType.MyAssembly)</nobr></p></td> <td><p>win32</p></td> </tr> <tr> <td><p><nobr>bind.assemblyVersion.<i>FileID</i></nobr></p></td> <td><p><nobr>!(bind.assemblyVersion.MyAssembly)</nobr></p></td> <td><p>1.0.0.0</p></td> </tr> </table> <h2>Localization Variables</h2> <p>Variables can be passed in before binding the output file from a <a href="wxl.htm">WiX localization file</a>, 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.</p> <p>Localization variables are in the following format:</p> <pre> !(loc.<i>VariableName</i>) </pre> <p>Read more about <a href="localization.htm">localization</a> for how to create and link .wxl files.</p> <h2>Custom Binder Variables</h2> <p>You can create your own binder variables using the <a href="wix_xsd_wixvariable.htm">WixVariable</a> element or by simply typing your own variable name in the following format:</p> <pre> !(bind.<i>VariableName</i>) </pre> <p>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.</p> </body> </html> --- NEW FILE: localized_extensions.htm --- <html> <head> <link rel="stylesheet" type="text/css" href="style.css"> <title>Localized Extensions</title> </head> <body> <h1>Localized Extensions</h1> <p>You can create your own localized extensions like <a href="WixUI_dialog_library.htm">WixUIExtension</a> using <a href="lit.htm">lit.exe</a>. Localized extensions can even contain multiple languages. Products using these extensions can pass the -cultures switch to <a href="light.htm">light.exe</a> along with the -ext switch to reference the extension.</p> <h2>Authoring Libraries</h2> <p><a href="extension_development.htm">WiX extensions</a> contain libraries comprised of fragments. These fragments may contain properties, search properties, dialogs, and more. Just like when <a href="localizing.htm">localizing products</a>, replace any localizable fields with variables in the format !(loc.<i>variableName</i>). Product would be authored to reference elements in this library, and when compiled would themselves contain the localization variables.</p> <h2>Authoring Localization Files</h2> <p>The WiX localization files, or .wxl files, are a collection of strings. For libraries, extension developers can choose whether or not those strings can be overwritten by .wxl files specified during linkage of the product. For example, part of the WixUIExtension's en-US resources are copied below.</p> <pre><?xml version="1.0" encoding="utf-8"?> <WixLocalization Culture="en-us" xmlns="http://schemas.microsoft.com/wix/2006/localization"> <String Id="WixUIBack" Overridable="yes">&amp;Back</String> <String Id="WixUINext" Overridable="yes">&amp;Next</String> <String Id="WixUICancel" Overridable="yes">Cancel</String> <String Id="WixUIFinish" Overridable="yes">&amp;Finish</String> <String Id="WixUIRetry" Overridable="yes">&amp;Retry</String> <String Id="WixUIIgnore" Overridable="yes">&amp;Ignore</String> <String Id="WixUIYes" Overridable="yes">&amp;Yes</String> <String Id="WixUINo" Overridable="yes">&amp;No</String> <String Id="WixUIOK" Overridable="yes">OK</String> </WixLocalization></pre> <p>These <a href="wixloc_xsd_string.htm">String</a> elements are attributed as @Overridable="yes" to allow for product developers to override these strings with their own values if they so choose. For example, a product developer may wish to use "Previous" instead of "Back", so they can define the same String/@Id in their own .wxl while still linking to the extension where that string is used. This offers product developers the benefits of the library while allowing for customizations. Extension developers can also choose to disallow overriding certain strings if it makes sense to do so.</p> <h2>Building Libraries</h2> <p>When all the fragment authoring and localization files are complete, they can be compiled and linked together using <a href="candle.htm">candle.exe</a> and <a href="lit.htm">lit.exe</a>.</p> <p>First compile all the .wxs sources.</p> <pre>candle.exe example1.wxs -out example1.wixobj candle.exe example2.wxs -out example2.wixobj</pre> <p>Now link together all the .wixobj files an .wxl files for each culture you want available in the extension library.</p> <pre>lit.exe example1.wixobj example2.wixobj -loc en-us.wxl -loc de-de.wxl -out example.wixlib</pre> <p>To be useful, the .wixlib should be embedded into a managed assembly and returned by WixExtension.GetLibrary().</p> <h2>Using the Libraries</h2> <p>Product developers reference elements within your .wixlib, as shown in the <a href="WixUI_dialog_library.htm">WixUIExtension</a> example. When compiling and linking, the extension is specified on the command line using the -ext switch. If any additional localization variables are used in the product authoring or would override localization variables in the library, those .wxl files are passed to the -loc switch as shown in the example below.</p> <pre>candle.exe example.wxs -ext WixUIExtension -out example.wixobj light.exe example.wixobj -ext WixUIExtension -cultures:en-us -loc en-us.wxl -out example.msi</pre> </body> </html> Index: preprocessor.htm =================================================================== RCS file: /cvsroot/wix/wix/src/chm/html/preprocessor.htm,v retrieving revision 1.3 retrieving revision 1.4 diff -C2 -d -r1.3 -r1.4 *** preprocessor.htm 22 Feb 2008 09:35:34 -0000 1.3 --- preprocessor.htm 7 Mar 2008 08:34:20 -0000 1.4 *************** *** 79,83 **** <h3>Custom variables <? define ?></h3> <p> ! If you want to define custom variables, you need to use the <?define?> statement. Later, the variables are referred to in the <?if?> statements with the syntax $(var.VarName). Variable names are case-sensitive. </p> <p> --- 79,83 ---- <h3>Custom variables <? define ?></h3> <p> ! If you want to define custom variables, you can use the <?define?> statement. You can also define variables on the command line using candle.exe using the -d switch. Later, the variables are referred to in the <?if?> statements with the syntax $(var.VarName). Variable names are case-sensitive. </p> <p> *************** *** 97,100 **** --- 97,105 ---- <?undef MyVariable ?><br /> </p> + <p>To define variables on the command line, you can type a command similar to the following:<p> + <pre> + candle.exe -dMyVariable="Hello World" ... + </pre> + <p>You can refer to variables in your source that are defined only on the command line, but candle.exe will err when preprocessing your source code if you do not define those variables on the command line.</p> <h2>Conditional Statements</h2> *************** *** 257,259 **** </body> ! </html> \ No newline at end of file --- 262,264 ---- </body> ! </html> |