522a5ad7fc78e874e2e11aaa1d01aed12962cd42
[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 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
184 STEP D. Configure NTBUILD.BAT.
185
186 The NTBUILD.BAT file copied to the OpenAFS base directory must be 
187 customized for use on your development system.  The following variables
188 must be defined to match your configuration:
189
190   AFSVER_CL: Set to 1200 if using MS Visual C++ 6.0
191              Set to 1300 if using MS Visual Studio .NET
192              Set to 1310 if using MS Visual Studio .NET 2003
193              Set to 1400 if using MS Visual Studio .NET 2005
194
195   MSVCDIR: Set to the short name version of the directory into which
196            the visual C++ compiler was installed regardless of version
197
198   MSSDKDIR: Set to the short name of the directory into which
199             the Platform SDK was installed
200
201   NTDDKDIR: Set the short name of the directory containing the npapi.h file
202
203   AFSROOT: Set to the short name of the OpenAFS Base directory
204
205
206 STEP E. Set version and installation options (optional)
207
208 Add a CellServDB file to install area. CellServDB contains the entries
209 for the various cell names.  You can download a general purpose one
210 from:
211         http://grand.central.org/dl/cellservdb/CellServDB
212 then copy it to %AFSROOT%\src\WINNT\install\NSIS and name it afsdcell.ini
213
214 Edit file %AFSROOT%\src\config\NTMakefile.i386_nt40
215     AFSPRODUCT_VER_MAJOR - Version Major Number
216     AFSPRODUCT_VER_MINOR - Version Minor Number
217     AFSPRODUCT_VER_PATCH - Version Patch Number
218     AFSPRODUCT_VER_BUILD - Version Build Number
219     CELLSERVDB_INSTALL   - The default file name for the CellServDB
220                            included in the install Package.
221     CELLNAME_DEFAULT     - The default home cell name.
222     CELLSERVDB_WEB       - The default web address to obtain CellServDB
223
224 For example: in the file %AFSROOT%\src\config\NTMakefile.i386_nt40 you would
225 see the following:
226
227    AFSPRODUCT_VER_MAJOR=1
228    AFSPRODUCT_VER_MINOR=3
229    AFSPRODUCT_VER_PATCH=7400
230    AFSPRODUCT_VER_BUILD=0
231    CELLNAME_DEFAULT=openafs.org
232    CELLSERVDB_INSTALL=CellServDB.GrandCentral
233    CELLSERVDB_WEB=http://grand.central.org/dl/cellservdb/CellServDB
234
235 During the Open AFS installation process the user will be presented
236 with two choices for the CellServDB: Local copy (CELLSERVDB_INSTALL) and
237 one that can be downloaded from the web (CELLSERVDB_WEB).
238
239 STEP F. Begin the build
240
241 (1) From Windows 2000/XP/2003 open up a DOS prompt window.
242
243 (2) Change to the %AFSROOT% directory
244
245 (3) Configure the environment variables:
246
247     For a release build (SMB version):
248
249     (a) Execute the VCVARS32.BAT or VSVARS32.BAT file which part of the
250         Visual Studio environment you installed.
251
252     (b) Execute the SETENV.BAT file with the parameters "/2000 /RETAIL"
253
254     (c) Execute the NTBUILD.BAT file with the parameter "free"
255
256     For a release build (IFS version):
257
258     (a) Execute the VCVARS32.BAT or VSVARS32.BAT file which part of the
259         Visual Studio environment you installed.
260
261     (b) Execute the SETENV.BAT file with the parameters "/2000 /RETAIL"
262
263     (c) Execute the NTBUILD.BAT file with the parameter "free ifs"
264
265     For a debug build (SMB version):
266
267     (a) Execute the VCVARS32.BAT or VSVARS32.BAT file which part of the
268         Visual Studio environment you installed.
269
270     (b) Execute the SETENV.BAT file with the parameters "/2000 /DEBUG"
271
272     (c) Execute the NTBUILD.BAT file with the parameter "checked"
273
274     For a debug build (IFS version):
275
276     (a) Execute the VCVARS32.BAT or VSVARS32.BAT file which part of the
277         Visual Studio environment you installed.
278
279     (b) Execute the SETENV.BAT file with the parameters "/2000 /DEBUG"
280
281     (c) Execute the NTBUILD.BAT file with the parameter "checked ifs"
282
283 (4) Clean the work area:
284
285     nmake /f NTMakefile clean
286
287 (5) Build the complete Windows NT/2000 development environment.
288
289     nmake /f NTMakefile install
290
291 While the build is running you will see many compile warnings. This
292 behavior is normal; the build process is successful as long as the build
293 process doesn't terminate with an error ("nmake.exe return code 0x2")
294 and it displays 'Build Finished Successfully'.
295
296
297 STEP G. Install NSIS 2.0 (optional).
298
299 Download the Nullsoft Scriptable Installation System (NSIS) 2.0 from
300
301     http://nsis.sourceforge.net/home/
302
303 Run the nsis20.exe installer.
304
305 NOTE: The NSIS installer may be rebuilt from source files 
306    
307     C:\Program Files\NSIS\Source
308
309 to enable options not built into the default configuration.  The 
310 OpenAFS installers are built using a modified version of the NSIS
311 sources.  The following changes were made to exehead\config.h.
312
313     NSIS_MAX_STRLEN set to 4096
314     NSIS_CONFIG_LOG defined
315     NSIS_CONFIG_LOG_ODS defined
316     
317
318 STEP H.  Build OpenAFS NSIS install package
319
320 From the %AFSROOT% directory execute:
321
322     nmake /f NTMakefile NSIS
323
324
325 STEP I.  Install Wix MSI Installer
326
327 Download the Wix 2.0.2217.0 installer from 
328
329     http://prdownloads.sourceforge.net/wix/sources-2.0.2217.0.zip
330
331 Apply the following patches to the source tree and execute 
332
333     make ship
334
335 from the \src\wix directory.  
336
337 Index: src/wix/Common.cs
338 ===================================================================
339 RCS file: /cvsroot/wix/wix/src/wix/Common.cs,v
340 retrieving revision 1.7
341 diff -w -r1.7 Common.cs
342 140a141,146
343 >               public static long GetFileTimeFromDateTime(string dateTime) 
344 >               {
345 >                       System.DateTime sdt = System.Xml.XmlConvert.ToDateTime(dateTime);
346 >                       return sdt.ToFileTime();
347 >               }
348
349 Index: src/wix/Compiler.cs
350 ===================================================================
351 RCS file: /cvsroot/wix/wix/src/wix/Compiler.cs,v
352 retrieving revision 1.14
353 diff -w -r1.14 Compiler.cs
354 847c847
355 <                     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
356 ---
357 >                     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
358 2352a2353,2358
359 >                       // if a Value attribute was given by itself, make this a type 19 custom action
360 >                       if( sourceBits == 0 && targetBits == MsiInterop.MsidbCustomActionTypeTextData ) 
361 >                       {
362 >                               sourceBits = MsiInterop.MsidbCustomActionTypeSourceFile;
363 >                       }
364
365 3881c3887
366 <                         minDate = attrib.Value;
367 ---
368 >                         minDate = Common.GetFileTimeFromDateTime( attrib.Value ).ToString();
369 3884c3890
370 <                         maxDate = attrib.Value;
371 ---
372 >                         maxDate = Common.GetFileTimeFromDateTime( attrib.Value ).ToString();
373 8187a8194,8207
374 >                                       case "Delete":
375 >                                               switch (attrib.Value)
376 >                                               {
377 >                                                       case "install":
378 >                                                               events |= MsiInterop.MsidbServiceControlEventDelete;
379 >                                                               break;
380 >                                                       case "uninstall":
381 >                                                               events |= MsiInterop.MsidbServiceControlEventUninstallDelete;
382 >                                                               break;
383 >                                                       case "both":
384 >                                                               events |= MsiInterop.MsidbServiceControlEventDelete | MsiInterop.MsidbServiceControlEventUninstallDelete;
385 >                                                               break;
386 >                                               }
387 >                                               break;
388 9685a9706
389
390 Index: src/wix/Preprocessor.cs
391 ===================================================================
392 RCS file: /cvsroot/wix/wix/src/wix/Preprocessor.cs,v
393 retrieving revision 1.6
394 diff -w -r1.6 Preprocessor.cs
395 274c274
396 <                             context = new IfContext(context.IsTrue & context.Active, this.variables.ContainsKey(reader.Value.Trim()), IfState.If);
397 ---
398 >                             context = new IfContext(context.IsTrue & context.Active, this.IsDefined(reader.Value.Trim()), IfState.If);
399 279c279
400 <                             context = new IfContext(context.IsTrue & context.Active, !this.variables.ContainsKey(reader.Value.Trim()), IfState.If);
401 ---
402 >                             context = new IfContext(context.IsTrue & context.Active, !this.IsDefined(reader.Value.Trim()), IfState.If);
403 360a361,362
404 >                                               case "error":
405 >                                                       throw new WixPreprocessorException(this.GetCurrentSourceLineNumbers(), this.PreprocessVariables(reader.Value));
406 419a422,437
407 >               /// Returns true if the symbol exists.
408 >               /// </summary>
409 >               /// <param name="symbol">symbol name to check</param>
410 >               /// <returns>true if symbol is defined</returns>
411 >               private bool IsDefined(string symbol)
412 >               {
413 >                       if( symbol.StartsWith("env.") )
414 >                               return Environment.GetEnvironmentVariable(symbol.Substring(4)) != null;
415 >                       if( symbol.StartsWith("var.") )
416 >                               return this.variables.ContainsKey(symbol.Substring(4));
417 >                       if( symbol.StartsWith("sys.") )
418 >                               return this.systemVariables.ContainsKey(symbol.Substring(4));
419 >                       return this.variables.ContainsKey(symbol);
420 >               }
421
422 >         /// <summary>
423 Index: src/wix/wix.csproj
424 ===================================================================
425 RCS file: /cvsroot/wix/wix/src/wix/wix.csproj,v
426 retrieving revision 1.4
427 diff -w -r1.4 wix.csproj
428 661a662,666
429 >                     RelPath = "Xsd\wix.xsx"
430 >                     DependentUpon = "wix.xsd"
431 >                     BuildAction = "None"
432 >                 />
433 >                 <File
434 664a670,674
435 >                 <File
436 >                     RelPath = "Xsd\wixloc.xsx"
437 >                     DependentUpon = "wixloc.xsd"
438 >                     BuildAction = "None"
439 >                 />
440
441
442 STEP J.  Build Wix MSI install package
443
444 From the %AFSROOT% directory execute:
445
446     nmake /f NTMakefile wix
447
448 Make sure the binaries installed to \src\wix\release\ship are
449 available in the PATH environment variable
450
451
452 STEP K. Final Results
453
454 The build process generates its binaries in %AFSROOT%\DEST. The subdirectory
455 would look like the following:
456
457 %AFSROOT%\DEST\{checked,free}\
458         bin
459         etc
460         include
461         lib
462         root.client
463         root.server
464         WinInstall
465
466     Bin - contains build utilities.
467     root.client - contains Open AFS binaries
468     root.server - contain Open AFS Server binaries
469     WinInstall\OpenAFSforWindows.exe - is the NSIS install package
470     WinInstall\openafs-en_US.msi - is the WiX MSI install package
471
472
473 STEP L. Optional Items
474
475 The build process has an error table that is compiled for many OpenAFS
476 applications.  This table is generated by Unix based tools.  It is not
477 normally necessary to modify this table so pre-generated source files
478 are included in the OpenAFS source.  If you need to make modifications
479 in these areas the Unix base tools that run on Windows can be found on
480 the web. For example:
481
482         http://cygwin.com/
483
484 Below is a short explanation how to update the error table.
485
486 (1) Install flex and bison from a Unix based tool provider.
487
488 (2) Make changes to the source files.
489
490 There are two files in the source tree that are processed with lex
491 and yacc on UNIX systems, src/comerr/et_lex.lex.l and
492 src/comerr/error_table.y, that when processed produce the files
493 et_lex.lex_nt.c, error_table_nt.c, and error_table_nt.h.
494
495 Since NT does not include lex and yacc or any equivalent tools, we
496 have provided the output files that lex and yacc produce (using Win32
497 ports of flex and bison). This will allow builds to work for anyone
498 who does not need to change the .l and .y files.
499
500 If you do need to change et_lex.lex.l, then you will need to install
501 Win32 port of flex on your system. Put flex.exe in a directory on the
502 path and rebuild.
503
504 If you do need to change error_table.y, then you will need to install
505 a Win32 port of bison on your system. Put bison.exe in a directory on
506 the path, configure bison as explained in step 5, and rebuild.
507
508 You can also attempt to use other replacements for lex and yacc. This
509 will require modifying the LEX and YACC settings in
510 /config/NTMakefile.i386_nt40. If the replacements require different
511 command line options than flex and bison, then you may also need to
512 change src/comerr/NTMakefile.
513
514 (3) Generate new OpenAFS binaries