Updated to reflect latest OS inconsistencies; removed shared library

theory section to a new file, implementor.texinfo, which will have
information that only developers will care about.

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

3 files changed, 273 insertions, 132 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 4fe7a6223..3a732170c 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,10 @@
+Mon Sep  9 19:35:37 1996  Theodore Ts'o  <tytso@rsts-11.mit.edu>
+
+	* build.texinfo: Updated to reflect latest OS inconsistencies;
+ 		removed shared library theory section to a new file,
+ 		implementor.texinfo, which will have information that only
+ 		developers will care about.
+
 Mon Sep  9 13:25:06 1996  Jeff Bigler  <jcb@viola.cygnus.com>
 
 	* texinfo-suppl.tex: extracted @doubleleftarrow{} hack into
diff --git a/doc/build.texinfo b/doc/build.texinfo
index 42f30f510..5852c06d0 100644
--- a/doc/build.texinfo
+++ b/doc/build.texinfo
@@ -10,15 +10,15 @@ porting Kerberos V5 to a new platform.
 * Unpacking the Sources::       Preparing the source tree.
 * Doing the Build::             Compiling Kerberos.
 * Testing the Build::           Making sure Kerberos built correctly.
-* Options to Configure::        
-* osconf.h::                    
-* Shared Library Support::      
+* Options to Configure::        Command-line options to Configure
+* osconf.h::                    Header file-specific configurations
+* Shared Library Support::      Building Shared Libraries for Kerberos V5
 * OS Incompatibilities::        Special cases to watch for.
 * Using Autoconf::              Modifying Kerberos V5's 
                                             configuration scripts.
 @end menu
 
-@node Build Requirements, Unpacking the Sources, , Building Kerberos V5
+@node Build Requirements, Unpacking the Sources, Building Kerberos V5, Building Kerberos V5
 @section Build Requirements
 
 In order to build Kerberos V5, you will need approximately 60-70
@@ -376,115 +376,15 @@ Solaris 5.3, Alpha OSF/1 >= 2.1, HP-UX >= 9.X.
 To enable shared libraries on the above platforms, run the configure
 script with the option @samp{--enable-shared}.
 
+@ifset notdef
+
+XXX What does this mean?
+
 One special note is that if the Kerberos V4 compatibility is compiled
 in, you @b{must not} specify an alternate Kerberos V4 library from the
 one in the tree or you will be missing references.
 
