doc/implementor.texinfo

   1 \input texinfo @c -*-texinfo-*-
   2 @c
   3 @c Note: the above texinfo file must include the "doubleleftarrow"
   4 @c definitions added by jcb.
   5 @c %**start of header
   6 @c guide
   7 @setfilename krb5-implement.info
   8 @settitle Kerberos V5 Installation Guide
   9 @setchapternewpage odd                  @c chapter begins on next odd page
  10 @c @setchapternewpage on                   @c chapter begins on next page
  11 @smallbook                              @c Format for 7" X 9.25" paper
  12 @c %**end of header
  13
  14 @paragraphindent 0
  15 @iftex
  16 @parskip 6pt plus 6pt
  17 @end iftex
  18
  19 @include definitions.texinfo
  20 @set EDITION b7-1
  21
  22 @finalout                               @c don't print black warning boxes
  23
  24 @titlepage
  25 @title @value{PRODUCT} Implementor's Guide
  26 @subtitle Release:  @value{RELEASE}
  27 @subtitle Document Edition:  @value{EDITION}
  28 @subtitle Last updated:  @value{UPDATED}
  29 @author @value{COMPANY}
  30
  31 @page
  32 @vskip 0pt plus 1filll
  33
  34 @iftex
  35 @include copyright.texinfo
  36 @end iftex
  37 @end titlepage
  38
  39 @menu
  40 * Shared Library Theory::
  41 * NetBSD Shared Library Support::
  42 * AIX Shared Library Support::
  43 * Solaris 5.3 Shared Library Support::
  44 * Alpha OSF/1 Shared Library Support::
  45 @end menu
  46
  47 @node Top, Introduction, (dir), (dir)
  48 @comment  node-name,  next,  previous,  up
  49
  50 @ifinfo
  51 This file contains internal implementor's information for the
  52 @value{RELEASE} release of @value{PRODUCT}.
  53
  54 @include copyright.texinfo
  55
  56 @end ifinfo
  57
  58 @c The master menu is updated using emacs19's M-x texinfo-all-menus-update
  59 @c function.  Don't forget to run M-x texinfo-every-node-update after
  60 @c you add a new section or subsection, or after you've rearranged the
  61 @c order of sections or subsections.  Also, don't forget to add an @node
  62 @c comand before each @section or @subsection!  All you need to enter
  63 @c is:
  64 @c
  65 @c @node New Section Name
  66
  67 @c @section New Section Name
  68 @c
  69 @c M-x texinfo-every-node-update will take care of calculating the
  70 @c node's forward and back pointers.
  71 @c
  72 @c ---------------------------------------------------------------------
  73
  74 @menu
  75 * Introduction::
  76 * Shared Libraries::
  77 @end menu
  78
  79 @node Introduction, Shared Libraries, Top, Top
  80 @chapter Introduction
  81
  82 This file contains internal implementor's information for
  83 @value{PRODUCT}.  It is currently contains information that was removed
  84 from install.texi; eventually it will have more detailed information on
  85 the internals of the @value{PRODUCT}.
  86
  87 @node Shared Libraries,  , Introduction, Top
  88 @chapter Shared Libraries
  89
  90 @menu
  91 * Shared Library Theory::
  92 * Operating System Notes for Shared Libraries::
  93 @end menu
  94
  95 @node Shared Library Theory, Operating System Notes for Shared Libraries, Shared Libraries, Shared Libraries
  96 @section Theory of How Shared Libraries are Used
  97
  98 An explanation of how shared libraries are implemented on a given
  99 platform is too broad a topic for this manual. Instead this will touch
 100 on some of the issues that the Kerberos V5 tree uses to support version
 101 numbering and alternate install locations.
 102
 103 Normally when one builds a shared library and then links with it, the
 104 name of the shared library is stored in the object
 105 (i.e. libfoo.so). Most operating systems allows one to change name that
 106 is referenced and we have done so, placing the version number into the
 107 shared library (i.e. libfoo.so.0.1). At link time, one would reference
 108 libfoo.so, but when one executes the program, the shared library loader
 109 would then look for the shared library with the alternate name.  Hence
 110 multiple versions of shared libraries may be supported relatively
 111 easily. @footnote{Under AIX for the RISC/6000, multiple versions of
 112 shared libraries are supported by combining two or more versions of the
 113 shared library into one file.  The Kerberos build procedure produces
 114 shared libraries with version numbers in the internal module names, so
 115 that the shared libraries are compatible with this scheme.
 116 Unfortunately, combining two shared libraries requires internal
 117 knowledge of the AIX shared library system beyond the scope of this
 118 document.  Practicallyspeaking, only one version of AIX shared libraries
 119 can be supported on a system, unless the multi-version library is
 120 constructed by a programmer familiar with the AIX internals.}
 121
 122 All operating systems (that we have seen) provide a means for programs
 123 to specify the location of shared libraries. On different operating
 124 systems, this is either specified when creating the shared library, and
 125 link time, or both.@footnote{Both are necessary sometimes as the shared
 126 libraries are dependent on other shared libraries} The build process
 127 will hardwire a path to the installed destination.
 128
 129 @node Operating System Notes for Shared Libraries,  , Shared Library Theory, Shared Libraries
 130 @section Operating System Notes for Shared Libraries
 131
 132
 133 @menu
 134 * NetBSD Shared Library Support::
 135 * AIX Shared Library Support::
 136 * Solaris 5.3 Shared Library Support::
 137 * Alpha OSF/1 Shared Library Support::
 138 @end menu
 139
 140 @node NetBSD Shared Library Support, AIX Shared Library Support, Operating System Notes for Shared Libraries, Operating System Notes for Shared Libraries
 141 @subsection NetBSD Shared Library Support
 142
 143 Shared library support has been tested under NetBSD 1.0A using
 144 GCC 2.4.5. Due to the vagaries of the loader in the operating system,
 145 the library load path needs to be specified in building libraries and in
 146 linking with them. Unless the library is placed in a standard location
 147 to search for libraries, this may make it difficult for developers to
 148 work with the shared libraries.
 149
 150 @node AIX Shared Library Support, Solaris 5.3 Shared Library Support, NetBSD Shared Library Support, Operating System Notes for Shared Libraries
 151 @subsection AIX Shared Library Support
 152
 153         AIX specifies shared library versions by combining multiple
 154 versions into a single file.  Because of the complexity of this process,
 155 no automatic procedure for building multi-versioned shared libraries is
 156 provided. Therefore, supporting multiple versions of the Kerberos shared
 157 libraries under AIX will require significant work on the part of a
 158 programmer famiiliar with AIX internals.
 159
 160         AIX allows a single library to be used both as a static library
 161 and as a shared library.  For this reason, the @samp{--enable-shared}
 162 switch to configure builds only shared libraries.  On other operating
 163 systems, both shared and static libraries are built when this switch is
 164 specified.  As with all other operating systems, only non-shared static
 165 libraries are built when @samp{--enable-shared} is not specified.
 166
 167         The AIX 3.2.5 linker dumps core trying to build a shared
 168 @samp{libkrb5.a} produced with the GNU C compiler.  The native AIX
 169 compiler works fine.  In addition, the AIX 4.1 linker is able to build a
 170 shared @samp{libkrb5.a} when GNU C is used.
 171
 172
 173 @node Solaris 5.3 Shared Library Support, Alpha OSF/1 Shared Library Support, AIX Shared Library Support, Operating System Notes for Shared Libraries
 174 @subsection Solaris 5.3 Shared Library Support
 175
 176 Shared library support only works when using the Sunsoft C compiler. We
 177 are currently using version 3.0.1.
 178
 179 The path to the shared library must be specified at link time as well as
 180 when creating libraries.
 181
 182 @node Alpha OSF/1 Shared Library Support,  , Solaris 5.3 Shared Library Support, Operating System Notes for Shared Libraries
 183 @subsection Alpha OSF/1 Shared Library Support
 184
 185 Shared library support has been tested with V2.1 and higher of the
 186 operating system. Shared libraries may be compiled both with GCC and the
 187 native compiler.
 188
 189 One of the nice features on this platform is that the paths to the
 190 shared libraries is specified in the library itself without requiring
 191 that one specify the same at link time.
 192
 193 We are using the @samp{-rpath} option to @samp{ld} to place the library
 194 load path into the executables. The one disadvantage of this is during
 195 testing where we want to make sure that we are using the build tree
 196 instead of a possibly installed library. The loader uses the contents of
 197 @samp{-rpath} before LD_LIBRARY_PATH so we must specify a dummy _RLD_ROOT
 198 and complete LD_LIBRARY_PATH in our tests.
 199
 200 The one disadvantage with the method we are using....
 201
 202 @contents
 203 @bye