Pull src/windows changes from krb5-1-1 branch (rename readme -> README)

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@11937 dc483132-0cff-0310-8789-dd5450dbe970

diff --git a/src/windows/README b/src/windows/README
new file mode 100644 (file)
index 0000000..c4c2f75
--- /dev/null
+++ b/src/windows/README
@@ -0,0 +1,132 @@
+              Building & Running Kerberos 5 on Windows
+              ----------------------------------------
+
+Kerberos 5 Windows support now only includes Win32 and no longer
+includes Win16.
+
+We build Kerberos 5 on Windows just with MSVC++ 6.0.  You should
+not need anything else.  We do not know whether it currently
+builds with other compilers or make utilities.
+
+These build instructions assume that you got a standalong source
+distribution of Kerberos 5 rather than the MIT Kerberos for Win32
+distribution (which includes a working Kerberos 4).
+
+There are two methods for building a Windows version of Kerberos 5.
+The traditional method involves starting on a Unix machine and
+creating a distribution that can be built on Windows.  The second
+method works from the sources that come from the Unix distribution if
+you have certain Unix-type utilities.
+
+
+Traditional Build Method:
+------------------------
+
+On the Unix side
+1) cd xxx/src                          # Go to where the source lives
+2) make -f Makefile.in kerbsrc.zip     # Do some Unix-side configuring
+                                       # ...and create kerbsrc.zip
+3) <transfer kerbsrc.zip to the PC>
+
+
+On the PC side
+1) md \krb5                            # Create where we'll put the tree
+2) cd \krb5
+3) unzip kerbsrc.zip
+        - or -
+   pkunzip -d kerbsrc.zip
+4) nmake -nologo                       # Build the sources
+5) nmake install                      # Copy headers, libs, executables
+
+
+All-Windows Build Method:
+------------------------
+
+First, make sure you have sed, gawk, cat, and cp.
+
+1) cd xxx/src                          # Go to where the source lives
+2) nmake -f Makefile.in prep-windows   # Create Makefile for Windows
+3) nmake -nologo                       # Build the sources
+4) nmake install                      # Copy headers, libs, executables
+
+
+Notes on the install Target:
+---------------------------
+
+For the install target, you will need to define KRB_INSTALL_DIR to
+point to the directory where the header, library, and executable files
+will be installed.  You can either define this in the environment or
+at the nmake command-line.  For example:
+
+nmake install KRB_INSTALL_DIR=c:\sdk\krb5
+
+Make sure you create the directory first.  Otherwise, nmake will
+complain.  The files will get installed into include, lib, and bin
+subdirectories.  You can then copy the binaries to where ever you want
+have them (probably somewhere in your path).
+
+
+Running Kerberos 5 Apps:
+-----------------------
+
+Make sure you have a valid krb5.ini file.  That will look just like a
+Unix krb5.conf file.  You can place this file in the same directory as
+your krb5_32.dll or in your Windows directory.  You should then be
+able to run the applications that are built.  Note that Kerberos 5
+will not look for the krb5.ini file in your path.
+
+
+Krb5.ini File:
+-------------
+
+WARNING: Despite its name, this is not a Windows .ini file.
+Therefore, do not try to use any .ini tools, including the Windows API
+or any installer tools to manipulate this file.  Its format is subtly
+different from Windows .ini files!
+
+
+Controlling the Kerberos 5 Run-Time Environment:
+-----------------------------------------------
+
+The Kerberos 5 configuration file and credentials cache can be
+controlled with environment variables and registry settings.  The
+environment variable for a particular setting always takes precedence.
+Next in precedence comes the setting in the registry under
+HKEY_CURRENT_USER\Software\MIT\Kerberos5.  Then comes the registry
+setting under HKEY_LOCAL_MACHINE\Software\MIT\Kerberos5.  If none of
+those are found, a default value is used.
+
+Configuration File:
+- Environment: KRB5_CONFIG
+- Registry Value: config
+- Default: looks in krb5_32.dll's dir and Windows directory
+
+Default Credentials Cache:
+- Environment: KRB5CCNAME
+- Registry Value: ccname
+- Default: API:krb5cc or FILE:%TEMP%\krb5cc or FILE:<windows dir>\krb5cc
+
+
+Credentials Cache:
+-----------------
+
+In addition to standard FILE: (disk file) and MEMORY: (in-process
+non-shared memory) Windows supports the API: cache type, which is a
+shared memory cache.  This is implemented by krbcc32.dll, which is not
+included the the krb5-only distribution.  Rather, it is part of MIT's
+Kerberos for Win32 suite.
+
+
+Othes Issues:
+------------
+
+The krb4_32.dll that is built (but not installed) is not supported.
+If you need Kerberos 4, you can use the krbv4w32.dll that MIT
+distributes as part of the MIT Kerberos for Win32 distribution.
+
+
+More Information:
+----------------
+
+For more information, please read the Kerberos 5 documentation in
+the doc directory of the distribution.