[OpenAFS-devel] README-NT revision
Jeremy Stribling
jstribl@us.ibm.com
Tue, 8 Jan 2002 18:11:34 -0800
Below is a revised version to the README-NT document that James Peterson
posted to this mailing list a few weeks ago. The only major change in this
document is a new section on how to build a debugging environment. A patch
has been sent to Derrick Brashear for inclusion into the source tree.
Thanks,
Jeremy Stribling
----
This software has been released under the terms of the IBM Public
License. For details, see the LICENSE file in the top-level source
directory or on-line at http://www.openafs.org/dl/license10.html
The document now provides a step by step procedure that takes the user
from a basic Windows NT/2000 workstation to an OpenAFS development
environment. Details are provided so that a 'beginning' windows
developer can build an OpenAFS installable package for Windows NT/2000.
*********** Windows NT/2000 Build Process ****************
Building OpenAFS for Windows requires configuring a Windows
development system by installing compilation tools and header files.
Open AFS Software development can be done on Windows NT or 2000. The
target system, where OpenAFS will be installed, should be either
Windows NT or Windows 2000. The building process is controlled by a
nmake file that generates the necessary binaries and binds them into an
install package.
The following steps describe how to configure Windows 2000/NT:
A. Obtain a copy of the OpenAFS Source Tree
B. Install Compiler and Development tools.
C. Set up drive mappings.
D. Install SDK header files
E. Configure Environment variables
F. Set program version Level
G. Build Win2000 binaries
H. Install InstallShield 5.x
I. Build Win2000 InstallShield Package
J. Build Win2000 InstallShield Package for the Web
K. Final Results
L. Creating a Debug Environment
M. Optional Items
N. Required patches for 1.2.2a and earlier releases
The Software development tools with InstallShield require 900 MB
storage.
The Software development tools (without InstallShield) require 660 MB
storage.
The OpenAFS Source directory requires about 200 MB storage. The Source
directory size includes additional space for files that will be
generated during the build process.
The following CDs are used in this example:
Microsoft SDK and Tools Jan 2001
Microsoft Visual Studio Version 6.0
InstallShield 5.5
Different versions of above CDs can be used; however, building an
install package for Windows NT/2000 requires InstallShield
version 5.0 to 5.5 (version 6.0 or better will not work).
You can build all the necessary binaries without the InstallShield
software. InstallShield is only needed to build an install package.
STEP A. Obtain a copy of the Open AFS Source Tree.
Transfer OpenAFS source tree onto your hardrive. The source can be
downloaded from the OpenAFS web site:
http://www.OpenAFS.org/release/snapindex.html.
For this example, download source for version 1.2.2a using the
following URL:
http://www.openafs.org/dl/openafs/1.2.2a/openafs-1.2.2a-src.tar
HINT: DailySnapShots are pre-release source trees and much more
likely to have compilation errors. If this is your first attempt, do
your build based on a release version of the source, e.g. 1.2.2.a. Once
you have completed a build process successfully, you can experiment with
other source trees.
You will need an unzip utility that can expand compressed tar files.
For example "Pkzip for Windows" from Pkware will uncompress tar files.
(http://www.pkware.com/)
Expand the downloaded tar file (openafs-1.2.2a-src.tar) into target
directory (c:\OpenAFS), the unzip routine will expand the source into a
subdirectory tree:
c:\OpenAFS\OpenAFS-1.2.2a\src
Copy files NTMAKEFILE from 'src' to the AFS base directory:
From a DOS command prompt window, enter the following copy commands:
copy c:\OpenAFS\OpenAFS-1.2.2a\src\NTMAKEFILE c:\OpenAFS\OpenAFS-1.2.2a\.
The AFS base directory should look something like the following:
c:\OpenAFS\OpenAFS-1.2.2a\
NTMakefile
src
STEP B. Install compiler and development tools.
Install a copy of Microsoft Visual C++ 5.0 or 6.0. The "Typical" install
setting is sufficient.
(1) You can reduce the installation size by selecting "Custom" install
and remove all but the following Options:
Microsoft Visual C++
Data Access
(2) When asked, Select to Register Environment Variables.
(3) After rebooting you have to choice to install additional software
packages. It is not necessary to install these packages.
STEP C. Map development drive letters.
The following documentation will assume you are mapping the Y: drive to
the OpenAFS source directory and you are mapping X: drive to your
development tools directory. Other configurations will work, including
not mapping any drives, as long as the path assignments are consistent
and you don't exceed the maximum environment variable length.
Y: drive mapping provides a consistent directory location to build from.
Building OpenAFS will require you to open up a command DOS prompt,
navigate to drive Y: and execute the nmake file. The source is based
from Y: drive and the generated files are based from Y:\DEST. If the
OpenAFS
source tree is at a different location, you only need to re-map the
Y: drive.
X: drive mapping shortens the length of several Environment variables
by mapping it to a directory where Visual Studio is installed. Although
this step is not important when using Windows NT or 2000 as a
development OS, it does reduce the chance of typing errors during
the configuration phase.
From a DOS command window enter the following commands:
SUBST y: c:\OpenAFS\OpenAFS-1.2.2a
SUBST x: "c:\Program Files\Microsoft Visual Studio\VC98"
SUBST is persistent across DOS command prompts; that is, if you open up
another DOS command prompt the mapped drives are still defined.
However, if you reboot the mapped drives using SUBST will be lost.
If you need to remove Y: drive mapping, execute the following command
from a DOS command prompt window:
SUBST y: /d
STEP D. Install SDK header files.
Files from Microsoft's Platform SDK for NT or 98 are required to
complete a build on NT/2000.
The header files that are required are found from a Microsoft SDK are:
netspi.h
npapi.h
To Install Platform SDK from CDROM
Run "setup.exe default.htm" from CDROM:
Select Microsoft Core SDK
Select Sample and Source
Select installation path x:\SDK
To Install Windows SDK from WEB:
http://www.microsoft.com/sdk
STEP E. Configure the OpenAFS build environment.
The following environment variables should be set:
SET AFSDEV_LIB=%LIB%
SET AFSROOT=Y:
SET SYS_NAME=i386_nt40
SET _WIN32_IE=0x400
SET MSSDK=X:\Sdk
SET MSTOOLS=X:\Sdk
SET MSVCDIR=X:
SET AFSDEV_BIN=X:\BIN
SET AFSDEV_BUILDTYPE=FREE
SET AFSDEV_INCLUDE=X:\Sdk\samples\winbase\security\winnt\logonNP;X:
\Sdk\Include\ATL30;X:\Sdk\Include;%INCLUDE%
Please do not include unnecessary spaces in AFSDEV_INLCUDE.
Create a batch file (SETAFS.BAT) to make these settings that can be
executed when you bring up a DOS command prompt window. Environment
variables are not persistent, if you close the DOS command window
or reboot, the environment variables are lost and they must be
recreated when you open a new DOS command prompt window.
HINT: SET AFSDEV_BUILDTYPE=CHECKED if you want debug information
included in your binaries.
HINT: Adding drive mapping commands to the batch file makes it easy to
establish your development environment even if you logoff. I suggest
adding the following lines to the beginning of the batch file:
SUBST y: /d
SUBST x: /d
SUBST y: c:\OpenAfs\OpenAFS-1.2.2a
SUBST x: "c:\Program Files\Microsoft Visual Studio\VC98"
HINT: Windows 2000/NT provides an alternate way to set environment
variables in System Proprieties. These can be accessed from the system
control panel, advanced tab, Environment Variables. These are
persistent and will be reset every time a DOS command prompt window is
opened.
STEP F. Set version and installation options
Add a CellServDB file to install area. CellServDB contains the entries
for the various cell names. You can download a general purpose one
from:
http://grand.central.org/dl/cellservdb/CellServDB
then copy it to Y:\DEST\Wininstall\Config\CellServDB.GrandCentral
Note: Create directory Y:\DEST\Wininstall\Config\ if it doesn't exist.
Edit file Y:\src\config\NTMakefile.i386_nt40
AFSPRODUCT_VERSION - Product version
CELLSERVDB_INSTALL - The default file name for the CellServDB
included in the install Package.
CELLNAME_DEFAULT - The default home cell name.
CELLSERVDB_WEB - The default web address to obtain CellServDB
For example: in the file Y:\src\config\NTMakefile.i386_nt40 you would
see the following:
AFSPRODUCT_VERSION=1.2.2a
CELLNAME_DEFAULT=home.cell.com
CELLSERVDB_INSTALL=CellServDB.GrandCentral
CELLSERVDB_WEB=http://grand.central.org/dl/cellservdb/CellServDB
During the Open AFS installation process the user will be presented
with two choices for the CellServDB: Local copy (CELLSERVDB_INSTALL) and
one that can be downloaded from the web (CELLSERVDB_WEB).
HINT: The product version number (AFSPRODUCT_VERSION) can be changed to
create a new version number. For example if you have added source
changes to OpenAFS-1.2.2a and you wanted to create a new version level,
you may want to use the following: AFSPRODUCT_VERSION=1.2.2b
STEP G. Begin the build
(1) From Windows 2000 open up a DOS prompt window.
(2) Clean the work area.
nmake /f NTMakefile clean
(3) Build the complete Windows NT/2000 development environment.
nmake /f NTMakefile install
While the build is running you will see many compile warnings. This
behavior is normal; the build process is successful as long as the build
process doesn't terminate with an error ("nmake.exe return code 0x2")
and it displays 'Build Finished Successfully'.
STEP H. Install InstallShield (optional).
In order to build an install package for OpenAFS, InstallShield 5.5
must be installed along with InstallShield East and West
multi-Language packs.
(1) Install InstallShield (version between 5.0 and 5.5)
For minimum installation choose "compact".
(2) Install West Language Pack (5.5)
(3) Install East Language Pack (5.5)
NOTE: InstallShield's versions 6 and higher WILL NOT WORK for
Windows NT/2000 build process.
(4) Add necessary DLL's to work with the InstallShield package.
Two Microsoft DLL's are missing from the InstallShield package. These
DLL's must be copied to Y:\DEST\WinInstall\Config\:
SHLWAPI.DLL
WININET.DLL
These files are only used during the installation, and they will not
be left on the target machine. They can be located at
%SystemRoot%\SYSTEM32.
From a DOS command prompt window enter the following commands:
copy %systemRoot%\System32\SHLWAPI.DLL y:\dest\wininstall\config\.
copy %systemRoot%\System32\WININET.DLL y:\dest\wininstall\config\.
(5) Add two Environment variables to the bottom of the batch file,
SETAFS.BAT (see STEP E:).
SET IS5ROOT="C:\Program Files\InstallShield\InstallShield 5.5 Professional
Edition"
SET AFSDEV_INCLUDE=%AFSDEV_INCLUDE%;%IS5ROOT%\Include
STEP I. Build Win2000 InstallShield package
From the DOS command prompt window run:
Y:
nmake /f NTMakefile media
While the build is running you will see a few compile warnings. This
behavior is normal; the build process is successful as long as the build
process doesn't terminate with an error ("nmake.exe return code 0x2")
and it displays 'Install Script Finished Successfully'.
STEP J. Build Win2000 InstallShield package for the Web
InstallShield's PackageForTheWeb combines the installation files into a
single application file that will expand on execution and lead you
through the OpenAFS installation.
Install PackageForTheWeb 3 from InstallShield
Add Environment variables to the bottom of the batch file, SETAFS.BAT
(see STEP E:).
SET ISWEB="C:\Program Files\InstallShield\PackageForTheWeb 3"
From the DOS command prompt window run:
Y:
nmake /f NTMakefile media
While the build is running you will see a few compile warnings. This
behavior is normal; the build process is successful as long as the build
process doesn't terminate with an error ("nmake.exe return code 0x2") and
it displays 'Install Script Finished Successfully'.
HINT: It is only necessary to run "nmake /f NTMakefile media" once, by
combining steps I & J.
STEP K. Final Results
The build process generates its binaries in Y:\DEST. The subdirectory
would look like the following:
Y:\DEST
bin
etc
include
lib
root.client
root.server
WinInstall
Y:\DEST\Bin - contains build utilities.
Y:\DEST\root.client - contains Open AFS binaries
Y:\DEST\root.server - contain Open AFS Server binaries
Y:\DEST\WinInstall\PackageWeb\AFSforWindows.exe - is the Web install
package for Open AFS.
Y:\DEST\WinInstall\ - are the install package files for Open AFS
Step L. Creating a Debug Environment
Instructions on building a debugging environment from Visual Studio C++
workspace. This example give the user a way to step through the source
code for AFSCREDS.EXE.
These instructions are to be followed after you have set up the
development environment.
The following steps must be done before you can build a debug
environment:
1. Set up the development environment as described above
2. set AFS_BUILDTYPE=CHECKED to get debug information.
3. You must use environment variables in System Properties
4. Do a complete build.
To set the the environment variables in the System Properties:
1. Select the 'System' icon in the control Panel
2. Select the 'Advanced' tab
3. Select the 'Environment Variables' button
4. In the user area set all variables as you did above that
were used in the setafs.bat file.
To build a new work space to debug afs_creds.exe:
1. Create New Workspace -
Select from Microsoft Visual C++ toolbar file New
Select from 'new' Project Tab Makefile Project name: Creds
Location Y:\src\winnt\client_creds
Select OK
From Dialog Box 'Makefile - Step 1 of 2'
command line= nmake /f"ntmakefile" install
Output = y:\dest\root.client\usr\vice\etc\AFSCREDS.EXE
Select NEXT
Dialog Box 'Makefile - Step 2 of 2'
Command line= nmake /f"ntmakefile" install
Output = y:\dest\root.client\usr\vice\etc\AFSCREDS.EXE
Select Finish
Switch to FileView
Right click on 'Source Files' and select 'Add Files to folder', select
all *.cpp files.
Right click on 'Header Files' and select 'Add Files to folder', select
all *.h files.
Right click on 'creds files' and select 'New Folder'
Fill name in 'Build'
From the toolbar select Build
Select 'Build All'
You should see the following string when the compile is finished:
"afs_creds.exe - 0 errors(0), 0 warnings(s)"
Press <F5> to execute afs_creds.exe.
STEP M. Optional Items
The build process has an error table that is compiled for many OpenAFS
applications. This table is generated by Unix based tools. It is not
normally necessary to modify this table so pre-generated source files
are included in the OpenAFS source. If you need to make modifications
in these areas the Unix base tools that run on Windows can be found on
the web. For example:
http://cygwin.com/
Below is a short explanation how to update the error table.
(1) Install flex and bison from a Unix based tool provider.
(2) Make changes to the source files.
There are two files in the source tree that are processed with lex
and yacc on UNIX systems, src/comerr/et_lex.lex.l and
src/comerr/error_table.y, that when processed produce the files
et_lex.lex_nt.c, error_table_nt.c, and error_table_nt.h.
Since NT does not include lex and yacc or any equivalent tools, we
have provided the output files that lex and yacc produce (using Win32
ports of flex and bison). This will allow builds to work for anyone
who does not need to change the .l and .y files.
If you do need to change et_lex.lex.l, then you will need to install
Win32 port of flex on your system. Put flex.exe in a directory on the
path and rebuild.
If you do need to change error_table.y, then you will need to install
a Win32 port of bison on your system. Put bison.exe in a directory on
the path, configure bison as explained in step 5, and rebuild.
You can also attempt to use other replacements for lex and yacc. This
will require modifying the LEX and YACC settings in
/config/NTMakefile.i386_nt40. If the replacements require different
command line options than flex and bison, then you may also need to
change src/comerr/NTMakefile.
(3) Generate new OpenAFS binaries
STEP N. Required patches for 1.2.2a and earlier releases
There are two set of patches must be applied to 1.2.2a source to
successfully build the binaries:
(1) Patches applied to 1.2.2a to build binaries, excluding install
package.
diff -Nur --exclude-from=exclude bas/src/NTMakefile upd/src/NTMakefile
--- bas/src/NTMakefile Wed Nov 14 19:38:06 2001
+++ upd/src/NTMakefile Mon Dec 3 14:41:12 2001
@@ -471,6 +471,7 @@
$(CD) $(OBJ)\$@
$(NTMAKE)
$(CD) ..\..
+ echo Build Finished Successfully
install: start finale
@@ -487,6 +488,7 @@
$(CD) ..\..\..\..
media: InstallShield5
+ echo Install Script Finished Successfully
(2) Patches applied to 1.2.2a to build install package.
diff -Nur --exclude-from=exclude bas/src/WINNT/afsd/NTMakefile
upd/src/WINNT/afsd/NTMakefile
--- bas/src/WINNT/afsd/NTMakefile Tue Nov 20 22:45:40 2001
+++ upd/src/WINNT/afsd/NTMakefile Wed Dec 5 11:42:46 2001
@@ -169,8 +169,8 @@
$(EXEDIR)\tokens.exe \
$(EXEDIR)\unlog.exe $(EXEDIR)\afsd.exe $(EXEDIR)\afsd_service.exe \
$(EXEDIR)\fs.exe $(EXEDIR)\symlink.exe \
- $(LOGON_DLLFILE) $(LOG95_DLLFILE) \
- $(EXEDIR)\afsshare.exe \
+ $(LOGON_DLLFILE) \
+ $(EXEDIR)\afsshare.exe \
$(DESTDIR)\bin\kpasswd.exe
install9X: install_headers $(CONF_DLLFILE) \
diff -Nur --exclude-from=exclude
bas/src/WINNT/install/InstallShield5/NTMakefile
upd/src/WINNT/install/InstallShield5/NTMakefile
--- bas/src/WINNT/install/InstallShield5/NTMakefile Wed Nov 14 19:38:50
2001
+++ upd/src/WINNT/install/InstallShield5/NTMakefile Mon Dec 3 16:43:08
2001
@@ -60,7 +60,7 @@
$(MKDIR) $(DESTDIR)\Wininstall\PackageWeb
! ENDIF
$(DEL) /q $(DESTDIR)\Wininstall\PackageWeb\*.*
- $(ISWEB)\Pftwwiz.exe $(AFSROOT)
\src\winnt\install\InstallShield5\PackageWeb.pfw -s -a
+ "$(ISWEB)\Pftwwiz.exe" $(AFSROOT)
\src\winnt\install\InstallShield5\PackageWeb.pfw -s -a
!ENDIF
xcopy /s/e/y "Media\OpenAFS\Disk Images\disk1\*.*" $(DESTDIR)
\WinInstall
copy AFS_component_version_number.txt $(DESTDIR)
\WinInstall\Version.txt
diff -Nur --exclude-from=exclude
bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC
upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC
--- bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC Thu Sep 6 20:54:58
2001
+++ upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.RC Mon Dec 3 15:11:46
2001
@@ -10,7 +10,7 @@
#define APSTUDIO_HIDDEN_SYMBOLS
#include "windows.h"
#undef APSTUDIO_HIDDEN_SYMBOLS
-#include <.\sdrc.h>
+#include <sdrc.h>
/////////////////////////////////////////////////////////////////////////////
#undef APSTUDIO_READONLY_SYMBOLS
diff -Nur --exclude-from=exclude
bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep
upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep
--- bas/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep Thu Sep 6 20:54:58
2001
+++ upd/src/WINNT/afs_setup_utils/_isuser/_IsUser.dep Wed Dec 31 16:00:00
1969
@@ -1,5 +0,0 @@
-# Microsoft Developer Studio Generated Dependency File, included by
_IsUser.mak
-
-.\_Isuser.RC : \
- ".\sdrc.h"\
-
diff -Nur --exclude-from=exclude
bas/src/WINNT/afs_setup_utils/_isuser/ntmakefile
upd/src/WINNT/afs_setup_utils/_isuser/ntmakefile
--- bas/src/WINNT/afs_setup_utils/_isuser/ntmakefile Mon Sep 10 09:39:50
2001
+++ upd/src/WINNT/afs_setup_utils/_isuser/ntmakefile Mon Dec 3 15:16:04
2001
@@ -30,14 +30,6 @@
"$(OUTDIR)" ::
if not exist "$(OUTDIR)/$(NULL)" mkdir "$(OUTDIR)"
-HEADERS = ".\sdrc.h"
-
-".\sdrc.h" : $(IS5ROOT)\INCLUDE\sdrc.h
- $(COPY) $(IS5ROOT)\INCLUDE\sdrc.h .
-! IF EXIST($(IS5ROOT)\Script\ISRT\Include\sdrc.h)
- $(COPY) $(IS5ROOT)\Script\ISRT\Include\sdrc.h .
-! ENDIF
-
CPP=cl.exe
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
@@ -85,20 +77,10 @@
"$(INTDIR)\_isuser.obj" \
"$(INTDIR)\_Isuser.res"
-"$(OUTDIR)\_IsUser.dll" : "$(OUTDIR)" $(HEADERS) $(DEF_FILE)
$(LINK32_OBJS)
+"$(OUTDIR)\_IsUser.dll" : "$(OUTDIR)" $(DEF_FILE) $(LINK32_OBJS)
$(LINK32) @<<
$(LINK32_FLAGS) $(LINK32_OBJS)
<<
-
-
-!IF "$(NO_EXTERNAL_DEPS)" != "1"
-!IF EXISTS("_IsUser.dep")
-!INCLUDE "_IsUser.dep"
-!ELSE
-!MESSAGE Warning: cannot find "_IsUser.dep"
-!ENDIF
-!ENDIF
-
SOURCE=.\_isuser.c