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