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