src/README-NT

   1 Copyright 2000, International Business Machines Corporation and others.
   2 All Rights Reserved.
   3
   4 This software has been released under the terms of the IBM Public
   5 License.  For details, see the LICENSE file in the top-level source
   6 directory or on-line at http://www.openafs.org/dl/license10.html
   7
   8 Building OpenAFS on Windows NT
   9 ------------------------------
  10
  11 There are several steps that must be performed before a successful
  12 build of AFS on Windows NT can be completed. These steps are as follows:
  13
  14    A. Install a compiler
  15    B. Add missing header files
  16    C. Optional: Install Installshield 5.x
  17    D. Optional: Install flex and bison
  18    E. Configure the OpenAFS build environment
  19    F. Begin the build
  20
  21 Each step is explained in detail below:
  22
  23 A. Install a compiler
  24
  25    You must install a copy of Microsoft Visual C++ 5.0 or 6.0. The
  26    "Typical" install setting is sufficient. It may be possible to use
  27    other compilers, but the source code as provided will work with MS
  28    VC++ 5.0/6.0.
  29
  30 B. Add missing header files
  31
  32    Files from Microsoft's Device Driver Development kits for NT and
  33    Windows 9x are required to complete a build on NT. They are
  34    copyrighted by Microsoft and so cannot be included with the OpenAFS
  35    source tree. These files are:
  36
  37    netmpr.h
  38    netspi.h
  39    npapi.h
  40
  41    These files come from Microsoft DDKs as follows:
  42
  43    January 1997 Windows NT Workstation DDK - /ddk/frc/network/inc/npapi.h
  44    July 1998 Windows 95 DDK - net/inc/netmpr.h and net/inc/netspi.h
  45
  46    The may also be available on more recent releases of the DDKs.
  47    These files must live on the include path.
  48
  49 C. Optional: Install Installshield 5.x
  50
  51    There are two ways to build OpenAFS on NT:
  52       1. Build of the product, or
  53       2. build of the product plus an installer package
  54
  55    In order to do the build that includes the installer package, a
  56    copy of Installshield 5.x must be installed. NOTE: Installshield
  57    versions 6 and higher WILL NOT WORK.
  58
  59    Optional DLL's missing for Install Script
  60    Two Microsoft DLL's must be included at DEST\WinInstall\Config\.
  61         SHLWAPI.DLL
  62         WININET.DLL
  63
  64         These files are only used for the Install, they will not be left
  65         on the target machine.
  66
  67 D. Optional: Install flex and bison
  68
  69    There are two files in the source tree that are processed with lex
  70    and yacc on UNIX systems, src/comerr/et_lex.lex.l and
  71    src/comerr/error_table.y, that when processed produce the files
  72    et_lex.lex_nt.c, error_table_nt.c, and error_table_nt.h.
  73
  74    Since NT does not include lex and yacc or any equivalent tools, we
  75    have provided the output files that lex and yacc produce (using
  76    Win32 ports of flex and bison). This will allow builds to work for
  77    anyone who does not need to change the .l and .y files.
  78
  79    If you do need to change et_lex.lex.l, then you will need to
  80    install Win32 port of flex on your system. Put flex.exe in a
  81    directory on the path and rebuild.
  82
  83    If you do need to change error_table.y, then you will need to
  84    install a Win32 port of bison on your system. Put bison.exe in a
  85    directory on the path, configure bison as explained in step 5, and
  86    rebuild.
  87
  88    You can also attempt to use other replacements for lex and yacc.
  89    This will require modifying the LEX and YACC settings in
  90    src/config/NTMakefile.i386_nt40. If the replacements require
  91    different command line options than flex and bison, then you may
  92    also need to change src/comerr/NTMakefile.
  93
  94 E. Configure the OpenAFS build environment
  95
  96    A set of environment variables used by the OpenAFS makefiles must
  97    be properly set for a build to successfully complete. The file
  98    src/ntbuild.bat is a DOS-style batch file that will configure these
  99    settings for you. Within this file there are the following lines
 100    that must be set to match your system settings:
 101
 102    * set SYS_NAME=<sys type>
 103
 104    * set MSVCDIR=<path to vc directory of MS Visual C++>
 105    Ex: set MSVCDIR=c:\progra~1\DevStudio\vc
 106
 107       This is the path to the compiler directory of the Microsoft Visual
 108       C++ installation.
 109
 110    * set AFSDEV_INCLUDE=<default include directories>
 111    Ex: set AFSDEV_INCLUDE=%MSVCDIR%\include;%MSVCDIR%\mfc\include
 112
 113       This contains a semicolon separated list of directories that
 114       contain compiler provided include files. You should not need to
 115       edit this other than to point to the DDK includes not provided
 116       with the distribution
 117
 118    * set AFSROOT=<Root directory of OpenAFS - parent of the src directory>
 119    Ex: set AFSROOT=d:\OpenAFS
 120
 121       This is the root directory of OpenAFS, which is the parent
 122       directory of the src directory.
 123
 124    * set IS5ROOT=<root directory of the Installshield5 program files>
 125    Ex: set IS5ROOT=d:\progra~1\instal~1\instal~1.1pr
 126
 127       This is the path to the Installshield5 program directory. You
 128       should only define this if you have Installshield installed on
 129       your computer and want to create the install script as part of
 130       the build.
 131
 132    NOTES: There are other settings in ntbuild.bat, but the ones listed
 133          above must be set correctly for the build to succeed.
 134
 135           As can be seen in the examples above, all paths in
 136           ntbuild.bat must be in the old MSDOS 8.3 format.
 137
 138 F. Set version and installation options
 139
 140         Modify .\src\config\NTMakefile.i386_nt40
 141                 AFSPRODUCT_VERSION  - Product version
 142                 CELLNAME_DEFAULT - The default AFS cell name
 143                 CELLSERVDB_INSTALL - The default name for the CellServDB included in the install script
 144                 CELLSERVDB_WEB  - The default web address to obtain CellServDB
 145
 146 For Example:
 147
 148  .\src\config\NTMakefile.i386_nt40
 149
 150    AFSPRODUCT_VERSION=1.1.1a
 151    CELLNAME_DEFAULT=openafs.org
 152    CELLSERVDB_INSTALL=CellServDB.GrandCentral
 153    CELLSERVDB_WEB=http://grand.central.org/dl/cellservdb/CellServDB
 154
 155 NOTE: If CELLNAME_DEFAULT has a '.' in cell name, then the name is assumed to be
 156 a valid cell name and when the user installs AFS the AFS Control Center
 157 will default to NOT installed!
 158
 159 Version level may be specified in different formats, for example the following
 160 forms all have the same version level; however will be displayed differently:
 161
 162 AFSPRODUCT_VERSION=1.1.1a
 163 AFSPRODUCT_VERSION=1.1.1 a
 164 AFSPRODUCT_VERSION=1.1.1.1
 165 AFSPRODUCT_VERSION=1.1.101
 166
 167 Add CellServDB file to install area.
 168          For the previous example you would add file:
 169                  DEST\Winistall\Config\CellServDB.GrandCentral
 170
 171 G. Begin the build
 172
 173  1. Make sure you are running the default NT command shell, cmd.exe.
 174     Other shells may work, but many do not.
 175
 176  2. Run the ntbuild.bat file that was configured in step 5. You can
 177     include the word "checked" on the command line to create binaries
 178     that include debug information, or the word "free" to create
 179     binaries that do not include debug information.
 180
 181     For a debug build, run:
 182        ntbuild checked
 183
 184     For a release build, run:
 185        ntbuild free
 186
 187  3. Copy the file src/NTMakefile to the parent of the src directory.
 188     You only need to do this once.
 189
 190  4. If you have not created a separate object build directory, edit NTMakefile and
 191     OBJ=obj to OBJ=src.
 192
 193  5. Begin the build. You can choose to build just the product bits,
 194     or, if Installshield is installed, the product bits and the
 195     install package.
 196
 197     To build just the product bits, run:
 198        nmake /f NTMakefile install
 199
 200     To build the product bits and the install package, run:
 201        nmake /f NTMakefile media