[mirror/winof/.git] / WinOF / WIX / README.txt
1 [04-10-09]\r
2 \r
3 How to generate a Windows OpenFabrics Release (WinOF) using the WIX 2.0 open\r
4 source installer tool set ( http://sourceforge.net/projects/wix/ ).\r
5 \r
6 WIX References:\r
7         WIX collection http://www.dalun.com/wix/default.htm\r
8         WIX Tutorial http://www.tramontana.co.hu/wix/\r
9         WIX sourceforge project http://sourceforge.net/projects/wix/\r
10         WIX Introduction http://wix.sourceforge.net/manual-wix2/wix_index.htm   \r
11 \r
12 \r
13 WinOF Revisions: (based on)\r
14   1.0   svn.614\r
15   1.0.1 svn.864\r
16   1.1   svn.1177\r
17   2.0   svn.1763\r
18   2.0.2 svn.1975\r
19 \r
20 \r
21 \r
22 Creating a binary release tree\r
23 ------------------------------\r
24 \r
25 As of WinOF 2.0 release [Aug'08] the build environment has been switched over to\r
26 Microsoft's WDK (Windows Driver Kit) version 6001.180001.\r
27 \r
28 See gen1\trunk\WinOF\BuildRelease.bat file to generate a Wix installer (.msi\r
29 file) containing signed driver files.\r
30 The OS flavor WLH\ - Vista/Server 2008[LongHorn], WNET\ - Server 2003+XP64\r
31 and XP\ (x86 only) bin\ folders will be populated with the correct folder\r
32 structure such that a WIX installer (.msi) files can be generated; either\r
33 cd into OS\arch dir and run buildmsi.bat or use WinOF\BuildRelease.bat.\r
34 \r
35 Warning - buildrelease.bat is not generic, some asembly required as the folder\r
36 structure is assumed; see SVN to set build SVN (aka OPENIB_REV).\r
37 \r
38 BuildRelease.bat will by default deposit 7 .msi files in\r
39 '%SystemRoot%\temp\WinOF_OS_arch.msi'.\r
40 \r
41 \r
42 The other approach to creating a binary release tree is to generate the\r
43 contents of WIX\bin\ yourself from a WDK/SDK build window which can run\r
44 'nmake'.\r
45 \r
46   1) Generate binaries for each supported architecture: x86, x64 and ia64.\r
47      cd to trunk; build /wg from a WDK OS and arch specific command window; all\r
48      are required by etc\makebin.bat.\r
49 \r
50   2) from trunk: execute 'etc\makebin %CD% dest-dir OS-flavor' for each OS\r
51      flavor: wnet, wlh and wxp.\r
52      Say your svn repository is at C:\open-ib\, then to populate the WIX bin\r
53      folder for Server 2008 binaries from a command window:\r
54         makebin C:\open-ib\gen1\trunk C:\open-ib\gen1\WinOF\Wix\WLH\bin WLH\r
55 \r
56 With the arrival of Windows Server 2008 & Vista (WLH - Windows LongHorn) driver\r
57 signing is a requirement. The WIX\sign-all-drivers.bat script will create a .cat\r
58 file for each driver .inf located. The generation of the .cat file is driven\r
59 from the corresponding driver.inf file via inf2cat.exe creating the .cat file\r
60 and signtool.exe signing the .cat and .sys files.\r
61 \r
62 A SW publisher's digital-ID certificate is required in order for WinOF\r
63 installers to be created. A test certificate can be generated for local use,\r
64 requires overhead during installation ('bcdedit -set testsigning on', reboot &\r
65 local certificate store updates).\r
66 The MS prescribed procedure is to obtain a SW publisher's certificate from\r
67 VeriSign or other CA agency; if your company is producing SW drivers for\r
68 SVR2008/Vista, then you will likely have access to a cert file.\r
69 The OFA will be purchasing a certificate for WinOF publication.\r
70 Scripts for signing drivers assume the MS cross-certification .cer file will be\r
71 resident in 'trunk\WinOF\Wix\*.cer'; your company Cert must be placed in the\r
72 local cert store under the default personal 'My' store. \r
73 see trunk\winof\buildrelease.bat for an example of how to invoke driver\r
74 signing or 'WIX\sign-all-drivers.bat'.\r
75 Also see the Microsoft 'Kernel Mode Code Signing' document\r
76 'KMCS_Walkthrough.doc'; goggle for current URL.\r
77 \r
78 \r
79 Creating a WIX tool set\r
80 -------------------------\r
81 \r
82 Download the WIX v2 (stable) tool set (http://sourceforge.net/projects/wix/)\r
83 to \91WinOF\WIX\WIX_tools\\92.\r
84 Unzip the archive to a folder within 'WIX_tools\' as this folder represents the\r
85 version of the tool set.\r
86 Something like unzip wix-2.0.5325.0-binaries.zip into wix-2.0.5325.0-binaries\.\r
87 You would now have the following structure:\r
88         WinOF\WIX\WIX_tools\wix-2.0.5325.0-binaries\{candle.exe, light.exe,...}\r
89 Point being Trunk\WinOF\buildRelease.bat needs the path to the WIX tool set.\r
90 \r
91 \r
92 \r
93 Updating Release Files\r
94 ---------------------\r
95 \r
96 Update Release_notes.htm file.\r
97 \r
98         The file 'Release_notes.htm' represents the next to be released\r
99         WinOF version, as reflected by is Release ID.\r
100 \r
101         Release ID number (e.g., 1.0, point releases are 1.0.x)\r
102 \r
103         New features\r
104 \r
105         Know issues\r
106 \r
107 Update the trunk\docs\Manual.htm file for new features.\r
108 \r
109 \r
110 BUILDING a .msi installer image file\r
111 ------------------------------------\r
112 \r
113 Easy way:\r
114  place MS cross certificate file (.cer) in WIX\ folder; 'My' cert store needs\r
115  to contain your company cert file; WinOF\BuildRelease.bat needs the name of\r
116  your company cert file; OFA case 'OpenFabrics Alliance'.\r
117  .\r
118  cd trunk\\r
119  From a standard DOS cmd window, not a WDK cmd window, say \r
120 \r
121    buildrelease all             # .msi files created in %windir%\temp\*.msi\r
122 \r
123    buildrelease makebin - assumes trunk\bin\* built,\r
124                           populates WIX\{wlh,wnet,wxp}\bin folders.\r
125    buildrelease sign - sign driver files & exit, assumes makebin has been run.\r
126    buildrelease msi - signs & creates installers assuming makebin has been run.\r
127    buildrelease wix - creates .msi installers - assumes all bin\ folders\r
128                       populated and drivers signed.\r
129 \r
130 CPU specific builds\r
131 \r
132 CD to the WIX OS-flavor and architecture specific directory. 'nmake.exe' needs\r
133 to be in your command window search path. Build three arch specific installers\r
134 (.msi files) for WLH and WNET; WXP is x86 only. \r
135 \r
136 WARNING:\r
137    assupmtion: .\bin is populated correctly from makebin.bat or\r
138    'BuildRelease makebin'.\r
139 \r
140 cd gen1\trunk\WinOF\WIX\wlh\x86 & nmake\r
141         Results in a .\WOF_wlh_x86.msi installer image.\r
142 \r
143 cd gen1\trunk\WinOF\WIX\wlh\x64 & nmake\r
144         Results in a WOF_wlh_x64.msi installer image.\r
145 \r
146 cd gen1\trunk\WinOF\WIX\wlh\ia64 & nmake\r
147         Results in a WOF_wlh_ia64.msi installer image.\r
148 \r
149 \r
150 DEBUG Installation\r
151 ------------------\r
152 Create a log file for a given .msi installation:\r
153 \r
154   msiexec /I "WOF_x86.msi" /Lv \temp\msi.log\r
155 \r
156   Also see %windir%\inf\setupapi.dev.log on Svr08 & Vista for driver load\r
157   logging.\r
158 \r
159 Command line way to set an interface's IP address, netmask, no gateway:\r
160 \r
161   netsh interface ip set \\r
162          address "Local Area Connection 3" static\r
163   netsh interface ip show address "Local Area Connection 3"\r
164 \r
165 \r