[OpenAFS-devel] new README-NT

[Lawrence Greenfield]

--Multipart_Wed_Jan_15_13:59:04_2003-1
Content-Type: text/plain; charset=US-ASCII

I've updated README-NT with instructions that seem to be simplier and
work better. I'll commit this unless someone has any objection. I've
attached it for review.

I'd also like people's opinion on whether it would be better to format
it in HTML or not.

I didn't touch the "making the installer" bit. I think we need to move
towards an MSI method that's somewhat easier for people to understand.

Also, there's currently a slightly lie that VS7 will work, which is
won't. As far as I know, the main problem with VS7 is the 64-bit
code. I'll try to commit a workaround that will work for both VS7 and
VS6.

thanks,
Larry


--Multipart_Wed_Jan_15_13:59:04_2003-1
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="README-NT"
Content-Transfer-Encoding: 7bit

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, 2000, or XP.
The target system, where OpenAFS will be installed, should be either
Windows NT, Windows 2000, or Windows XP.  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

We believe that the latest Microsoft SDK (as of this writing, July
2002) and Visual Studio .NET (aka Visual Studio 7) will work.

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\src

The AFS base directory should look something like the following:

c:\OpenAFS
  configure
  src
  doc
    ...
	  
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.

[this step is no longer needed, we believe]

STEP D. Install SDK header files.

If you have an older version of the SDK or you are compiling to target
Win9x, you may need to track down some additional header files.

The header files that are required are found from a Microsoft SDK are:

   netspi.h
	netspi.h is needed only for Win9x builds.
   npapi.h
	Npapi.h is included in the July 2002 SDK

These files come from Microsoft DDKs/SDKs as follows:

   January 1997 Windows NT Workstation DDK - /ddk/frc/network/inc/npapi.h
   November 2001 Microsoft Platform SDK - install "samples" from "Core SDK"
                              samples/winbase/security/winnt/logonnp/npapi.h
   July 1998 Windows 95 DDK - net/inc/netmpr.h and net/inc/netspi.h
   July 1999 Windows 98 DDK - src/net/inc/netmpr.h and src/net/inc/netspi.h
                            - you need to install "Legacy and Related
                              driver samples"

To Install Windows SDK from WEB:
	http://www.microsoft.com/sdk

STEP E. Configure the OpenAFS build environment.

Edit C:\OpenAFS\src\ntbuild.bat to conform to where you unzipped the
sources.

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 C:\OpenAFS\DEST\Wininstall\Config\CellServDB.GrandCentral

Note: Create directory C:\OpenAFS\DEST\Wininstall\Config\ if it
doesn't exist.

Edit file C:\OpenAFS\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 C:\OpenAFS\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.

    Using the Platform SDK "open build environment" may be easiest.
    The build appears to work with the "Windows 2000 Build
    Environment" but does not work with the "Windows XP 32-bit Build
    Environment".

(2) Change to the OpenAFS src area.

    cd c:\OpenAFS

(3) Copy file 'NTMAKEFILE' from 'src' to the AFS base directory:

    copy src\NTMAKEFILE .

(4) Run ntbuild.bat to set environment variables.

    src\ntbuild.bat

(5) 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 C:\OpenAFS\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 c:\OpenAFS\dest\wininstall\config\.
copy %systemRoot%\System32\WININET.DLL c:\OpenAFS\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:

     c:
     cd \OpenAFS
     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:

     c:
     cd \OpenAFS
     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 C:\OpenAFS\DEST. The
subdirectory would look like the following:

C:\OpenAFS\DEST
	bin
	etc
	include
	lib
	root.client
	root.server
	WinInstall

C:\OpenAFS\DEST\Bin - contains build utilities.
C:\OpenAFS\DEST\root.client - contains Open AFS binaries
C:\OpenAFS\DEST\root.server - contain Open AFS Server binaries
C:\OpenAFS\DEST\WinInstall\PackageWeb\AFSforWindows.exe - is the Web install
package for Open AFS.
C:\OpenAFS\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 C:\OpenAFS\src\winnt\client_creds
Select OK

From Dialog Box 'Makefile - Step 1 of 2'
command line= nmake /f"ntmakefile" install
Output = C:\OpenAFS\dest\root.client\usr\vice\etc\AFSCREDS.EXE
Select NEXT

Dialog Box 'Makefile - Step 2 of 2'
Command line= nmake /f"ntmakefile" install
Output = C:\OpenAFS\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

--Multipart_Wed_Jan_15_13:59:04_2003-1--