Compiling PRODUCT
*****************

PRODUCT is supplied in source form for a number of reasons:

  * You can examine the source yourself, and verify the behavior of the system to your satisfaction.  This is especially important with security software.

  * You can make your own changes (of course, we recommend having us make the changes, so that we can support them in the future.)

PRODUCT is a large package.  In order to efficiently manage sources across a large number of platforms, we've used certain tools that you may be unfamilar with, and we explain them here.

Requirements
============

At the very minimum, you need a Unix-like operating system with a C compiler.  (The MacOS and Windows ports are not discussed here.)  While an ANSI C compiler is preferred, mostly because it is likely to be a more recent compiler, the build process checks for particular features and works around them in most cases.  We of course recommend gcc, but we test the compilation with both gcc and the "native" or OS-vendor supplied compiler whenever possible.

You also need a version of make.  We recommend GNU make, but again, we test with the vendor-supplied one as well.  Most native implementations of make are sufficient to build PRODUCT directly in the source tree.  Having a seperate build tree is far more convenient, and is what we recommend; this usually needs GNU make because of the variation in support of VPATH.

If you're only going to compile the unchanged source, or are only going to change C files, you should be set.  If you're going to change some part of the build process (any of the Makefiles---more specifically, any of the configure.in or Makefile.in files that generate them) you're going to need a recent version of GNU m4.

Setup
=====

We recommend a directory structure as follows:

krb5
     is the source tree itself.

src
     is a symlink farm pointing into the source tree.

PLATFORM
     is a directory for a particular build platform.  It may be more convenient for you to name these by hostname, but if you're keeping the trees around for any length of time it is better to label them by vendor and version.

Given the above structure, unpack the tar file of sources.

If you don't have GNU m4, or are not planning to change anything, simply

             mv krb5 src

If you are likely to be changing build-related information, then the procedure

             % mkdir src
             % cd src
             % ../krb5/util/lndir ../krb5

will produce the symlink farm, then

             % rm Makefile
             % cd util/autoconf
             % ./configure
             % make
             % cd ../..
             % util/reconf
             % cd ..

The reconf step will take a while, as it regenerates the build scripts. If you change aclocal.m4, Makefile.in, or configure.in, you can rerun util/reconf (causing it to rebuild only those things that need to.) If you're just making changes to a Makefile.in or configure.in in one directory, the make rules will take care of rerunning autoconf to rebuild them directly.

In order to build a particular platform, simply

             % mkdir platform
             % cd platform
             % ../src/configure --CONFIGURE OPTIONS
             % make all {MAKE OPTIONS}
             % make check
             % make install

If cc isn't a working compiler (stock Solaris, for example) you should also do a

             setenv CC gcc

before running configure.

Make Options
------------

MAKE OPTIONS include

  * CC=COMPILER

  * CCOPTS=COMPILER FLAGS

which get automatically propagated to all subdirectories.

Configure Options
-----------------

CONFIGURE OPTIONS include

--with-dbm
     Use native dbm for the key database.

--without-dbm
     Use included version of Berkeley db.  This is the default, but not yet recommended.  In a future release, after db is more thoroughly tested, a conversion tool will be supplied.

--with-dbm-lname
     Use native dbm for aname to lname conversion database.  This optional database is most useful when users have principals in multiple realms that have common access.

--without-dbm-lname
     Use included version of Berkeley db.  This is the default, but not yet recommended.  In a future release, after db is more thoroughly tested, a conversion tool will be supplied.

--enable-athena
     If V4 compatibility is also enabled (the default), construct kadmin.v4, the PRODUCT V4 compatible Kerberos Administration Server, and krb524, the conversion tools to allow users to generate V4 tickets from V5 tickets.

     It also causes KRB5_ATHENA_COMPAT to be defined, which may have affects in future releases, but is currently unused.

--prefix PATHNAME
     Specify that the installed tree be rooted at PATHNAME.  The MIT default is to use /krb5 but

--without-krb4
     Don't include any Kerberos V4 backwards compatibility support in applications, and don't build the V4 libraries either.

--with-krb4
     PRODUCT V4 libraries (enhanced for compatibility use) are included as part of the PRODUCT V5 source tree.  By default, or with this option, these are built and installed in libkrb4.a and are used in various utilities.

--with-krb4=KRB4DIR
     Enable V4 backwards compatibility support, but use existing Kerberos libraries as preinstalled in KRB4DIR.  Generally not used now that the V4 libraries are included.

--with-cc=COMPILER
     Select compiler to use, and write it into the constructed Makefiles as the default value of CC.

--with-linker=LINKER
     Select linker to use, and write it into the constructed Makefiles as the default value of LD.  Useful for building with Purify.

--with-ccopts=CCOPTS
     Select compiler command line options, and write it into the constructed Makefiles as the default value of CCOPTS.  Useful for building with debugging or optimization.

--with-cppopts=CPPOPTS
     Select compiler preprocessor command line options, and write it into the constructed Makefiles as the default value of CPPOPTS. Useful for setting flags.

--with-netlib=LIBS
     Use user defined resolve library.  Normally the resolver is part of the C library, but on SunOS systems using NIS, you may need to specify -lresolv in order to get a proper domain name resolver.

--enable-shared
     Construct PRODUCT V5 shared libraries.  Not supported on all systems.

--with-shared
     Use constructed shared (default) libraries.

--without-shared
     Don't use any shared libraries when building PRODUCT.

--without-afs
     The default, indicating that you don't have afs libraries to build with and therefore can't to build asetkey, aklog, and kascvt.

--with-afs=AFSDIR
     Use preinstalled AFS library tree located under AFSDIR to build the TransArc AFS support and conversion tools.  These require V4 compatibility to operate, and work in conjunction with krb524d.

--enable-telnet-encryption
     Use non-standard encryption in telnet.  The telnet implementation provides for the use of DES in a stream mode to encrypt the connection, but there are some user interface issues that may make it less safe. Always verify using ^[ enc status RET that it was successful, rather than trusting the message which may have been inserted by an attacker.  For this and other reasons, the encryption mode is not an Internet Standard as of October 1995, but work is expected in the coming year to change that.

--disable-telnet-encryption
     Don't enable the non-standard telnet encryption mode described above.

Testing
=======

After running make all successfully, you should run the collection of built in test cases.  Running make check will run a number of built in tests of

  * raw database code

  * raw encryption code

  * various Kerberos V5 interfaces including kdb5

If you have runtest from the DejaGnu package (prep.ai.mit.edu:/pub/gnu/dejagnu-1.2.tar.gz as of this writing) installed, this will also run a set of live application tests, creating a test realm, starting a Kerberos server, kadmind, and clients, and testing their features the way a human would use them.  The end summary should list no unexpected failures.

If you do find problems, you can get more specific detail by changing to the tests/dejagnu directory and running runtest with the -d option, and examining the dbg.log file produced.  (This will not be necessary with any platform supported by COMPANY.)

Constructing an Install Kit
===========================

Currently install kits are constructed by creating an install directory and running make install DESTDIR=INSTALL DIRECTORY, then using tar cf to produce a tar file.  In the future, there will be direct make targets to support construction of tar files and SVR4 packages.