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
5 The document now provides a step by step procedure that takes the user
6 from a basic Windows NT/2000 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 NT/2000.
10 *********** Windows NT/2000 Build Process ****************
12 Building OpenAFS for Windows requires configuring a Windows
13 development system by installing compilation tools and header files.
14 Open AFS Software development can be done on Windows NT or 2000. The
15 target system, where OpenAFS will be installed, should be either
16 Windows NT or Windows 2000. The building process is controlled by a
17 nmake file that generates the necessary binaries and binds them into an
20 The following steps describe how to configure Windows 2000/NT:
22 A. Obtain a copy of the OpenAFS Source Tree
23 B. Install Compiler and Development tools.
24 C. Set up drive mappings.
25 D. Install SDK header files
26 E. Configure Environment variables
27 F. Set program version Level
28 G. Build Win2000 binaries
29 H. Install InstallShield 5.x
30 I. Build Win2000 InstallShield Package
31 J. Build Win2000 InstallShield Package for the Web
33 L. Creating a Debug Environment
35 N. Required patches for 1.2.2a and earlier releases
37 The Software development tools with InstallShield require 900 MB
40 The Software development tools (without InstallShield) require 660 MB
43 The OpenAFS Source directory requires about 200 MB storage. The Source
44 directory size includes additional space for files that will be
45 generated during the build process.
47 The following CDs are used in this example:
48 Microsoft SDK and Tools Jan 2001
49 Microsoft Visual Studio Version 6.0
52 Different versions of above CDs can be used; however, building an
53 install package for Windows NT/2000 requires InstallShield
54 version 5.0 to 5.5 (version 6.0 or better will not work).
56 You can build all the necessary binaries without the InstallShield
57 software. InstallShield is only needed to build an install package.
59 STEP A. Obtain a copy of the Open AFS Source Tree.
61 Transfer OpenAFS source tree onto your hardrive. The source can be
62 downloaded from the OpenAFS web site:
63 http://www.OpenAFS.org/release/snapindex.html.
65 For this example, download source for version 1.2.2a using the
67 http://www.openafs.org/dl/openafs/1.2.2a/openafs-1.2.2a-src.tar
69 HINT: DailySnapShots are pre-release source trees and much more
70 likely to have compilation errors. If this is your first attempt, do
71 your build based on a release version of the source, e.g. 1.2.2.a. Once
72 you have completed a build process successfully, you can experiment with
75 You will need an unzip utility that can expand compressed tar files.
76 For example "Pkzip for Windows" from Pkware will uncompress tar files.
77 (http://www.pkware.com/)
79 Expand the downloaded tar file (openafs-1.2.2a-src.tar) into target
80 directory (c:\OpenAFS), the unzip routine will expand the source into a
82 c:\OpenAFS\OpenAFS-1.2.2a\src
84 Copy files NTMAKEFILE from 'src' to the AFS base directory:
86 From a DOS command prompt window, enter the following copy commands:
88 copy c:\OpenAFS\OpenAFS-1.2.2a\src\NTMAKEFILE c:\OpenAFS\OpenAFS-1.2.2a\.
90 The AFS base directory should look something like the following:
92 c:\OpenAFS\OpenAFS-1.2.2a\
96 STEP B. Install compiler and development tools.
98 Install a copy of Microsoft Visual C++ 5.0 or 6.0. The "Typical" install
99 setting is sufficient.
101 (1) You can reduce the installation size by selecting "Custom" install
102 and remove all but the following Options:
107 (2) When asked, Select to Register Environment Variables.
109 (3) After rebooting you have to choice to install additional software
110 packages. It is not necessary to install these packages.
112 STEP C. Map development drive letters.
114 The following documentation will assume you are mapping the Y: drive to
115 the OpenAFS source directory and you are mapping X: drive to your
116 development tools directory. Other configurations will work, including
117 not mapping any drives, as long as the path assignments are consistent
118 and you don't exceed the maximum environment variable length.
120 Y: drive mapping provides a consistent directory location to build from.
121 Building OpenAFS will require you to open up a command DOS prompt,
122 navigate to drive Y: and execute the nmake file. The source is based
123 from Y: drive and the generated files are based from Y:\DEST. If the OpenAFS
124 source tree is at a different location, you only need to re-map the
127 X: drive mapping shortens the length of several Environment variables
128 by mapping it to a directory where Visual Studio is installed. Although
129 this step is not important when using Windows NT or 2000 as a
130 development OS, it does reduce the chance of typing errors during
131 the configuration phase.
133 From a DOS command window enter the following commands:
135 SUBST y: c:\OpenAFS\OpenAFS-1.2.2a
136 SUBST x: "c:\Program Files\Microsoft Visual Studio\VC98"
138 SUBST is persistent across DOS command prompts; that is, if you open up
139 another DOS command prompt the mapped drives are still defined.
140 However, if you reboot the mapped drives using SUBST will be lost.
142 If you need to remove Y: drive mapping, execute the following command
143 from a DOS command prompt window:
147 STEP D. Install SDK header files.
149 Files from Microsoft's Platform SDK for NT or 98 are required to
150 complete a build on NT/2000.
152 The header files that are required are found from a Microsoft SDK are:
157 These files come from Microsoft DDKs/SDKs as follows:
159 January 1997 Windows NT Workstation DDK - /ddk/frc/network/inc/npapi.h
160 November 2001 Microsoft Platform SDK - install "samples" from "Core SDK"
161 samples/winbase/security/winnt/logonnp/npapi.h
162 July 1998 Windows 95 DDK - net/inc/netmpr.h and net/inc/netspi.h
163 July 1999 Windows 98 DDK - src/net/inc/netmpr.h and src/net/inc/netspi.h
164 - you need to install "Legacy and Related
167 To Install Platform SDK from CDROM
169 Run "setup.exe default.htm" from CDROM:
170 Select Microsoft Core SDK
171 Select Sample and Source
172 Select installation path x:\SDK
174 To Install Windows SDK from WEB:
175 http://www.microsoft.com/sdk
177 STEP E. Configure the OpenAFS build environment.
179 The following environment variables should be set:
183 SET SYS_NAME=i386_nt40
188 SET AFSDEV_BIN=X:\BIN
189 SET AFSDEV_BUILDTYPE=FREE
190 SET AFSDEV_INCLUDE=X:\Sdk\samples\winbase\security\winnt\logonNP;X:\Sdk\Include\ATL30;X:\Sdk\Include;%INCLUDE%
192 Please do not include unnecessary spaces in AFSDEV_INLCUDE.
194 Create a batch file (SETAFS.BAT) to make these settings that can be
195 executed when you bring up a DOS command prompt window. Environment
196 variables are not persistent, if you close the DOS command window
197 or reboot, the environment variables are lost and they must be
198 recreated when you open a new DOS command prompt window.
200 HINT: SET AFSDEV_BUILDTYPE=CHECKED if you want debug information
201 included in your binaries.
203 HINT: Adding drive mapping commands to the batch file makes it easy to
204 establish your development environment even if you logoff. I suggest
205 adding the following lines to the beginning of the batch file:
209 SUBST y: c:\OpenAfs\OpenAFS-1.2.2a
210 SUBST x: "c:\Program Files\Microsoft Visual Studio\VC98"
212 HINT: Windows 2000/NT provides an alternate way to set environment
213 variables in System Proprieties. These can be accessed from the system
214 control panel, advanced tab, Environment Variables. These are
215 persistent and will be reset every time a DOS command prompt window is
218 STEP F. Set version and installation options
220 Add a CellServDB file to install area. CellServDB contains the entries
221 for the various cell names. You can download a general purpose one
223 http://grand.central.org/dl/cellservdb/CellServDB
224 then copy it to Y:\DEST\Wininstall\Config\CellServDB.GrandCentral
226 Note: Create directory Y:\DEST\Wininstall\Config\ if it doesn't exist.
228 Edit file Y:\src\config\NTMakefile.i386_nt40
229 AFSPRODUCT_VERSION - Product version
230 CELLSERVDB_INSTALL - The default file name for the CellServDB
231 included in the install Package.
232 CELLNAME_DEFAULT - The default home cell name.
233 CELLSERVDB_WEB - The default web address to obtain CellServDB
235 For example: in the file Y:\src\config\NTMakefile.i386_nt40 you would
238 AFSPRODUCT_VERSION=1.2.2a
239 CELLNAME_DEFAULT=home.cell.com
240 CELLSERVDB_INSTALL=CellServDB.GrandCentral
241 CELLSERVDB_WEB=http://grand.central.org/dl/cellservdb/CellServDB
243 During the Open AFS installation process the user will be presented
244 with two choices for the CellServDB: Local copy (CELLSERVDB_INSTALL) and
245 one that can be downloaded from the web (CELLSERVDB_WEB).
247 HINT: The product version number (AFSPRODUCT_VERSION) can be changed to
248 create a new version number. For example if you have added source
249 changes to OpenAFS-1.2.2a and you wanted to create a new version level,
250 you may want to use the following: AFSPRODUCT_VERSION=1.2.2b
252 STEP G. Begin the build
254 (1) From Windows 2000 open up a DOS prompt window.
256 (2) Clean the work area.
258 nmake /f NTMakefile clean
260 (3) Build the complete Windows NT/2000 development environment.
262 nmake /f NTMakefile install
264 While the build is running you will see many compile warnings. This
265 behavior is normal; the build process is successful as long as the build
266 process doesn't terminate with an error ("nmake.exe return code 0x2")
267 and it displays 'Build Finished Successfully'.
269 STEP H. Install InstallShield (optional).
271 In order to build an install package for OpenAFS, InstallShield 5.5
272 must be installed along with InstallShield East and West
273 multi-Language packs.
275 (1) Install InstallShield (version between 5.0 and 5.5)
277 For minimum installation choose "compact".
279 (2) Install West Language Pack (5.5)
281 (3) Install East Language Pack (5.5)
283 NOTE: InstallShield's versions 6 and higher WILL NOT WORK for
284 Windows NT/2000 build process.
286 (4) Add necessary DLL's to work with the InstallShield package.
288 Two Microsoft DLL's are missing from the InstallShield package. These
289 DLL's must be copied to Y:\DEST\WinInstall\Config\:
293 These files are only used during the installation, and they will not
294 be left on the target machine. They can be located at
295 %SystemRoot%\SYSTEM32.
297 From a DOS command prompt window enter the following commands:
299 copy %systemRoot%\System32\SHLWAPI.DLL y:\dest\wininstall\config\.
300 copy %systemRoot%\System32\WININET.DLL y:\dest\wininstall\config\.
302 (5) Add two Environment variables to the bottom of the batch file,
303 SETAFS.BAT (see STEP E:).
305 SET IS5ROOT="C:\Program Files\InstallShield\InstallShield 5.5 Professional Edition"
306 SET AFSDEV_INCLUDE=%AFSDEV_INCLUDE%;%IS5ROOT%\Include
308 STEP I. Build Win2000 InstallShield package
310 From the DOS command prompt window run:
313 nmake /f NTMakefile media
315 While the build is running you will see a few compile warnings. This
316 behavior is normal; the build process is successful as long as the build
317 process doesn't terminate with an error ("nmake.exe return code 0x2")
318 and it displays 'Install Script Finished Successfully'.
320 STEP J. Build Win2000 InstallShield package for the Web
322 InstallShield's PackageForTheWeb combines the installation files into a
323 single application file that will expand on execution and lead you
324 through the OpenAFS installation.
326 Install PackageForTheWeb 3 from InstallShield
328 Add Environment variables to the bottom of the batch file, SETAFS.BAT
331 SET ISWEB="C:\Program Files\InstallShield\PackageForTheWeb 3"
333 From the DOS command prompt window run:
336 nmake /f NTMakefile media
338 While the build is running you will see a few compile warnings. This
339 behavior is normal; the build process is successful as long as the build
340 process doesn't terminate with an error ("nmake.exe return code 0x2") and
341 it displays 'Install Script Finished Successfully'.
343 HINT: It is only necessary to run "nmake /f NTMakefile media" once, by
344 combining steps I & J.
346 STEP K. Final Results
348 The build process generates its binaries in Y:\DEST. The subdirectory
349 would look like the following:
360 Y:\DEST\Bin - contains build utilities.
361 Y:\DEST\root.client - contains Open AFS binaries
362 Y:\DEST\root.server - contain Open AFS Server binaries
363 Y:\DEST\WinInstall\PackageWeb\AFSforWindows.exe - is the Web install
364 package for Open AFS.
365 Y:\DEST\WinInstall\ - are the install package files for Open AFS
367 Step L. Creating a Debug Environment
369 Instructions on building a debugging environment from Visual Studio C++
370 workspace. This example give the user a way to step through the source
371 code for AFSCREDS.EXE.
373 These instructions are to be followed after you have set up the
374 development environment.
376 The following steps must be done before you can build a debug
379 1. Set up the development environment as described above
380 2. set AFS_BUILDTYPE=CHECKED to get debug information.
381 3. You must use environment variables in System Properties
382 4. Do a complete build.
384 To set the the environment variables in the System Properties:
385 1. Select the 'System' icon in the control Panel
386 2. Select the 'Advanced' tab
387 3. Select the 'Environment Variables' button
388 4. In the user area set all variables as you did above that
389 were used in the setafs.bat file.
391 To build a new work space to debug afs_creds.exe:
393 1. Create New Workspace -
394 Select from Microsoft Visual C++ toolbar file New
395 Select from 'new' Project Tab Makefile Project name: Creds
396 Location Y:\src\winnt\client_creds
399 From Dialog Box 'Makefile - Step 1 of 2'
400 command line= nmake /f"ntmakefile" install
401 Output = y:\dest\root.client\usr\vice\etc\AFSCREDS.EXE
404 Dialog Box 'Makefile - Step 2 of 2'
405 Command line= nmake /f"ntmakefile" install
406 Output = y:\dest\root.client\usr\vice\etc\AFSCREDS.EXE
411 Right click on 'Source Files' and select 'Add Files to folder', select
414 Right click on 'Header Files' and select 'Add Files to folder', select
417 Right click on 'creds files' and select 'New Folder'
420 From the toolbar select Build
423 You should see the following string when the compile is finished:
424 "afs_creds.exe - 0 errors(0), 0 warnings(s)"
426 Press <F5> to execute afs_creds.exe.
428 STEP M. Optional Items
430 The build process has an error table that is compiled for many OpenAFS
431 applications. This table is generated by Unix based tools. It is not
432 normally necessary to modify this table so pre-generated source files
433 are included in the OpenAFS source. If you need to make modifications
434 in these areas the Unix base tools that run on Windows can be found on
435 the web. For example:
439 Below is a short explanation how to update the error table.
441 (1) Install flex and bison from a Unix based tool provider.
443 (2) Make changes to the source files.
445 There are two files in the source tree that are processed with lex
446 and yacc on UNIX systems, src/comerr/et_lex.lex.l and
447 src/comerr/error_table.y, that when processed produce the files
448 et_lex.lex_nt.c, error_table_nt.c, and error_table_nt.h.
450 Since NT does not include lex and yacc or any equivalent tools, we
451 have provided the output files that lex and yacc produce (using Win32
452 ports of flex and bison). This will allow builds to work for anyone
453 who does not need to change the .l and .y files.
455 If you do need to change et_lex.lex.l, then you will need to install
456 Win32 port of flex on your system. Put flex.exe in a directory on the
459 If you do need to change error_table.y, then you will need to install
460 a Win32 port of bison on your system. Put bison.exe in a directory on
461 the path, configure bison as explained in step 5, and rebuild.
463 You can also attempt to use other replacements for lex and yacc. This
464 will require modifying the LEX and YACC settings in
465 /config/NTMakefile.i386_nt40. If the replacements require different
466 command line options than flex and bison, then you may also need to
467 change src/comerr/NTMakefile.
469 (3) Generate new OpenAFS binaries
472 STEP N. Required patches for 1.2.2a and earlier releases
474 There are two set of patches must be applied to 1.2.2a source to
475 successfully build the binaries:
477 (1) Patches applied to 1.2.2a to build binaries, excluding install
480 diff -Nur --exclude-from=exclude bas/src/NTMakefile upd/src/NTMakefile
481 --- bas/src/NTMakefile Wed Nov 14 19:38:06 2001
482 +++ upd/src/NTMakefile Mon Dec 3 14:41:12 2001
487 + echo Build Finished Successfully
489 install: start finale
494 media: InstallShield5
495 + echo Install Script Finished Successfully
498 (2) Patches applied to 1.2.2a to build install package.
500 diff -Nur --exclude-from=exclude bas/src/WINNT/afsd/NTMakefile upd/src/WINNT/afsd/NTMakefile
501 --- bas/src/WINNT/afsd/NTMakefile Tue Nov 20 22:45:40 2001
502 +++ upd/src/WINNT/afsd/NTMakefile Wed Dec 5 11:42:46 2001
504 $(EXEDIR)\tokens.exe \
505 $(EXEDIR)\unlog.exe $(EXEDIR)\afsd.exe $(EXEDIR)\afsd_service.exe \
506 $(EXEDIR)\fs.exe $(EXEDIR)\symlink.exe \
507 - $(LOGON_DLLFILE) $(LOG95_DLLFILE) \
508 - $(EXEDIR)\afsshare.exe \
510 + $(EXEDIR)\afsshare.exe \
511 $(DESTDIR)\bin\kpasswd.exe
513 install9X: install_headers $(CONF_DLLFILE) \
515 diff -Nur --exclude-from=exclude bas/src/WINNT/install/InstallShield5/NTMakefile upd/src/WINNT/install/InstallShield5/NTMakefile
516 --- bas/src/WINNT/install/InstallShield5/NTMakefile Wed Nov 14 19:38:50 2001
517 +++ upd/src/WINNT/install/InstallShield5/NTMakefile Mon Dec 3 16:43:08 2001
519 $(MKDIR) $(DESTDIR)\Wininstall\PackageWeb
521 $(DEL) /q $(DESTDIR)\Wininstall\PackageWeb\*.*
522 - $(ISWEB)\Pftwwiz.exe $(AFSROOT)\src\winnt\install\InstallShield5\PackageWeb.pfw -s -a
523 + "$(ISWEB)\Pftwwiz.exe" $(AFSROOT)\src\winnt\install\InstallShield5\PackageWeb.pfw -s -a
525 xcopy /s/e/y "Media\OpenAFS\Disk Images\disk1\*.*" $(DESTDIR)\WinInstall
526 copy AFS_component_version_number.txt $(DESTDIR)\WinInstall\Version.txt
527 diff -Nur --exclude-from=exclude bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC
528 --- bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC Thu Sep 6 20:54:58 2001
529 +++ upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC Mon Dec 3 15:11:46 2001
531 #define APSTUDIO_HIDDEN_SYMBOLS
533 #undef APSTUDIO_HIDDEN_SYMBOLS
537 /////////////////////////////////////////////////////////////////////////////
538 #undef APSTUDIO_READONLY_SYMBOLS
539 diff -Nur --exclude-from=exclude bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep
540 --- bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep Thu Sep 6 20:54:58 2001
541 +++ upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep Wed Dec 31 16:00:00 1969
543 -# Microsoft Developer Studio Generated Dependency File, included by _IsUser.mak
548 diff -Nur --exclude-from=exclude bas/src/WINNT/afs_setup_utils/_isuser/ntmakefile upd/src/WINNT/afs_setup_utils/_isuser/ntmakefile
549 --- bas/src/WINNT/afs_setup_utils/_isuser/ntmakefile Mon Sep 10 09:39:50 2001
550 +++ upd/src/WINNT/afs_setup_utils/_isuser/ntmakefile Mon Dec 3 15:16:04 2001
553 if not exist "$(OUTDIR)/$(NULL)" mkdir "$(OUTDIR)"
555 -HEADERS = ".\sdrc.h"
557 -".\sdrc.h" : $(IS5ROOT)\INCLUDE\sdrc.h
558 - $(COPY) $(IS5ROOT)\INCLUDE\sdrc.h .
559 -! IF EXIST($(IS5ROOT)\Script\ISRT\Include\sdrc.h)
560 - $(COPY) $(IS5ROOT)\Script\ISRT\Include\sdrc.h .
564 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
567 "$(INTDIR)\_isuser.obj" \
568 "$(INTDIR)\_Isuser.res"
570 -"$(OUTDIR)\_IsUser.dll" : "$(OUTDIR)" $(HEADERS) $(DEF_FILE) $(LINK32_OBJS)
571 +"$(OUTDIR)\_IsUser.dll" : "$(OUTDIR)" $(DEF_FILE) $(LINK32_OBJS)
573 $(LINK32_FLAGS) $(LINK32_OBJS)
577 -!IF "$(NO_EXTERNAL_DEPS)" != "1"
578 -!IF EXISTS("_IsUser.dep")
579 -!INCLUDE "_IsUser.dep"
581 -!MESSAGE Warning: cannot find "_IsUser.dep"