1 This software has been released under the terms of the IBM Public
\r
2 License. For details, see the LICENSE file in the top-level source
\r
3 directory or on-line at http://www.openafs.org/dl/license10.html
\r
5 The document now provides a step by step procedure that takes the user
\r
6 from a basic Windows NT/2000 workstation to an OpenAFS development
\r
7 environment. Details are provided so that a 'beginning' windows
\r
8 developer can build an OpenAFS installable package for Windows NT/2000.
\r
10 *********** Windows NT/2000 Build Process ****************
\r
12 Building OpenAFS for Windows requires configuring a Windows
\r
13 development system by installing compilation tools and header files.
\r
14 Open AFS Software development can be done on Windows NT or 2000. The
\r
15 target system, where OpenAFS will be installed, should be either
\r
16 Windows NT or Windows 2000. The building process is controlled by a
\r
17 nmake file that generates the necessary binaries and binds them into an
\r
20 The following steps describe how to configure Windows 2000/NT:
\r
22 A. Obtain a copy of the OpenAFS Source Tree
\r
23 B. Install Compiler and Development tools.
\r
24 C. Set up drive mappings.
\r
25 D. Install SDK header files
\r
26 E. Configure Environment variables
\r
27 F. Set program version Level
\r
28 G. Build Win2000 binaries
\r
29 H. Install InstallShield 5.x
\r
30 I. Build Win2000 InstallShield Package
\r
31 J. Build Win2000 InstallShield Package for the Web
\r
33 L. Creating a Debug Environment
\r
35 N. Required patches for 1.2.2a and earlier releases
\r
37 The Software development tools with InstallShield require 900 MB
\r
40 The Software development tools (without InstallShield) require 660 MB
\r
43 The OpenAFS Source directory requires about 200 MB storage. The Source
\r
44 directory size includes additional space for files that will be
\r
45 generated during the build process.
\r
47 The following CDs are used in this example:
\r
48 Microsoft SDK and Tools Jan 2001
\r
49 Microsoft Visual Studio Version 6.0
\r
52 Different versions of above CDs can be used; however, building an
\r
53 install package for Windows NT/2000 requires InstallShield
\r
54 version 5.0 to 5.5 (version 6.0 or better will not work).
\r
56 You can build all the necessary binaries without the InstallShield
\r
57 software. InstallShield is only needed to build an install package.
\r
59 STEP A. Obtain a copy of the Open AFS Source Tree.
\r
61 Transfer OpenAFS source tree onto your hardrive. The source can be
\r
62 downloaded from the OpenAFS web site:
\r
63 http://www.OpenAFS.org/release/snapindex.html.
\r
65 For this example, download source for version 1.2.2a using the
\r
67 http://www.openafs.org/dl/openafs/1.2.2a/openafs-1.2.2a-src.tar
\r
69 HINT: DailySnapShots are pre-release source trees and much more
\r
70 likely to have compilation errors. If this is your first attempt, do
\r
71 your build based on a release version of the source, e.g. 1.2.2.a. Once
\r
72 you have completed a build process successfully, you can experiment with
\r
75 You will need an unzip utility that can expand compressed tar files.
\r
76 For example "Pkzip for Windows" from Pkware will uncompress tar files.
\r
77 (http://www.pkware.com/)
\r
79 Expand the downloaded tar file (openafs-1.2.2a-src.tar) into target
\r
80 directory (c:\OpenAFS), the unzip routine will expand the source into a
\r
82 c:\OpenAFS\OpenAFS-1.2.2a\src
\r
84 Copy files NTMAKEFILE from 'src' to the AFS base directory:
\r
86 From a DOS command prompt window, enter the following copy commands:
\r
88 copy c:\OpenAFS\OpenAFS-1.2.2a\src\NTMAKEFILE c:\OpenAFS\OpenAFS-1.2.2a\.
\r
90 The AFS base directory should look something like the following:
\r
92 c:\OpenAFS\OpenAFS-1.2.2a\
\r
96 STEP B. Install compiler and development tools.
\r
98 Install a copy of Microsoft Visual C++ 5.0 or 6.0. The "Typical" install
\r
99 setting is sufficient.
\r
101 (1) You can reduce the installation size by selecting "Custom" install
\r
102 and remove all but the following Options:
\r
104 Microsoft Visual C++
\r
107 (2) When asked, Select to Register Environment Variables.
\r
109 (3) After rebooting you have to choice to install additional software
\r
110 packages. It is not necessary to install these packages.
\r
112 STEP C. Map development drive letters.
\r
114 The following documentation will assume you are mapping the Y: drive to
\r
115 the OpenAFS source directory and you are mapping X: drive to your
\r
116 development tools directory. Other configurations will work, including
\r
117 not mapping any drives, as long as the path assignments are consistent
\r
118 and you don't exceed the maximum environment variable length.
\r
120 Y: drive mapping provides a consistent directory location to build from.
\r
121 Building OpenAFS will require you to open up a command DOS prompt,
\r
122 navigate to drive Y: and execute the nmake file. The source is based
\r
123 from Y: drive and the generated files are based from Y:\DEST. If the OpenAFS
\r
124 source tree is at a different location, you only need to re-map the
\r
127 X: drive mapping shortens the length of several Environment variables
\r
128 by mapping it to a directory where Visual Studio is installed. Although
\r
129 this step is not important when using Windows NT or 2000 as a
\r
130 development OS, it does reduce the chance of typing errors during
\r
131 the configuration phase.
\r
133 From a DOS command window enter the following commands:
\r
135 SUBST y: c:\OpenAFS\OpenAFS-1.2.2a
\r
136 SUBST x: "c:\Program Files\Microsoft Visual Studio\VC98"
\r
138 SUBST is persistent across DOS command prompts; that is, if you open up
\r
139 another DOS command prompt the mapped drives are still defined.
\r
140 However, if you reboot the mapped drives using SUBST will be lost.
\r
142 If you need to remove Y: drive mapping, execute the following command
\r
143 from a DOS command prompt window:
\r
147 STEP D. Install SDK header files.
\r
149 Files from Microsoft's Platform SDK for NT or 98 are required to
\r
150 complete a build on NT/2000.
\r
152 The header files that are required are found from a Microsoft SDK are:
\r
157 To Install Platform SDK from CDROM
\r
159 Run "setup.exe default.htm" from CDROM:
\r
160 Select Microsoft Core SDK
\r
161 Select Sample and Source
\r
162 Select installation path x:\SDK
\r
164 To Install Windows SDK from WEB:
\r
165 http://www.microsoft.com/sdk
\r
167 STEP E. Configure the OpenAFS build environment.
\r
169 The following environment variables should be set:
\r
171 SET AFSDEV_LIB=%LIB%
\r
173 SET SYS_NAME=i386_nt40
\r
174 SET _WIN32_IE=0x400
\r
178 SET AFSDEV_BIN=X:\BIN
\r
179 SET AFSDEV_BUILDTYPE=FREE
\r
180 SET AFSDEV_INCLUDE=X:\Sdk\samples\winbase\security\winnt\logonNP;X:\Sdk\Include\ATL30;X:\Sdk\Include;%INCLUDE%
\r
182 Please do not include unnecessary spaces in AFSDEV_INLCUDE.
\r
184 Create a batch file (SETAFS.BAT) to make these settings that can be
\r
185 executed when you bring up a DOS command prompt window. Environment
\r
186 variables are not persistent, if you close the DOS command window
\r
187 or reboot, the environment variables are lost and they must be
\r
188 recreated when you open a new DOS command prompt window.
\r
190 HINT: SET AFSDEV_BUILDTYPE=CHECKED if you want debug information
\r
191 included in your binaries.
\r
193 HINT: Adding drive mapping commands to the batch file makes it easy to
\r
194 establish your development environment even if you logoff. I suggest
\r
195 adding the following lines to the beginning of the batch file:
\r
199 SUBST y: c:\OpenAfs\OpenAFS-1.2.2a
\r
200 SUBST x: "c:\Program Files\Microsoft Visual Studio\VC98"
\r
202 HINT: Windows 2000/NT provides an alternate way to set environment
\r
203 variables in System Proprieties. These can be accessed from the system
\r
204 control panel, advanced tab, Environment Variables. These are
\r
205 persistent and will be reset every time a DOS command prompt window is
\r
208 STEP F. Set version and installation options
\r
210 Add a CellServDB file to install area. CellServDB contains the entries
\r
211 for the various cell names. You can download a general purpose one
\r
213 http://grand.central.org/dl/cellservdb/CellServDB
\r
214 then copy it to Y:\DEST\Wininstall\Config\CellServDB.GrandCentral
\r
216 Note: Create directory Y:\DEST\Wininstall\Config\ if it doesn't exist.
\r
218 Edit file Y:\src\config\NTMakefile.i386_nt40
\r
219 AFSPRODUCT_VERSION - Product version
\r
220 CELLSERVDB_INSTALL - The default file name for the CellServDB
\r
221 included in the install Package.
\r
222 CELLNAME_DEFAULT - The default home cell name.
\r
223 CELLSERVDB_WEB - The default web address to obtain CellServDB
\r
225 For example: in the file Y:\src\config\NTMakefile.i386_nt40 you would
\r
228 AFSPRODUCT_VERSION=1.2.2a
\r
229 CELLNAME_DEFAULT=home.cell.com
\r
230 CELLSERVDB_INSTALL=CellServDB.GrandCentral
\r
231 CELLSERVDB_WEB=http://grand.central.org/dl/cellservdb/CellServDB
\r
233 During the Open AFS installation process the user will be presented
\r
234 with two choices for the CellServDB: Local copy (CELLSERVDB_INSTALL) and
\r
235 one that can be downloaded from the web (CELLSERVDB_WEB).
\r
237 HINT: The product version number (AFSPRODUCT_VERSION) can be changed to
\r
238 create a new version number. For example if you have added source
\r
239 changes to OpenAFS-1.2.2a and you wanted to create a new version level,
\r
240 you may want to use the following: AFSPRODUCT_VERSION=1.2.2b
\r
242 STEP G. Begin the build
\r
244 (1) From Windows 2000 open up a DOS prompt window.
\r
246 (2) Clean the work area.
\r
248 nmake /f NTMakefile clean
\r
250 (3) Build the complete Windows NT/2000 development environment.
\r
252 nmake /f NTMakefile install
\r
254 While the build is running you will see many compile warnings. This
\r
255 behavior is normal; the build process is successful as long as the build
\r
256 process doesn't terminate with an error ("nmake.exe return code 0x2")
\r
257 and it displays 'Build Finished Successfully'.
\r
259 STEP H. Install InstallShield (optional).
\r
261 In order to build an install package for OpenAFS, InstallShield 5.5
\r
262 must be installed along with InstallShield East and West
\r
263 multi-Language packs.
\r
265 (1) Install InstallShield (version between 5.0 and 5.5)
\r
267 For minimum installation choose "compact".
\r
269 (2) Install West Language Pack (5.5)
\r
271 (3) Install East Language Pack (5.5)
\r
273 NOTE: InstallShield's versions 6 and higher WILL NOT WORK for
\r
274 Windows NT/2000 build process.
\r
276 (4) Add necessary DLL's to work with the InstallShield package.
\r
278 Two Microsoft DLL's are missing from the InstallShield package. These
\r
279 DLL's must be copied to Y:\DEST\WinInstall\Config\:
\r
283 These files are only used during the installation, and they will not
\r
284 be left on the target machine. They can be located at
\r
285 %SystemRoot%\SYSTEM32.
\r
287 From a DOS command prompt window enter the following commands:
\r
289 copy %systemRoot%\System32\SHLWAPI.DLL y:\dest\wininstall\config\.
\r
290 copy %systemRoot%\System32\WININET.DLL y:\dest\wininstall\config\.
\r
292 (5) Add two Environment variables to the bottom of the batch file,
\r
293 SETAFS.BAT (see STEP E:).
\r
295 SET IS5ROOT="C:\Program Files\InstallShield\InstallShield 5.5 Professional Edition"
\r
296 SET AFSDEV_INCLUDE=%AFSDEV_INCLUDE%;%IS5ROOT%\Include
\r
298 STEP I. Build Win2000 InstallShield package
\r
300 From the DOS command prompt window run:
\r
303 nmake /f NTMakefile media
\r
305 While the build is running you will see a few compile warnings. This
\r
306 behavior is normal; the build process is successful as long as the build
\r
307 process doesn't terminate with an error ("nmake.exe return code 0x2")
\r
308 and it displays 'Install Script Finished Successfully'.
\r
310 STEP J. Build Win2000 InstallShield package for the Web
\r
312 InstallShield's PackageForTheWeb combines the installation files into a
\r
313 single application file that will expand on execution and lead you
\r
314 through the OpenAFS installation.
\r
316 Install PackageForTheWeb 3 from InstallShield
\r
318 Add Environment variables to the bottom of the batch file, SETAFS.BAT
\r
321 SET ISWEB="C:\Program Files\InstallShield\PackageForTheWeb 3"
\r
323 From the DOS command prompt window run:
\r
326 nmake /f NTMakefile media
\r
328 While the build is running you will see a few compile warnings. This
\r
329 behavior is normal; the build process is successful as long as the build
\r
330 process doesn't terminate with an error ("nmake.exe return code 0x2") and
\r
331 it displays 'Install Script Finished Successfully'.
\r
333 HINT: It is only necessary to run "nmake /f NTMakefile media" once, by
\r
334 combining steps I & J.
\r
336 STEP K. Final Results
\r
338 The build process generates its binaries in Y:\DEST. The subdirectory
\r
339 would look like the following:
\r
350 Y:\DEST\Bin - contains build utilities.
\r
351 Y:\DEST\root.client - contains Open AFS binaries
\r
352 Y:\DEST\root.server - contain Open AFS Server binaries
\r
353 Y:\DEST\WinInstall\PackageWeb\AFSforWindows.exe - is the Web install
\r
354 package for Open AFS.
\r
355 Y:\DEST\WinInstall\ - are the install package files for Open AFS
\r
357 Step L. Creating a Debug Environment
\r
359 Instructions on building a debugging environment from Visual Studio C++
\r
360 workspace. This example give the user a way to step through the source
\r
361 code for AFSCREDS.EXE.
\r
363 These instructions are to be followed after you have set up the
\r
364 development environment.
\r
366 The following steps must be done before you can build a debug
\r
369 1. Set up the development environment as described above
\r
370 2. set AFS_BUILDTYPE=CHECKED to get debug information.
\r
371 3. You must use environment variables in System Properties
\r
372 4. Do a complete build.
\r
374 To set the the environment variables in the System Properties:
\r
375 1. Select the 'System' icon in the control Panel
\r
376 2. Select the 'Advanced' tab
\r
377 3. Select the 'Environment Variables' button
\r
378 4. In the user area set all variables as you did above that
\r
379 were used in the setafs.bat file.
\r
381 To build a new work space to debug afs_creds.exe:
\r
383 1. Create New Workspace -
\r
384 Select from Microsoft Visual C++ toolbar file New
\r
385 Select from 'new' Project Tab Makefile Project name: Creds
\r
386 Location Y:\src\winnt\client_creds
\r
389 From Dialog Box 'Makefile - Step 1 of 2'
\r
390 command line= nmake /f"ntmakefile" install
\r
391 Output = y:\dest\root.client\usr\vice\etc\AFSCREDS.EXE
\r
394 Dialog Box 'Makefile - Step 2 of 2'
\r
395 Command line= nmake /f"ntmakefile" install
\r
396 Output = y:\dest\root.client\usr\vice\etc\AFSCREDS.EXE
\r
401 Right click on 'Source Files' and select 'Add Files to folder', select
\r
404 Right click on 'Header Files' and select 'Add Files to folder', select
\r
407 Right click on 'creds files' and select 'New Folder'
\r
408 Fill name in 'Build'
\r
410 From the toolbar select Build
\r
413 You should see the following string when the compile is finished:
\r
414 "afs_creds.exe - 0 errors(0), 0 warnings(s)"
\r
416 Press <F5> to execute afs_creds.exe.
\r
418 STEP M. Optional Items
\r
420 The build process has an error table that is compiled for many OpenAFS
\r
421 applications. This table is generated by Unix based tools. It is not
\r
422 normally necessary to modify this table so pre-generated source files
\r
423 are included in the OpenAFS source. If you need to make modifications
\r
424 in these areas the Unix base tools that run on Windows can be found on
\r
425 the web. For example:
\r
429 Below is a short explanation how to update the error table.
\r
431 (1) Install flex and bison from a Unix based tool provider.
\r
433 (2) Make changes to the source files.
\r
435 There are two files in the source tree that are processed with lex
\r
436 and yacc on UNIX systems, src/comerr/et_lex.lex.l and
\r
437 src/comerr/error_table.y, that when processed produce the files
\r
438 et_lex.lex_nt.c, error_table_nt.c, and error_table_nt.h.
\r
440 Since NT does not include lex and yacc or any equivalent tools, we
\r
441 have provided the output files that lex and yacc produce (using Win32
\r
442 ports of flex and bison). This will allow builds to work for anyone
\r
443 who does not need to change the .l and .y files.
\r
445 If you do need to change et_lex.lex.l, then you will need to install
\r
446 Win32 port of flex on your system. Put flex.exe in a directory on the
\r
449 If you do need to change error_table.y, then you will need to install
\r
450 a Win32 port of bison on your system. Put bison.exe in a directory on
\r
451 the path, configure bison as explained in step 5, and rebuild.
\r
453 You can also attempt to use other replacements for lex and yacc. This
\r
454 will require modifying the LEX and YACC settings in
\r
455 /config/NTMakefile.i386_nt40. If the replacements require different
\r
456 command line options than flex and bison, then you may also need to
\r
457 change src/comerr/NTMakefile.
\r
459 (3) Generate new OpenAFS binaries
\r
462 STEP N. Required patches for 1.2.2a and earlier releases
\r
464 There are two set of patches must be applied to 1.2.2a source to
\r
465 successfully build the binaries:
\r
467 (1) Patches applied to 1.2.2a to build binaries, excluding install
\r
470 diff -Nur --exclude-from=exclude bas/src/NTMakefile upd/src/NTMakefile
\r
471 --- bas/src/NTMakefile Wed Nov 14 19:38:06 2001
\r
472 +++ upd/src/NTMakefile Mon Dec 3 14:41:12 2001
\r
473 @@ -471,6 +471,7 @@
\r
477 + echo Build Finished Successfully
\r
479 install: start finale
\r
481 @@ -487,6 +488,7 @@
\r
484 media: InstallShield5
\r
485 + echo Install Script Finished Successfully
\r
488 (2) Patches applied to 1.2.2a to build install package.
\r
490 diff -Nur --exclude-from=exclude bas/src/WINNT/afsd/NTMakefile upd/src/WINNT/afsd/NTMakefile
\r
491 --- bas/src/WINNT/afsd/NTMakefile Tue Nov 20 22:45:40 2001
\r
492 +++ upd/src/WINNT/afsd/NTMakefile Wed Dec 5 11:42:46 2001
\r
493 @@ -169,8 +169,8 @@
\r
494 $(EXEDIR)\tokens.exe \
\r
495 $(EXEDIR)\unlog.exe $(EXEDIR)\afsd.exe $(EXEDIR)\afsd_service.exe \
\r
496 $(EXEDIR)\fs.exe $(EXEDIR)\symlink.exe \
\r
497 - $(LOGON_DLLFILE) $(LOG95_DLLFILE) \
\r
498 - $(EXEDIR)\afsshare.exe \
\r
499 + $(LOGON_DLLFILE) \
\r
500 + $(EXEDIR)\afsshare.exe \
\r
501 $(DESTDIR)\bin\kpasswd.exe
\r
503 install9X: install_headers $(CONF_DLLFILE) \
\r
505 diff -Nur --exclude-from=exclude bas/src/WINNT/install/InstallShield5/NTMakefile upd/src/WINNT/install/InstallShield5/NTMakefile
\r
506 --- bas/src/WINNT/install/InstallShield5/NTMakefile Wed Nov 14 19:38:50 2001
\r
507 +++ upd/src/WINNT/install/InstallShield5/NTMakefile Mon Dec 3 16:43:08 2001
\r
509 $(MKDIR) $(DESTDIR)\Wininstall\PackageWeb
\r
511 $(DEL) /q $(DESTDIR)\Wininstall\PackageWeb\*.*
\r
512 - $(ISWEB)\Pftwwiz.exe $(AFSROOT)\src\winnt\install\InstallShield5\PackageWeb.pfw -s -a
\r
513 + "$(ISWEB)\Pftwwiz.exe" $(AFSROOT)\src\winnt\install\InstallShield5\PackageWeb.pfw -s -a
\r
515 xcopy /s/e/y "Media\OpenAFS\Disk Images\disk1\*.*" $(DESTDIR)\WinInstall
\r
516 copy AFS_component_version_number.txt $(DESTDIR)\WinInstall\Version.txt
\r
517 diff -Nur --exclude-from=exclude bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC
\r
518 --- bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC Thu Sep 6 20:54:58 2001
\r
519 +++ upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC Mon Dec 3 15:11:46 2001
\r
521 #define APSTUDIO_HIDDEN_SYMBOLS
\r
522 #include "windows.h"
\r
523 #undef APSTUDIO_HIDDEN_SYMBOLS
\r
524 -#include <.\sdrc.h>
\r
527 /////////////////////////////////////////////////////////////////////////////
\r
528 #undef APSTUDIO_READONLY_SYMBOLS
\r
529 diff -Nur --exclude-from=exclude bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep
\r
530 --- bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep Thu Sep 6 20:54:58 2001
\r
531 +++ upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep Wed Dec 31 16:00:00 1969
\r
533 -# Microsoft Developer Studio Generated Dependency File, included by _IsUser.mak
\r
538 diff -Nur --exclude-from=exclude bas/src/WINNT/afs_setup_utils/_isuser/ntmakefile upd/src/WINNT/afs_setup_utils/_isuser/ntmakefile
\r
539 --- bas/src/WINNT/afs_setup_utils/_isuser/ntmakefile Mon Sep 10 09:39:50 2001
\r
540 +++ upd/src/WINNT/afs_setup_utils/_isuser/ntmakefile Mon Dec 3 15:16:04 2001
\r
543 if not exist "$(OUTDIR)/$(NULL)" mkdir "$(OUTDIR)"
\r
545 -HEADERS = ".\sdrc.h"
\r
547 -".\sdrc.h" : $(IS5ROOT)\INCLUDE\sdrc.h
\r
548 - $(COPY) $(IS5ROOT)\INCLUDE\sdrc.h .
\r
549 -! IF EXIST($(IS5ROOT)\Script\ISRT\Include\sdrc.h)
\r
550 - $(COPY) $(IS5ROOT)\Script\ISRT\Include\sdrc.h .
\r
554 CPP_PROJ=/nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "_ISUSER_EXPORTS" /YX /Fo"$(INTDIR)\\" /Fd"$(INTDIR)\\" /FD /c
\r
556 @@ -85,20 +77,10 @@
\r
557 "$(INTDIR)\_isuser.obj" \
\r
558 "$(INTDIR)\_Isuser.res"
\r
560 -"$(OUTDIR)\_IsUser.dll" : "$(OUTDIR)" $(HEADERS) $(DEF_FILE) $(LINK32_OBJS)
\r
561 +"$(OUTDIR)\_IsUser.dll" : "$(OUTDIR)" $(DEF_FILE) $(LINK32_OBJS)
\r
563 $(LINK32_FLAGS) $(LINK32_OBJS)
\r
567 -!IF "$(NO_EXTERNAL_DEPS)" != "1"
\r
568 -!IF EXISTS("_IsUser.dep")
\r
569 -!INCLUDE "_IsUser.dep"
\r
571 -!MESSAGE Warning: cannot find "_IsUser.dep"
\r