windows-updates-20010819
[openafs.git] / 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 (6 might also
26    work). The "Typical" install setting is sufficient. It may be
27    possible to use other compilers, but the source code as provided
28    will work with MS VC++ 5.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 MSVCDIR=<path to vc directory of MS Visual C++>
103    Ex: set MSVCDIR=c:\progra~1\DevStudio\vc
104
105       This is the path to the compiler directory of the Microsoft Visual
106       C++ installation.
107
108    set AFSDEV_INCLUDE=<default include directories>
109    Ex: set AFSDEV_INCLUDE=%MSVCDIR%\include;%MSVCDIR%\mfc\include
110
111       This contains a semicolon separated list of directories that
112       contain compiler provided include files. You do not need to add paths
113       here of AFS include files.
114
115    set AFSDEV_LIB=<default library directories>
116    Ex: set AFSDEV_LIB=%MSVCDIR%\lib;%MSVCDIR%\mfc\lib
117
118       This contains a semicolon separated list of directories that
119       contain compiler provided library files. You do not need to add
120       paths here of AFS library files.
121
122    set AFSDEV_BIN=<compiler binaries directory>
123    Ex: set AFSDEV_BIN=%MSVCDIR%\bin
124
125       This is the path to the compiler binary files.
126
127    set AFSROOT=<Root directory of OpenAFS - parent of the src directory>
128    Ex: set AFSROOT=d:\OpenAFS
129
130       This is the root directory of OpenAFS, which is the parent
131       directory of the src directory.
132
133    set IS5ROOT=<root directory of the Installshield5 program files>
134    Ex: set IS5ROOT=d:\progra~1\instal~1\instal~1.1pr
135
136       This is the path to the Installshield5 program directory. You
137       should only define this if you have Installshield installed on
138       your computer and want to create the install script as part of
139       the build.
140
141    set BISON_SIMPLE=<path to bison.simple>
142    set BISON_HAIRY=<path to bison.hairy>
143    Ex: set BISON_SIMPLE=c:\bin\bison.simple
144    Ex: set BISON_HAIRY=c:\bin\bison.hairy
145
146       bison has two files (in addition to the bison executable) that
147       must be on the system. In order for bison to find these files,
148       you must set the environment variables listed above to the paths
149       to these files. There are other ways to do this, but this is
150       what the build system expects.
151
152    NOTE: There are other settings in ntbuild.bat, but the ones listed
153          above must be set correctly for the build to succeed.
154
155    As can be seen in the examples above, all paths in ntbuild.bat must
156    be in the old MSDOS 8.3 format.
157
158 F. Set version and installation options
159
160         Modify .\src\config\NTMakefile.i386_nt40
161                 AFSPRODUCT_VERSION  - Product version
162                 CELLNAME_DEFAULT - The default AFS cell name
163                 CELLSERVDB_INSTALL - The default name for the CellServDB included in the install script
164                 CELLSERVDB_WEB  - The default web address to obtain CellServDB
165
166 For Example:
167
168  .\src\config\NTMakefile.i386_nt40
169
170    AFSPRODUCT_VERSION=1.1.1a
171    CELLNAME_DEFAULT=openafs.org
172    CELLSERVDB_INSTALL=CellServDB.GrandCentral
173    CELLSERVDB_WEB=http://grand.central.org/dl/cellservdb/CellServDB
174
175 NOTE: If CELLNAME_DEFAULT has a '.' in cell name, then the name is assumed to be 
176 a valid cell name and when the user installs AFS the AFS Control Center 
177 will default to NOT installed!
178
179 Version level may be specified in different formats, for example the following
180 forms all have the same version level; however will be displayed differently:
181
182 AFSPRODUCT_VERSION=1.1.1a
183 AFSPRODUCT_VERSION=1.1.1 a
184 AFSPRODUCT_VERSION=1.1.1.1
185 AFSPRODUCT_VERSION=1.1.101
186
187 Add CellServDB file to install area.
188          For the previous example you would add file:
189                  DEST\Winistall\Config\CellServDB.GrandCentral
190
191 G. Begin the build
192
193  1. Make sure you are running the default NT command shell, cmd.exe.
194     Other shells may work, but many do not.
195
196  2. Run the ntbuild.bat file that was configured in step 5. You can
197     include the word "checked" on the command line to create binaries
198     that include debug information, or the word "free" to create
199     binaries that do not include debug information.
200
201     For a debug build, run:
202        ntbuild checked
203
204     For a release build, run:
205        ntbuild free
206
207  3. Copy the file src/NTMakefile to the parent of the src directory.
208     You only need to do this once.
209
210  4. Begin the build. You can choose to build just the product bits,
211     or, if Installshield is installed, the product bits and the
212     install package.
213
214     To build just the product bits, run:
215        nmake /f NTMakefile install
216
217     To build the product bits and the install package, run:
218        nmake /f NTMakefile media