-@menu
-* Shared Library Theory::       
-* NetBSD Shared Library Support::  
-* AIX Shared Library Support::  
-* Solaris 5.3 Shared Library Support::  
-* Alpha OSF/1 Shared Library Support::  
-@end menu
-
-@node Shared Library Theory, NetBSD Shared Library Support, Shared Library Support, Shared Library Support
-@subsection Theory of How Shared Libraries are Used
-
-An explanation of how shared libraries are implemented on a given
-platform is too broad a topic for this manual. Instead this will touch
-on some of the issues that the Kerberos V5 tree uses to support version
-numbering and alternate install locations.
-
-Normally when one builds a shared library and then links with it, the
-name of the shared library is stored in the object
-(i.e. libfoo.so). Most operating systems allows one to change name that
-is referenced and we have done so, placing the version number into the
-shared library (i.e. libfoo.so.0.1). At link time, one would reference
-libfoo.so, but when one executes the program, the shared library loader
-would then look for the shared library with the alternate name.  Hence
-multiple versions of shared libraries may be supported relatively
-easily. @footnote{Under AIX for the RISC/6000, multiple versions of
-shared libraries are supported by combining two or more versions of the
-shared library into one file.  The Kerberos build procedure produces
-shared libraries with version numbers in the internal module names, so
-that the shared libraries are compatible with this scheme.
-Unfortunately, combining two shared libraries requires internal
-knowledge of the AIX shared library system beyond the scope of this
-document.  Practicallyspeaking, only one version of AIX shared libraries
-can be supported on a system, unless the multi-version library is
-constructed by a programmer familiar with the AIX internals.}
-
-All operating systems (that we have seen) provide a means for programs
-to specify the location of shared libraries. On different operating
-systems, this is either specified when creating the shared library, and
-link time, or both.@footnote{Both are necessary sometimes as the shared
-libraries are dependent on other shared libraries} The build process
-will hardwire a path to the installed destination.
-
-
-@node NetBSD Shared Library Support, AIX Shared Library Support, Shared Library Theory, Shared Library Support
-@subsection NetBSD Shared Library Support
-
-Shared library support has been tested under NetBSD 1.0A using 
-GCC 2.4.5. Due to the vagaries of the loader in the operating system,
-the library load path needs to be specified in building libraries and in
-linking with them. Unless the library is placed in a standard location
-to search for libraries, this may make it difficult for developers to
-work with the shared libraries.
-
-@node AIX Shared Library Support, Solaris 5.3 Shared Library Support, NetBSD Shared Library Support, Shared Library Support
-@subsection AIX Shared Library Support
-
-        AIX specifies shared library versions by combining multiple
-versions into a single file.  Because of the complexity of this process,
-no automatic procedure for building multi-versioned shared libraries is
-provided. Therefore, supporting multiple versions of the Kerberos shared
-libraries under AIX will require significant work on the part of a
-programmer famiiliar with AIX internals.  
-
-        AIX allows a single library to be used both as a static library
-and as a shared library.  For this reason, the @samp{--enable-shared}
-switch to configure builds only shared libraries.  On other operating
-systems, both shared and static libraries are built when this switch is
-specified.  As with all other operating systems, only non-shared static
-libraries are built when @samp{--enable-shared} is not specified.
-
-        The AIX 3.2.5 linker dumps core trying to build a shared
-@samp{libkrb5.a} produced with the GNU C compiler.  The native AIX
-compiler works fine.  In addition, the AIX 4.1 linker is able to build a
-shared @samp{libkrb5.a} when GNU C is used.
-
-
-@node Solaris 5.3 Shared Library Support, Alpha OSF/1 Shared Library Support, AIX Shared Library Support, Shared Library Support
-@subsection Solaris 5.3 Shared Library Support
-
-Shared library support only works when using the Sunsoft C compiler. We
-are currently using version 3.0.1. 
-
-The path to the shared library must be specified at link time as well as
-when creating libraries. 
-
-@node Alpha OSF/1 Shared Library Support,  , Solaris 5.3 Shared Library Support, Shared Library Support
-@subsection Alpha OSF/1 Shared Library Support
-
-Shared library support has been tested with V2.1 and higher of the
-operating system. Shared libraries may be compiled both with GCC and the
-native compiler.
-
-One of the nice features on this platform is that the paths to the
-shared libraries is specified in the library itself without requiring
-that one specify the same at link time. 
-
-We are using the @samp{-rpath} option to @samp{ld} to place the library
-load path into the executables. The one disadvantage of this is during
-testing where we want to make sure that we are using the build tree
-instead of a possibly installed library. The loader uses the contents of
-@samp{-rpath} before LD_LIBRARY_PATH so we must specify a dummy _RLD_ROOT
-and complete LD_LIBRARY_PATH in our tests.
-
-The one disadvantage with the
-method we are using 
+@end ifset
 
 @node OS Incompatibilities, Using Autoconf, Shared Library Support, Building Kerberos V5
 @section Operating System Incompatibilities
@@ -495,34 +395,25 @@ incompatibilities, and/or discover work arounds to such problems, please
 send a report to @b{krb5-bugs@@mit.edu}.  Thanks!
 
 @menu
-* Ultrix 4.2/3::                
+* AIX::                         
 * Alpha OSF/1 V1.3::            
-* Alpha OSF/1 V2.0++::          
+* Alpha OSF/1 (Digital Unix) V2.0++::  
 * BSDI::                        
+* HPUX::                        
 * Solaris versions 2.0 through 2.3::  
 * Solaris 2.X::                 
 * SGI Irix 5.X::                
+* Ultrix 4.2/3::                
 @end menu
 
-@node Ultrix 4.2/3, Alpha OSF/1 V1.3, OS Incompatibilities, OS Incompatibilities
-@subsection Ultrix 4.2/3
+@node AIX, Alpha OSF/1 V1.3, OS Incompatibilities, OS Incompatibilities
+@subsection AIX
 
-On the DEC MIPS platform, using the native compiler, @file{md4.c} and
-@file{md5.c} can not be compiled with the optimizer set at level 1.
-That is, you must specify either @samp{--with-ccopts=-O} and
-@samp{--with-ccopts=-g} to configure.  If you don't specify either, the
-compile will never complete.
-
-The optimizer isn't hung; it just takes an exponentially long time.
-Compiling 6 out of the 48 algorithmic steps takes 3 seconds; compiling 7
-steps takes 9 seconds; compiling 8 steps takes 27 seconds, and so on.
-Calculations estimate it will finish in approximately 3,469 billion
-years....
-
-Using GCC instead of the native compiler will also work fine, both with
-or without optimization.
+The AIX 3.2.5 linker dumps core trying to build a shared
+@samp{libkrb5.a} produced with the GNU C compiler.  The native AIX
+compiler works fine.  This problem is fixed using the AIX 4.1 linker.
 
