README-WINDOWS

   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