Commit | Line | Data |
---|---|---|
805e021f CE |
1 | This software has been released under the terms of the IBM Public |
2 | License. For details, see the LICENSE file in the top-level source | |
3 | directory or on-line at http://www.openafs.org/dl/license10.html | |
4 | ||
5 | The document now provides a step by step procedure that takes the user | |
6 | from a basic Windows 2000/XP/2003/Vista/2008/Win7 workstation to an OpenAFS | |
7 | development environment. Details are provided so that a 'beginning' | |
8 | windows developer can build an OpenAFS installable package for Windows | |
9 | 2000/XP/2003/Vista/2008/Win7. | |
10 | ||
11 | NOTE 1: | |
12 | As of the OpenAFS 1.3 release series, Windows platforms released | |
13 | prior to Windows 2000 are no longer supported. As of the OpenAFS 1.5 | |
14 | series, the Windows 9x components are being removed from the source tree. | |
15 | ||
16 | ||
17 | ****** Windows XP/2003/Vista/2008/Win7/2008-R2 Build Process ****** | |
18 | ||
19 | Building OpenAFS for Windows requires configuring a Windows | |
20 | development system by installing compilation tools and header files. | |
21 | OpenAFS Software development can be done on XP, 2003, Vista, Win7, | |
22 | or 2008 system. The target system, where OpenAFS will be installed, | |
23 | can be one of: | |
24 | ||
25 | * Windows XP | |
26 | * Windows XP SP2 | |
27 | * Windows 2003 | |
28 | * Windows 2003 SP1 | |
29 | * Windows XP 64 | |
30 | * Windows 2003 64 | |
31 | * Windows 2003 R2 (32 or 64) | |
32 | * Windows Vista (32 or 64) | |
33 | * Windows 2008 (64) | |
34 | * Windows 7 (32 or 64) | |
35 | * Windows 2008 R2 (64) | |
36 | ||
37 | The build process is controlled by a nmake file that generates the | |
38 | necessary binaries and binds them into an install package. | |
39 | ||
40 | The following steps describe how to configure the development environment: | |
41 | ||
42 | A. Obtain a copy of the OpenAFS Source Tree | |
43 | B. Install Compiler and Development tools. | |
44 | C. Install SDK header files | |
45 | D. Configure NTBUILD.BAT | |
46 | E. Set program version Level | |
47 | F. Build the binaries | |
48 | I. Install Wix 2.0.5805 | |
49 | J. Build Wix MSI Install Package | |
50 | K. Final Results | |
51 | L. Optional Items | |
52 | ||
53 | The Microsoft development tools require anywhere from 660 MB to 1.8GB | |
54 | of storage depending on which compilers are selected. The following | |
55 | versions are supported: | |
56 | ||
57 | Microsoft Visual Studio .NET 2005 | |
58 | available via a MSDN subscription | |
59 | (used for OpenAFS.org distribution) | |
60 | Visual Studio 2005 SP1 is required to use Win7 as a development environment | |
61 | ||
62 | Microsoft Visual Studio 2008 | |
63 | available via a MSDN subscription | |
64 | ||
65 | Under some conditions, a conflict between Windows SDK headers and Windows DDK | |
66 | headers causes difficulties using Visual Studio 2008 as a development | |
67 | environment. Visual Studio 2005 does not suffer from this issue. | |
68 | ||
69 | One of the following Microsoft SDKs is required: | |
70 | ||
71 | Microsoft SDK for Windows 6.1 | |
72 | Microsoft SDK for Windows 7.0 | |
73 | ||
74 | One of the following Microsoft DDK/WDK is required: | |
75 | ||
76 | Microsoft Windows Driver Kit 7600 | |
77 | ||
78 | NOTE: Not all combinations of Visual Studio, SDK, and DDK/WDK are | |
79 | known to work. OpenAFS for Windows is packaged by Secure Endpoints Inc. | |
80 | using the following configurations: | |
81 | ||
82 | 32-bit Packages: | |
83 | Built on Windows 7 | |
84 | Visual Studio 2008 | |
85 | Windows [Platform] SDK 6.0a | |
86 | Windows DDK 7600 | |
87 | Target: i386_w2k | |
88 | APPVER: 5.0 | |
89 | ||
90 | 64-bit Packages: | |
91 | Built on Windows 7 | |
92 | Visual Studio 2008 | |
93 | Windows [Platform] SDK 6.0a | |
94 | Windows DDK 7600 | |
95 | Target: amd64_w2k | |
96 | APPVER: 5.02 | |
97 | ||
98 | The Microsoft HTML Help Workshop is required: | |
99 | ||
100 | http://www.microsoft.com/downloads/details.aspx?familyid=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en | |
101 | ||
102 | The Microsoft Internationalized Domain Names (IDN) Mitigation APIs 1.1 is required: | |
103 | ||
104 | http://www.microsoft.com/en-us/download/details.aspx?id=734 | |
105 | ||
106 | ActiveState Perl 5.10 is required for man-page generation | |
107 | ||
108 | http://www.activestate.com/activeperl/ | |
109 | ||
110 | Cygwin is required for Docbook to HTML and Docbook to HTMLHelp conversion | |
111 | ||
112 | http://cygwin.com/setup.exe | |
113 | ||
114 | Doxygen is required for Developer Documentation generation | |
115 | ||
116 | http://www.stack.nl/~dimitri/doxygen/ | |
117 | ||
118 | The WiX installer requires about 18 MB of storage. The following | |
119 | version is supported: | |
120 | ||
121 | WiX 2.0.5805.0 | |
122 | http://wix.codeplex.com/releases/view/44405 | |
123 | ||
124 | Newer versions of WiX (e.g., the 3.x series) are not supported. | |
125 | ||
126 | The OpenAFS Source directory requires about 360 MB storage. The Source | |
127 | directory size includes additional space for files that will be | |
128 | generated during the build process. A full build of Free and Checked | |
129 | installers on 64-bit Windows will require up to 1GB of storage. | |
130 | ||
131 | ||
132 | STEP A. Obtain a copy of the Open AFS Source Tree. | |
133 | ||
134 | Transfer OpenAFS source tree onto your hardrive. The source can be | |
135 | downloaded from the OpenAFS web site: | |
136 | http://www.OpenAFS.org/release/snapindex.html. | |
137 | ||
138 | For this example, download source for version 1.7.25 using the | |
139 | following URL: | |
140 | http://www.openafs.org/dl/openafs/1.7.25/openafs-1.7.25-src.tar | |
141 | http://www.openafs.org/dl/openafs/1.7.25/openafs-1.7.25-doc.tar | |
142 | ||
143 | HINT: DailySnapShots are pre-release source trees and much more | |
144 | likely to have compilation errors. If this is your first attempt, do | |
145 | your build based on a release version of the source, e.g. 1.7.25. Once | |
146 | you have completed a build process successfully, you can experiment with | |
147 | other source trees. | |
148 | ||
149 | You will need an unzip utility that can expand compressed tar files. | |
150 | For example "Pkzip for Windows" from Pkware will uncompress tar files. | |
151 | (http://www.pkware.com/) | |
152 | ||
153 | Expand the downloaded tar files into target directory (c:\OpenAFS), | |
154 | the unzip routine will expand the source into a subdirectory tree: | |
155 | c:\OpenAFS\OpenAFS-1.7.25\ | |
156 | ||
157 | Copy the file 'ntbuild.bat' from the 'src' subdirectory to the OpenAFS | |
158 | base directory (aka %AFSROOT%): | |
159 | ||
160 | From a DOS command prompt window, enter the following copy commands: | |
161 | ||
162 | cd c:\OpenAFS\OpenAFS-1.7.25 | |
163 | copy src\ntbuild.bat . | |
164 | ||
165 | The OpenAFS base directory should look something like the following: | |
166 | ||
167 | c:\OpenAFS\OpenAFS-1.7.25\ | |
168 | NTMakefile | |
169 | ntbuild.bat | |
170 | src | |
171 | doc | |
172 | ||
173 | STEP B. Install compiler and development tools. | |
174 | ||
175 | Install a copy of Microsoft Visual Studio .NET 2005. Visual Studio 2008 | |
176 | can be used to produce builds but the resulting binaries cannot be used | |
177 | on Windows 2000. | |
178 | ||
179 | (1) You can reduce the installation size by selecting "Custom" install | |
180 | and remove all but the following Options: | |
181 | ||
182 | Microsoft Visual C++ | |
183 | Data Access | |
184 | ||
185 | (2) When asked, Select to Register Environment Variables. | |
186 | ||
187 | ||
188 | STEP C. Install SDK header files. | |
189 | ||
190 | Files from Microsoft's Platform SDK for Windows Server 2003 SP1 are | |
191 | required to complete a build on Windows 2000/XP/2003. At a minimum the | |
192 | following components are known to be required: | |
193 | ||
194 | * Core | |
195 | * Data Access | |
196 | * Installer | |
197 | * Windows Management Instrumentation | |
198 | * Web Workshop (IE) | |
199 | ||
200 | It is advised that you install the entire SDK. The SDK can be obtained | |
201 | from: | |
202 | ||
203 | http://www.microsoft.com/en-us/download/details.aspx?id=6510 | |
204 | ||
205 | The header files that are required from a Microsoft SDK/WDK are: | |
206 | ||
207 | npapi.h (Windows 2000,XP,2003 builds) | |
208 | netcfgx.h (NSIS Loopback Adapter installer - Windows 2000,XP,2003 builds) | |
209 | netcfgn.h (NSIS Loopback Adapter installer - Windows 2000,XP,2003 builds) | |
210 | normalization.h (AFS Cache Manager) | |
211 | ||
212 | These files come from the following Microsoft DDKs/SDKs: | |
213 | ||
214 | npapi.h: | |
215 | Windows XP SP2 Platform SDK - include/ | |
216 | ||
217 | netcfgn.h, netcfgx.h: | |
218 | Windows XP/2003 DDK - inc/wxp/ | |
219 | ||
220 | normalization.h: | |
221 | Microsoft IDN Mitigation APIs 1.1 - include/ | |
222 | ||
223 | The Windows DDK can be obtained from: | |
224 | ||
225 | http://www.microsoft.com/en-us/download/details.aspx?id=11800 | |
226 | ||
227 | STEP D. Configure NTBUILD.BAT. | |
228 | ||
229 | The NTBUILD.BAT file copied to the OpenAFS base directory must be | |
230 | customized for use on your development system. The provided NTBUILD.BAT | |
231 | was developed for use with Visual Studio 2005 and the Windows Server 2008 | |
232 | Platform SDK. It requires significant modification to construct a build | |
233 | environment, due to differences between systems. | |
234 | ||
235 | The following variables must be defined to match your configuration: | |
236 | ||
237 | AFSVER_CL: Set to 1200 if using MS Visual C++ 6.0 | |
238 | Set to 1300 if using MS Visual Studio .NET | |
239 | Set to 1310 if using MS Visual Studio .NET 2003 | |
240 | Set to 1400 if using MS Visual Studio .NET 2005 | |
241 | Set to 1500 if using MS Visual Studio 2008 | |
242 | Set to 1600 if using MS Visual Studio 2010 | |
243 | Set to 1700 if using MS Visual Studio 2012 | |
244 | ||
245 | MSVCDIR: Set to the short name version of the directory into which | |
246 | the visual C++ compiler was installed regardless of version | |
247 | ||
248 | MSVCDIR64: On AMD64 systems, set to the 64-bit visual C++ compiler | |
249 | ||
250 | MSSDKDIR: Set to the short name of the directory into which | |
251 | the Platform SDK was installed | |
252 | ||
253 | NTDDKDIR: Set to the short name of the INC\WNET DDK directory | |
254 | ||
255 | NTDDKDIR2: Set to the short name of the INC\CRT DDK directory | |
256 | ||
257 | MSIDNNLS: Set the the name of the Microsoft IDN Mitigation APIs 1.1 | |
258 | directory | |
259 | ||
260 | AFSROOT: Set to the short name of the OpenAFS Base directory. This | |
261 | cannot be set to a UNC path. | |
262 | ||
263 | SYS_NAME: One of "i386_w2k" or "amd64_w2k" | |
264 | ||
265 | APPVER: 5.0 for Windows 2000 and above; 5.1 for AMD64 systems | |
266 | ||
267 | _WIN32_IE: 0x500 for Windows 2000 and above; 0x502 for AMD64 systems | |
268 | ||
269 | CODESIGN_DESC: Product Name | |
270 | ||
271 | CODESIGN_TIMESTAMP: Time Stamp Service for Code Signing Certificate | |
272 | ||
273 | CODESIGN_URL: Support URL Displayed to End Users | |
274 | ||
275 | CODESIGN_CROSS_CERT: Path to Microsoft Cross Signing Certificate | |
276 | (if you have one) | |
277 | ||
278 | If no code signing tools are available, the resulting driver will not be | |
279 | usable on 64-bit Vista and Win7 and newer systems, unless the system is | |
280 | booted with the disable signing checks option from the F8 menu. | |
281 | ||
282 | ||
283 | STEP E. Set version and installation options (optional) | |
284 | ||
285 | Add a CellServDB file to install area. CellServDB contains the entries | |
286 | for the various cell names. You can download a general purpose one | |
287 | from: | |
288 | http://grand.central.org/dl/cellservdb/CellServDB | |
289 | then copy it to %AFSROOT%\src\WINNT\install\NSIS and name it afsdcell.ini | |
290 | ||
291 | Edit file %AFSROOT%\src\config\NTMakefile.i386_w2k or NTMakefile.amd64_w2k | |
292 | as appropriate: | |
293 | ||
294 | AFSPRODUCT_VER_MAJOR - Version Major Number | |
295 | AFSPRODUCT_VER_MINOR - Version Minor Number | |
296 | AFSPRODUCT_VER_PATCH - Version Patch Number | |
297 | AFSPRODUCT_VER_BUILD - Version Build Number | |
298 | CELLSERVDB_INSTALL - The default file name for the CellServDB | |
299 | included in the install Package. | |
300 | CELLNAME_DEFAULT - The default home cell name. | |
301 | CELLSERVDB_WEB - The default web address to obtain CellServDB | |
302 | ||
303 | For example: in the file %AFSROOT%\src\config\NTMakefile.i386_w2k you would | |
304 | see the following: | |
305 | ||
306 | AFSPRODUCT_VER_MAJOR=1 | |
307 | AFSPRODUCT_VER_MINOR=7 | |
308 | AFSPRODUCT_VER_PATCH=2500 | |
309 | AFSPRODUCT_VER_BUILD=0 | |
310 | CELLNAME_DEFAULT=openafs.org | |
311 | CELLSERVDB_INSTALL=CellServDB.GrandCentral | |
312 | CELLSERVDB_WEB=http://grand.central.org/dl/cellservdb/CellServDB | |
313 | ||
314 | During the OpenAFS installation process the user will be presented | |
315 | with two choices for the CellServDB: Local copy (CELLSERVDB_INSTALL) and | |
316 | one that can be downloaded from the web (CELLSERVDB_WEB). | |
317 | ||
318 | IMPORTANT: When building your own binaries, you must set the AFSPRODUCT_VER_BUILD | |
319 | value to a number greater than 1023. All values 0 to 1023 are reserved for use | |
320 | by official OpenAFS.org releases. A failure to do so will result in Windows | |
321 | Crash Reports for your binaries being delivered to OpenAFS.org for analysis. | |
322 | ||
323 | ||
324 | STEP F. Begin the build | |
325 | ||
326 | (1) Open a Command Prompt window (cmd.exe) | |
327 | ||
328 | Enable delayed variable expansion with "cmd /v" | |
329 | ||
330 | (2) Change to the %AFSROOT% directory | |
331 | ||
332 | (3) Configure the environment variables: | |
333 | ||
334 | For a release build (SMB version): | |
335 | ||
336 | (a) Execute the VCVARS32.BAT or VSVARS32.BAT file which part of the | |
337 | Visual Studio environment you installed. | |
338 | ||
339 | (b) Execute the SETENV.CMD file from the Windows SDK with the parameters | |
340 | "/2000 /RETAIL" | |
341 | ||
342 | (c) Execute the NTBUILD.BAT file with the parameter "free" | |
343 | ||
344 | For a debug build (SMB version): | |
345 | ||
346 | (a) Execute the VCVARS32.BAT or VSVARS32.BAT file which part of the | |
347 | Visual Studio environment you installed. | |
348 | ||
349 | (b) Execute the SETENV.CMD file from the Windows SDK with the parameters | |
350 | "/2000 /DEBUG" | |
351 | ||
352 | (c) Execute the NTBUILD.BAT file with the parameter "checked" | |
353 | ||
354 | (4) Build the complete Windows 2000/XP/2003 development environment. | |
355 | ||
356 | nmake /f NTMakefile install | |
357 | ||
358 | While the build is running you will see many compile warnings. This | |
359 | behavior is normal; the build process is successful as long as the build | |
360 | process doesn't terminate with an error ("nmake.exe return code 0x2") | |
361 | and it displays 'Build Finished Successfully'. Note that although the | |
362 | the build target is "install", it does not install OpenAFS. | |
363 | ||
364 | (5) Before rebuilding you must clean the work area: | |
365 | ||
366 | nmake /f NTMakefile clean | |
367 | ||
368 | ||
369 | STEP G. NSIS is no longer used, it does not support 64-bit systems | |
370 | ||
371 | STEP I. Install Wix MSI Installer | |
372 | ||
373 | Download the WiX 2.0.5805.0 binaries from | |
374 | ||
375 | http://wix.codeplex.com/releases/view/44405 | |
376 | ||
377 | STEP J. Build Wix MSI install package | |
378 | ||
379 | From the %AFSROOT% directory execute: | |
380 | ||
381 | nmake /f NTMakefile wix | |
382 | ||
383 | Make sure the binaries installed to \src\wix\release\ship are | |
384 | available in the PATH environment variable | |
385 | ||
386 | ||
387 | STEP K. Final Results | |
388 | ||
389 | The build process generates its binaries in %AFSROOT%\DEST. The subdirectory | |
390 | would look like the following: | |
391 | ||
392 | %AFSROOT%\DEST\{checked,free}\ | |
393 | bin | |
394 | etc | |
395 | include | |
396 | lib | |
397 | root.client | |
398 | root.server | |
399 | WinInstall | |
400 | ||
401 | Bin - contains build utilities. | |
402 | root.client - contains Open AFS binaries | |
403 | root.server - contain Open AFS Server binaries | |
404 | WinInstall\OpenAFSforWindows.exe - is the NSIS install package | |
405 | WinInstall\openafs-en_US.msi - is the WiX MSI install package | |
406 | ||
407 | ||
408 | STEP L. Optional Items | |
409 | ||
410 | The build process has an error table that is compiled for many OpenAFS | |
411 | applications. This table is generated by Unix based tools. It is not | |
412 | normally necessary to modify this table so pre-generated source files | |
413 | are included in the OpenAFS source. If you need to make modifications | |
414 | in these areas the Unix base tools that run on Windows can be found on | |
415 | the web. For example: | |
416 | ||
417 | http://cygwin.com/ | |
418 | ||
419 | Below is a short explanation how to update the error table. | |
420 | ||
421 | (1) Install flex and bison from a Unix based tool provider. | |
422 | ||
423 | (2) Make changes to the source files. | |
424 | ||
425 | There are two files in the source tree that are processed with lex | |
426 | and yacc on UNIX systems, src/comerr/et_lex.lex.l and | |
427 | src/comerr/error_table.y, that when processed produce the files | |
428 | et_lex.lex_nt.c, error_table_nt.c, and error_table_nt.h. | |
429 | ||
430 | Since NT does not include lex and yacc or any equivalent tools, we | |
431 | have provided the output files that lex and yacc produce (using Win32 | |
432 | ports of flex and bison). This will allow builds to work for anyone | |
433 | who does not need to change the .l and .y files. | |
434 | ||
435 | If you do need to change et_lex.lex.l, then you will need to install | |
436 | Win32 port of flex on your system. Put flex.exe in a directory on the | |
437 | path and rebuild. | |
438 | ||
439 | If you do need to change error_table.y, then you will need to install | |
440 | a Win32 port of bison on your system. Put bison.exe in a directory on | |
441 | the path, configure bison as explained in step 5, and rebuild. | |
442 | ||
443 | You can also attempt to use other replacements for lex and yacc. This | |
444 | will require modifying the LEX and YACC settings in | |
445 | /config/NTMakefile.i386_nt40. If the replacements require different | |
446 | command line options than flex and bison, then you may also need to | |
447 | change src/comerr/NTMakefile. | |
448 | ||
449 | (3) Generate new OpenAFS binaries |