-@node Alpha OSF/1 V1.3, Alpha OSF/1 V2.0++, Ultrix 4.2/3, OS Incompatibilities
+@node Alpha OSF/1 V1.3, Alpha OSF/1 (Digital Unix) V2.0++, AIX, OS Incompatibilities
 @subsection Alpha OSF/1 V1.3
 
 Using the native compiler, compiling with the @samp{-O} compiler flag
@@ -531,7 +422,7 @@ causes the @code{asn.1} library to be compiled incorrectly.
 Using GCC version 2.6.3 or later instead of the native compiler will also work
 fine, both with or without optimization.
 
-@node Alpha OSF/1 V2.0++, BSDI, Alpha OSF/1 V1.3, OS Incompatibilities
+@node Alpha OSF/1 (Digital Unix) V2.0++, BSDI, Alpha OSF/1 V1.3, OS Incompatibilities
 @subsection Alpha OSF/1 V2.0++
 
 There used to be a bug when using the native compiler in compiling
@@ -544,7 +435,7 @@ was never a problem in using GCC version 2.6.3.
 In version 3.2 and beyond of the operating system, we have not seen any
 problems with the native compiler. 
 
-@node BSDI, Solaris versions 2.0 through 2.3, Alpha OSF/1 V2.0++, OS Incompatibilities
+@node BSDI, HPUX, Alpha OSF/1 (Digital Unix) V2.0++, OS Incompatibilities
 @subsection BSDI
 
 BSDI versions 1.0 and 1.1 reportedly has a bad @samp{sed} which causes
@@ -553,7 +444,16 @@ to use a @samp{sed} from somewhere else, such as GNU.  (This may be
 true for some versions of other systems derived from BSD 4.4, such as
 NetBSD and FreeBSD.)
 
-@node Solaris versions 2.0 through 2.3, Solaris 2.X, BSDI, OS Incompatibilities
+@node HPUX, Solaris versions 2.0 through 2.3, BSDI, OS Incompatibilities
+@subsection HPUX
+
+The native compiler for HPUX currently will not work, because it is not
+a full ANSI C compiler.  The optional compiler (c89) should work as long
+as you give it the @samp{+Olibcalls -D_HPUX_SOURCE} (this has only been
+tested for HPUX 9.0).  At this point, using GCC is probably your best
+bet.
+
+@node Solaris versions 2.0 through 2.3, Solaris 2.X, HPUX, OS Incompatibilities
 @subsection Solaris versions 2.0 through 2.3
 
 The @code{gethostbyname()} routine is broken; it does not return a fully
@@ -603,7 +503,11 @@ LD_LIBRARY_PATH environment variable when you compile it.  Alternatively
 you can use the @code{-i} option to @samp{cc}, by using the specifying
 @code{--with-ccopts=-i} option to @samp{configure}.
 
-@node SGI Irix 5.X,  , Solaris 2.X, OS Incompatibilities
+Shared library support only works when using the Sunsoft C compiler. We
+are currently using version 3.0.1.   (The latest GCC may work; this
+needs to be tested.)
+
+@node SGI Irix 5.X, Ultrix 4.2/3, Solaris 2.X, OS Incompatibilities
 @subsection SGI Irix 5.X
 
 If you are building in a tree separate from the source tree, the vendors
@@ -619,6 +523,32 @@ simply specify @code{--with-netlib} option to @samp{configure}.
 In 5.3, @code{gethostbyname()} is no longer present in @code{-lsocket} and
 is no longer an issue. 
 
+@node Ultrix 4.2/3,  , SGI Irix 5.X, OS Incompatibilities
+@subsection Ultrix 4.2/3
+
+The DEC MIPS platform currently will not support the native compiler,
+since the Ultrix compiler is not a full ANSI C compiler.  You should use
+GCC instead.
+
+@ifset notdef
+
+On the DEC MIPS platform, using the native compiler, @file{md4.c} and
+@file{md5.c} can not be compiled with the optimizer set at level 1.
+That is, you must specify either @samp{--with-ccopts=-O} and
+@samp{--with-ccopts=-g} to configure.  If you don't specify either, the
+compile will never complete.
+
+The optimizer isn't hung; it just takes an exponentially long time.
+Compiling 6 out of the 48 algorithmic steps takes 3 seconds; compiling 7
+steps takes 9 seconds; compiling 8 steps takes 27 seconds, and so on.
+Calculations estimate it will finish in approximately 3,469 billion
+years....
+
+Using GCC instead of the native compiler will also work fine, both with
+or without optimization.
+
+@end ifset
+
 @node Using Autoconf,  , OS Incompatibilities, Building Kerberos V5
 @section Using @samp{Autoconf}
 
