window-afsifs-20050617
[openafs.git] / README-NT
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 workstation to an OpenAFS development 
7 environment.   Details are provided so that a 'beginning' windows 
8 developer can build an OpenAFS installable package for Windows 2000/XP/2003.
9
10 NOTE:
11 As of the OpenAFS 1.3 release series, Windows platforms released
12 prior to Windows 2000 are not being supported.  The InstallShield
13 installer is still in the source tree but is no longer supported.
14 A new open source installer based on NSIS 2.0 replaces it.
15
16 NOTE:
17 In this release, there are two clients offered: an SMB version (as was
18 included in all previous versions), and an IFS version (newly released).
19 To build the IFS version, follow the directions below, but note that
20 only the NSIS installer script can be correctly configured; the Wix
21 installer will not work correctly.  Also, the kernel module associated
22 with the IFS version must be built separately, using the IFS kit or DDK
23 build environment.  While in the DDK build environment, enter into the
24 afsrdr source directory, and execute 'build'.  This will create the
25 module to be packaged by the installer.
26
27
28 ***********   Windows 2000/XP/2003 Build Process ****************
29
30 Building OpenAFS for Windows requires configuring a Windows
31 development system by installing compilation tools and header files.
32 Open AFS Software development can be done on Windows 2000 or XP.  The
33 target system, where OpenAFS will be installed, should be either
34 Windows 2000, Windows XP, or Windows 2003.  The building process is 
35 controlled by a nmake file that generates the necessary binaries and 
36 binds them into an install package.
37
38 The following steps describe how to configure Windows 2000/XP:
39
40    A. Obtain a copy of the OpenAFS Source Tree
41    B. Install Compiler and Development tools.
42    C. Install SDK header files
43    D. Configure NTBUILD.BAT
44    E. Set program version Level
45    F. Build Win2000 binaries
46    G. Install NSIS 2.0
47    H. Build NSIS Install Package
48    I. Install Wix 2.0
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 
58       available via a MSDN subscription
59
60     Microsoft Visual Studio .NET 2003 (recommended)
61       available via a MSDN subscription
62
63     Microsoft Visual Studio .NET 2005 (do not use for production)
64       available via a MSDN subscription
65
66 The following Microsoft SDK is required:
67
68     Microsoft Platform SDK for Windows XP SP2 [Core, Data Access and Installer SDKs are required]
69       http://www.microsoft.com/msdownload/platformsdk/sdkupdate/downlevel.htm [IE required]
70       http://www.microsoft.com/msdownload/platformsdk/sdkupdate/XPSP2FULLInstall.htm
71
72 The following Microsoft DDK is required:
73
74     Microsoft Windows Server 2003 SP1 DDK
75       available via a MSDN subscription or via free CD
76       http://www.microsoft.com/whdc/devtools/ddk/orderddkcd.mspx
77
78 The NSIS installer requires about 14 MB of storage. The following 
79 version is supported:
80
81     Nullsoft Scriptable Installation System 2.0 
82       http://nsis.sourceforge.net/home/
83
84 The WiX installer requires about 18 MB of storage.  The following 
85 version is supported:
86
87     Wix 2.0.2217.0
88       http://prdownloads.sourceforge.net/wix/sources-2.0.2217.0.zip
89
90 The InstallShield scripts (although not supported) require version 5.5
91 of InstallShiled. Version 6.0 or higher of InstallShield are not 
92 compatible.
93
94 The OpenAFS Source directory requires about 360 MB storage. The Source
95 directory size includes additional space for files that will be
96 generated during the build process.
97
98
99 STEP A. Obtain a copy of the Open AFS Source Tree.
100
101 Transfer OpenAFS source tree onto your hardrive.  The source can be
102 downloaded from the OpenAFS web site:
103         http://www.OpenAFS.org/release/snapindex.html.
104
105 For this example, download source for version 1.3.74 using the
106 following URL:
107 http://www.openafs.org/dl/openafs/1.3.74/openafs-1.3.74-src.tar
108
109 HINT: DailySnapShots are pre-release source trees and much more
110 likely to have compilation errors. If this is your first attempt, do
111 your build based on a release version of the source, e.g. 1.3.74. Once
112 you have completed a build process successfully, you can experiment with
113 other source trees.
114
115 You will need an unzip utility that can expand compressed tar files.
116 For example "Pkzip for Windows" from Pkware will uncompress tar files.
117 (http://www.pkware.com/)
118
119 Expand the downloaded tar file (openafs-1.3.74-src.tar) into target
120 directory (c:\OpenAFS), the unzip routine will expand the source into a
121 subdirectory tree:
122     c:\OpenAFS\OpenAFS-1.3.74\src
123
124 Copy the files 'NTMakefile' and 'ntbuild.bat' from 'src' to the OpenAFS 
125 base directory (aka %AFSROOT%):
126
127   From a DOS command prompt window, enter the following copy commands:
128
129     cd c:\OpenAFS\OpenAFS-1.3.74
130     copy src\NTMakefile .
131     copy src\ntbuild.bat .
132
133
134 The AFS base directory should look something like the following:
135
136   c:\OpenAFS\OpenAFS-1.3.74\
137     NTMakefile
138     ntbuild.bat
139     src
140           
141
142 STEP B. Install compiler and development tools.
143
144 Install a copy of Microsoft Visual Studio .NET, Visual Studio .NET 2003, 
145 or Visual Studio .NET 2005.  The "Typical" install setting is sufficient.
146
147 (1) You can reduce the installation size by selecting "Custom" install
148 and remove all but the following Options:
149
150         Microsoft Visual C++
151         Data Access
152
153 (2) When asked, Select to Register Environment Variables.
154
155
156 STEP C. Install SDK header files.
157
158 Files from Microsoft's Platform SDK for Windows XP SP2 is required to
159 complete a build on Windows 2000/XP/2003.   You can install the "Core, Data
160 Access and Installer SDKs" from
161
162   http://www.microsoft.com/msdownload/platformsdk/sdkupdate/
163
164 by using Internet Explorer 5.x or higher.  (Active X controls are required)
165 If you do not which to use IE a complete SDK package is available from
166
167   http://www.microsoft.com/msdownload/platformsdk/sdkupdate/XPSP2FULLInstall.htm
168
169 The header files that are required are found from a Microsoft SDK are:
170
171    npapi.h    (Windows 2000,XP,2003 builds)
172    netcfgx.h  (NSIS Loopback Adapter installer - Windows 2000,XP,2003 builds)
173    netcfgn.h  (NSIS Loopback Adapter installer - Windows 2000,XP,2003 builds)
174
175 These files come from the following Microsoft DDKs/SDKs:
176
177    npapi.h:
178         Windows XP SP2 Platform SDK - include/
179
180    netcfgn.h, netcfgx.h:
181         Windows XP/2003 DDK - inc/wxp/
182
183 If you are interested in experimenting with the IFS you must purchase from
184 Microsoft a copy of the Windows 2003 SP1 IFS Kit.
185
186   http://www.microsoft.com/whdc/devtools/ifskit/default.mspx
187
188
189 STEP D. Configure NTBUILD.BAT.
190
191 The NTBUILD.BAT file copied to the OpenAFS base directory must be 
192 customized for use on your development system.  The following variables
193 must be defined to match your configuration:
194
195   AFSVER_CL: Set to 1200 if using MS Visual C++ 6.0
196              Set to 1300 if using MS Visual Studio .NET
197              Set to 1310 if using MS Visual Studio .NET 2003
198              Set to 1400 if using MS Visual Studio .NET 2005
199
200   MSVCDIR: Set to the short name version of the directory into which
201            the visual C++ compiler was installed regardless of version
202
203   MSSDKDIR: Set to the short name of the directory into which
204             the Platform SDK was installed
205
206   NTDDKDIR: Set the short name of the directory containing the npapi.h file
207
208   AFSROOT: Set to the short name of the OpenAFS Base directory.  This
209            cannot be set to a UNC path.
210
211
212 STEP E. Set version and installation options (optional)
213
214 Add a CellServDB file to install area. CellServDB contains the entries
215 for the various cell names.  You can download a general purpose one
216 from:
217         http://grand.central.org/dl/cellservdb/CellServDB
218 then copy it to %AFSROOT%\src\WINNT\install\NSIS and name it afsdcell.ini
219
220 Edit file %AFSROOT%\src\config\NTMakefile.i386_w2k
221     AFSPRODUCT_VER_MAJOR - Version Major Number
222     AFSPRODUCT_VER_MINOR - Version Minor Number
223     AFSPRODUCT_VER_PATCH - Version Patch Number
224     AFSPRODUCT_VER_BUILD - Version Build Number
225     CELLSERVDB_INSTALL   - The default file name for the CellServDB
226                            included in the install Package.
227     CELLNAME_DEFAULT     - The default home cell name.
228     CELLSERVDB_WEB       - The default web address to obtain CellServDB
229
230 For example: in the file %AFSROOT%\src\config\NTMakefile.i386_nt40 you would
231 see the following:
232
233    AFSPRODUCT_VER_MAJOR=1
234    AFSPRODUCT_VER_MINOR=3
235    AFSPRODUCT_VER_PATCH=7400
236    AFSPRODUCT_VER_BUILD=0
237    CELLNAME_DEFAULT=openafs.org
238    CELLSERVDB_INSTALL=CellServDB.GrandCentral
239    CELLSERVDB_WEB=http://grand.central.org/dl/cellservdb/CellServDB
240
241 During the Open AFS installation process the user will be presented
242 with two choices for the CellServDB: Local copy (CELLSERVDB_INSTALL) and
243 one that can be downloaded from the web (CELLSERVDB_WEB).
244
245 STEP F. Begin the build
246
247 (1) From Windows 2000/XP/2003 open up a DOS prompt window.
248
249 (2) Change to the %AFSROOT% directory
250
251 (3) Configure the environment variables:
252
253     For a release build (SMB version):
254
255     (a) Execute the VCVARS32.BAT or VSVARS32.BAT file which part of the
256         Visual Studio environment you installed.
257
258     (b) Execute the SETENV.BAT file with the parameters "/2000 /RETAIL"
259
260     (c) Execute the NTBUILD.BAT file with the parameter "free"
261
262     For a release build (IFS version):
263
264     (a) Execute the VCVARS32.BAT or VSVARS32.BAT file which part of the
265         Visual Studio environment you installed.
266
267     (b) Execute the SETENV.BAT file with the parameters "/2000 /RETAIL"
268
269     (c) Execute the NTBUILD.BAT file with the parameter "free ifs"
270
271     For a debug build (SMB version):
272
273     (a) Execute the VCVARS32.BAT or VSVARS32.BAT file which part of the
274         Visual Studio environment you installed.
275
276     (b) Execute the SETENV.BAT file with the parameters "/2000 /DEBUG"
277
278     (c) Execute the NTBUILD.BAT file with the parameter "checked"
279
280     For a debug build (IFS version):
281
282     (a) Execute the VCVARS32.BAT or VSVARS32.BAT file which part of the
283         Visual Studio environment you installed.
284
285     (b) Execute the SETENV.BAT file with the parameters "/2000 /DEBUG"
286
287     (c) Execute the NTBUILD.BAT file with the parameter "checked ifs"
288
289 (4) Clean the work area:
290
291     nmake /f NTMakefile clean
292
293 (5) Build the complete Windows 2000/XP/2003 development environment.
294
295     nmake /f NTMakefile install
296
297 While the build is running you will see many compile warnings. This
298 behavior is normal; the build process is successful as long as the build
299 process doesn't terminate with an error ("nmake.exe return code 0x2")
300 and it displays 'Build Finished Successfully'.
301
302 (6) [IFS only] Open a DDK/IFS Build Environment command window, change 
303     to the src\WINNT\afsrdr directory, and execute the "build" command.
304
305
306 STEP G. Install NSIS 2.0 (optional).
307
308 Download the Nullsoft Scriptable Installation System (NSIS) 2.0 from
309
310     http://nsis.sourceforge.net/home/
311
312 Run the nsis20.exe installer.
313
314 NOTE: The NSIS installer may be rebuilt from source files 
315    
316     C:\Program Files\NSIS\Source
317
318 to enable options not built into the default configuration.  The 
319 OpenAFS installers are built using a modified version of the NSIS
320 sources.  The following changes were made to exehead\config.h.
321
322     NSIS_MAX_STRLEN set to 4096
323     NSIS_CONFIG_LOG defined
324     NSIS_CONFIG_LOG_ODS defined
325     
326
327 STEP H.  Build OpenAFS NSIS install package
328
329 From the %AFSROOT% directory execute:
330
331     nmake /f NTMakefile NSIS
332
333
334 STEP I.  Install Wix MSI Installer
335
336 Download the Wix 2.0.2217.0 installer from 
337
338     http://prdownloads.sourceforge.net/wix/sources-2.0.2217.0.zip
339
340 Apply the following patches to the source tree and execute 
341
342     make ship
343
344 from the \src\wix directory.  
345
346 Index: src/wix/Common.cs
347 ===================================================================
348 RCS file: /cvsroot/wix/wix/src/wix/Common.cs,v
349 retrieving revision 1.7
350 diff -w -r1.7 Common.cs
351 140a141,146
352 >               public static long GetFileTimeFromDateTime(string dateTime) 
353 >               {
354 >                       System.DateTime sdt = System.Xml.XmlConvert.ToDateTime(dateTime);
355 >                       return sdt.ToFileTime();
356 >               }
357
358 Index: src/wix/Compiler.cs
359 ===================================================================
360 RCS file: /cvsroot/wix/wix/src/wix/Compiler.cs,v
361 retrieving revision 1.14
362 diff -w -r1.14 Compiler.cs
363 847c847
364 <                     this.AddRegistryKey(sourceLineNumbers, null, MsiInterop.MsidbRegistryRootClassesRoot, String.Concat("CLSID\\", classId, "\\", context[i]), String.Empty, String.Concat("\"[!", fileServer, "]", argument == null ? String.Empty : " ", argument, "\""), componentId); // ClassId context
365 ---
366 >                     this.AddRegistryKey(sourceLineNumbers, null, MsiInterop.MsidbRegistryRootClassesRoot, String.Concat("CLSID\\", classId, "\\", context[i]), String.Empty, String.Concat("\"[#", fileServer, "]", argument == null ? String.Empty : " ", argument, "\""), componentId); // ClassId context
367 2352a2353,2358
368 >                       // if a Value attribute was given by itself, make this a type 19 custom action
369 >                       if( sourceBits == 0 && targetBits == MsiInterop.MsidbCustomActionTypeTextData ) 
370 >                       {
371 >                               sourceBits = MsiInterop.MsidbCustomActionTypeSourceFile;
372 >                       }
373
374 3881c3887
375 <                         minDate = attrib.Value;
376 ---
377 >                         minDate = Common.GetFileTimeFromDateTime( attrib.Value ).ToString();
378 3884c3890
379 <                         maxDate = attrib.Value;
380 ---
381 >                         maxDate = Common.GetFileTimeFromDateTime( attrib.Value ).ToString();
382 8187a8194,8207
383 >                                       case "Delete":
384 >                                               switch (attrib.Value)
385 >                                               {
386 >                                                       case "install":
387 >                                                               events |= MsiInterop.MsidbServiceControlEventDelete;
388 >                                                               break;
389 >                                                       case "uninstall":
390 >                                                               events |= MsiInterop.MsidbServiceControlEventUninstallDelete;
391 >                                                               break;
392 >                                                       case "both":
393 >                                                               events |= MsiInterop.MsidbServiceControlEventDelete | MsiInterop.MsidbServiceControlEventUninstallDelete;
394 >                                                               break;
395 >                                               }
396 >                                               break;
397 9685a9706
398
399 Index: src/wix/Preprocessor.cs
400 ===================================================================
401 RCS file: /cvsroot/wix/wix/src/wix/Preprocessor.cs,v
402 retrieving revision 1.6
403 diff -w -r1.6 Preprocessor.cs
404 274c274
405 <                             context = new IfContext(context.IsTrue & context.Active, this.variables.ContainsKey(reader.Value.Trim()), IfState.If);
406 ---
407 >                             context = new IfContext(context.IsTrue & context.Active, this.IsDefined(reader.Value.Trim()), IfState.If);
408 279c279
409 <                             context = new IfContext(context.IsTrue & context.Active, !this.variables.ContainsKey(reader.Value.Trim()), IfState.If);
410 ---
411 >                             context = new IfContext(context.IsTrue & context.Active, !this.IsDefined(reader.Value.Trim()), IfState.If);
412 360a361,362
413 >                                               case "error":
414 >                                                       throw new WixPreprocessorException(this.GetCurrentSourceLineNumbers(), this.PreprocessVariables(reader.Value));
415 419a422,437
416 >               /// Returns true if the symbol exists.
417 >               /// </summary>
418 >               /// <param name="symbol">symbol name to check</param>
419 >               /// <returns>true if symbol is defined</returns>
420 >               private bool IsDefined(string symbol)
421 >               {
422 >                       if( symbol.StartsWith("env.") )
423 >                               return Environment.GetEnvironmentVariable(symbol.Substring(4)) != null;
424 >                       if( symbol.StartsWith("var.") )
425 >                               return this.variables.ContainsKey(symbol.Substring(4));
426 >                       if( symbol.StartsWith("sys.") )
427 >                               return this.systemVariables.ContainsKey(symbol.Substring(4));
428 >                       return this.variables.ContainsKey(symbol);
429 >               }
430
431 >         /// <summary>
432 Index: src/wix/wix.csproj
433 ===================================================================
434 RCS file: /cvsroot/wix/wix/src/wix/wix.csproj,v
435 retrieving revision 1.4
436 diff -w -r1.4 wix.csproj
437 661a662,666
438 >                     RelPath = "Xsd\wix.xsx"
439 >                     DependentUpon = "wix.xsd"
440 >                     BuildAction = "None"
441 >                 />
442 >                 <File
443 664a670,674
444 >                 <File
445 >                     RelPath = "Xsd\wixloc.xsx"
446 >                     DependentUpon = "wixloc.xsd"
447 >                     BuildAction = "None"
448 >                 />
449
450
451 STEP J.  Build Wix MSI install package
452
453 From the %AFSROOT% directory execute:
454
455     nmake /f NTMakefile wix
456
457 Make sure the binaries installed to \src\wix\release\ship are
458 available in the PATH environment variable
459
460
461 STEP K. Final Results
462
463 The build process generates its binaries in %AFSROOT%\DEST. The subdirectory
464 would look like the following:
465
466 %AFSROOT%\DEST\{checked,free}\
467         bin
468         etc
469         include
470         lib
471         root.client
472         root.server
473         WinInstall
474
475     Bin - contains build utilities.
476     root.client - contains Open AFS binaries
477     root.server - contain Open AFS Server binaries
478     WinInstall\OpenAFSforWindows.exe - is the NSIS install package
479     WinInstall\openafs-en_US.msi - is the WiX MSI install package
480
481
482 STEP L. Optional Items
483
484 The build process has an error table that is compiled for many OpenAFS
485 applications.  This table is generated by Unix based tools.  It is not
486 normally necessary to modify this table so pre-generated source files
487 are included in the OpenAFS source.  If you need to make modifications
488 in these areas the Unix base tools that run on Windows can be found on
489 the web. For example:
490
491         http://cygwin.com/
492
493 Below is a short explanation how to update the error table.
494
495 (1) Install flex and bison from a Unix based tool provider.
496
497 (2) Make changes to the source files.
498
499 There are two files in the source tree that are processed with lex
500 and yacc on UNIX systems, src/comerr/et_lex.lex.l and
501 src/comerr/error_table.y, that when processed produce the files
502 et_lex.lex_nt.c, error_table_nt.c, and error_table_nt.h.
503
504 Since NT does not include lex and yacc or any equivalent tools, we
505 have provided the output files that lex and yacc produce (using Win32
506 ports of flex and bison). This will allow builds to work for anyone
507 who does not need to change the .l and .y files.
508
509 If you do need to change et_lex.lex.l, then you will need to install
510 Win32 port of flex on your system. Put flex.exe in a directory on the
511 path and rebuild.
512
513 If you do need to change error_table.y, then you will need to install
514 a Win32 port of bison on your system. Put bison.exe in a directory on
515 the path, configure bison as explained in step 5, and rebuild.
516
517 You can also attempt to use other replacements for lex and yacc. This
518 will require modifying the LEX and YACC settings in
519 /config/NTMakefile.i386_nt40. If the replacements require different
520 command line options than flex and bison, then you may also need to
521 change src/comerr/NTMakefile.
522
523 (3) Generate new OpenAFS binaries