@@ -675,3 +605,4 @@ To install the binaries into a binary tree, do:
 % make all
 % make install DESTDIR=somewhere-else
 @end example
+
diff --git a/doc/implementor.texinfo b/doc/implementor.texinfo
new file mode 100644
index 000000000..aa5b23a86
--- /dev/null
+++ b/doc/implementor.texinfo
@@ -0,0 +1,203 @@
+\input texinfo @c -*-texinfo-*-
+@c
+@c Note: the above texinfo file must include the "doubleleftarrow"
+@c definitions added by jcb.
+@c %**start of header
+@c guide
+@setfilename krb5-implement.info
+@settitle Kerberos V5 Installation Guide
+@setchapternewpage odd                  @c chapter begins on next odd page
+@c @setchapternewpage on                   @c chapter begins on next page
+@smallbook                              @c Format for 7" X 9.25" paper
+@c %**end of header
+
+@paragraphindent 0
+@iftex
+@parskip 6pt plus 6pt
+@end iftex
+
+@include definitions.texinfo
+@set EDITION b7-1
+
+@finalout                               @c don't print black warning boxes
+
+@titlepage
+@title @value{PRODUCT} Implementor's Guide
+@subtitle Release:  @value{RELEASE}
+@subtitle Document Edition:  @value{EDITION}
+@subtitle Last updated:  @value{UPDATED}
+@author @value{COMPANY}
+
+@page
+@vskip 0pt plus 1filll
+
+@iftex
+@include copyright.texinfo
+@end iftex
+@end titlepage
+
+@menu
+* Shared Library Theory::       
+* NetBSD Shared Library Support::  
+* AIX Shared Library Support::  
+* Solaris 5.3 Shared Library Support::  
+* Alpha OSF/1 Shared Library Support::  
+@end menu
+
+@node Top, Introduction, (dir), (dir)
+@comment  node-name,  next,  previous,  up
+
+@ifinfo
+This file contains internal implementor's information for the
+@value{RELEASE} release of @value{PRODUCT}.  
+
+@include copyright.texinfo
+
+@end ifinfo
+
+@c The master menu is updated using emacs19's M-x texinfo-all-menus-update
+@c function.  Don't forget to run M-x texinfo-every-node-update after
+@c you add a new section or subsection, or after you've rearranged the
+@c order of sections or subsections.  Also, don't forget to add an @node
+@c comand before each @section or @subsection!  All you need to enter
+@c is:
+@c
+@c @node New Section Name
+
+@c @section New Section Name
+@c
+@c M-x texinfo-every-node-update will take care of calculating the
+@c node's forward and back pointers.
+@c
+@c ---------------------------------------------------------------------
+
+@menu
+* Introduction::                
+* Shared Libraries::            
+@end menu
+
+@node Introduction, Shared Libraries, Top, Top
+@chapter Introduction
+
+This file contains internal implementor's information for
+@value{PRODUCT}.  It is currently contains information that was removed
+from install.texi; eventually it will have more detailed information on
+the internals of the @value{PRODUCT}.
+
+@node Shared Libraries,  , Introduction, Top
+@chapter Shared Libraries
+
+@menu
+* Shared Library Theory::       
+* Operating System Notes for Shared Libraries::  
+@end menu
+
+@node Shared Library Theory, Operating System Notes for Shared Libraries, Shared Libraries, Shared Libraries
+@section Theory of How Shared Libraries are Used
+
+An explanation of how shared libraries are implemented on a given
+platform is too broad a topic for this manual. Instead this will touch
+on some of the issues that the Kerberos V5 tree uses to support version
+numbering and alternate install locations.
+
+Normally when one builds a shared library and then links with it, the
+name of the shared library is stored in the object
+(i.e. libfoo.so). Most operating systems allows one to change name that
+is referenced and we have done so, placing the version number into the
+shared library (i.e. libfoo.so.0.1). At link time, one would reference
+libfoo.so, but when one executes the program, the shared library loader
+would then look for the shared library with the alternate name.  Hence
+multiple versions of shared libraries may be supported relatively
+easily. @footnote{Under AIX for the RISC/6000, multiple versions of
+shared libraries are supported by combining two or more versions of the
+shared library into one file.  The Kerberos build procedure produces
+shared libraries with version numbers in the internal module names, so
+that the shared libraries are compatible with this scheme.
+Unfortunately, combining two shared libraries requires internal
+knowledge of the AIX shared library system beyond the scope of this
+document.  Practicallyspeaking, only one version of AIX shared libraries
+can be supported on a system, unless the multi-version library is
+constructed by a programmer familiar with the AIX internals.}
+
+All operating systems (that we have seen) provide a means for programs
+to specify the location of shared libraries. On different operating
+systems, this is either specified when creating the shared library, and
+link time, or both.@footnote{Both are necessary sometimes as the shared
+libraries are dependent on other shared libraries} The build process
+will hardwire a path to the installed destination.
+
+@node Operating System Notes for Shared Libraries,  , Shared Library Theory, Shared Libraries
+@section Operating System Notes for Shared Libraries
+
+
+@menu
+* NetBSD Shared Library Support::  
+* AIX Shared Library Support::  
+* Solaris 5.3 Shared Library Support::  
+* Alpha OSF/1 Shared Library Support::  
+@end menu
+
+@node NetBSD Shared Library Support, AIX Shared Library Support, Operating System Notes for Shared Libraries, Operating System Notes for Shared Libraries
+@subsection NetBSD Shared Library Support
+
+Shared library support has been tested under NetBSD 1.0A using 
+GCC 2.4.5. Due to the vagaries of the loader in the operating system,
+the library load path needs to be specified in building libraries and in
+linking with them. Unless the library is placed in a standard location
+to search for libraries, this may make it difficult for developers to
+work with the shared libraries.
+
+@node AIX Shared Library Support, Solaris 5.3 Shared Library Support, NetBSD Shared Library Support, Operating System Notes for Shared Libraries
+@subsection AIX Shared Library Support
+
+        AIX specifies shared library versions by combining multiple
+versions into a single file.  Because of the complexity of this process,
+no automatic procedure for building multi-versioned shared libraries is
+provided. Therefore, supporting multiple versions of the Kerberos shared
+libraries under AIX will require significant work on the part of a
+programmer famiiliar with AIX internals.  
+
+        AIX allows a single library to be used both as a static library
+and as a shared library.  For this reason, the @samp{--enable-shared}
+switch to configure builds only shared libraries.  On other operating
+systems, both shared and static libraries are built when this switch is
+specified.  As with all other operating systems, only non-shared static
+libraries are built when @samp{--enable-shared} is not specified.
+
+        The AIX 3.2.5 linker dumps core trying to build a shared
+@samp{libkrb5.a} produced with the GNU C compiler.  The native AIX
+compiler works fine.  In addition, the AIX 4.1 linker is able to build a
+shared @samp{libkrb5.a} when GNU C is used.
+
+
+@node Solaris 5.3 Shared Library Support, Alpha OSF/1 Shared Library Support, AIX Shared Library Support, Operating System Notes for Shared Libraries
+@subsection Solaris 5.3 Shared Library Support
+
+Shared library support only works when using the Sunsoft C compiler. We
+are currently using version 3.0.1. 
+
+The path to the shared library must be specified at link time as well as
+when creating libraries. 
+
+@node Alpha OSF/1 Shared Library Support,  , Solaris 5.3 Shared Library Support, Operating System Notes for Shared Libraries
+@subsection Alpha OSF/1 Shared Library Support
+
+Shared library support has been tested with V2.1 and higher of the
+operating system. Shared libraries may be compiled both with GCC and the
+native compiler.
+
+One of the nice features on this platform is that the paths to the
+shared libraries is specified in the library itself without requiring
+that one specify the same at link time. 
+
+We are using the @samp{-rpath} option to @samp{ld} to place the library
+load path into the executables. The one disadvantage of this is during
+testing where we want to make sure that we are using the build tree
+instead of a possibly installed library. The loader uses the contents of
+@samp{-rpath} before LD_LIBRARY_PATH so we must specify a dummy _RLD_ROOT
+and complete LD_LIBRARY_PATH in our tests.
+
+The one disadvantage with the method we are using....
+
+@contents
+@bye