
This is the README file for the Perl extension module AFS
(Version 2.2.0) 


DESCRIPTION
    The AFS module bundle is a dynamically loadable extension to
    Perl. It gives the AFS user and administrator access to many of the
    AFS programming APIs, allowing you to make these calls directly from
    Perl, rather than processing the output of a command.


REQUIREMENTS
    Before you can build the AFS module bundle you need to have the
    following installed on your system:

        * Perl 5.005_02 or later
        * system libraries for IBM AFS (version 3.6) or OpenAFS
        * GNU gcc (on solaris-2.{5,6,7,8,9})

    NOTICE: This release does not support AFS system libraries 
            version 3.4 or version 3.5 !!!
 

BUILDING & INSTALLING
    Assuming you have met all the prerequisites, building the modules
    should be straightforward. The AFS module bundle is distributed as a
    single gzipped tar archive file:

            AFS-2.2.0.tar.gz

    Unpack the archive to create an AFS installation directory:

        gunzip AFS-2.2.0.tar.gz
        tar xvf AFS-2.2.0.tar

    'cd' into that directory, make, test and install the modules. You
    have to specify the location of the AFS system libraries. While
    running the 'perl Makefile.PL' step you will be prompted for the
    location of the AFS system libraries.  If you want to avoid that
    query, you should specify the environment variable 'AFSPATH'
    before you start[1].  If your AFS system type is not yet known by
    the make file, please follow the printed message.  

    This is the sequence of commands to build the modules:

        cd AFS-2.2.0

        [1] this step is optional
        setenv AFSPATH 'path_to_the_AFS_system_libraries' # tcsh-shell
        export AFSPATH='path_to_the_AFS_system_libraries' # sh-shell

        perl Makefile.PL
             ---->  Which AFS system libraries should be used? [/usr/afsws]
        make
        make test
        make install


SunOS
    Under SunOS, several people have encountered problems while compiling
    and installing the AFS module bundle.  From my own experience I can
    report that the module bundle did not compile with every AFS system
    library packages (see below).  

    If you're a SunOS user who knows a solution to an encountered problem
    and would like to document the solution for others, please send the
    docs to the AFS module maintainer to amend the installation directions.

    Here is a collection of user reports about their "sun" problems.

    From: Alf Wachsmann <alf@ifh.de>
    Compiling with Sun's SUNWspro cc doesn't work for me, so I use the gcc
    (version 2.8.1) which gives lots of warnings, but it compiles the module.
    Note the changed flag -fpic instead of -Kpic!

    From: Peter Scott <Peter@PSDT.com> 
    Gotcha.  I am trying this on Solaris 2.6... success!  All tests
    pass.  You might want to mention that the GNU ld loses on this, have
    to use the Sun ld.  perl Makefile.PL LD=/usr/ccs/bin/ld

    From: Norbert Gruener <nog@MPA-Garching.MPG.de>
    In the meantime I traced the "sun-problem"
        sun4x_57          compiles with AFS 3.6 Patch 2.0   gcc 2.95.2
        sun4x_57 DOES NOT compile  with AFS 3.6 Patch 2.3   gcc 2.95.2
        sun4x_57          compiles with AFS 3.6 Patch 2.6   gcc 2.95.2

    From: Alf Wachsmann <alfw@SLAC.Stanford.EDU>
    I checked on our site:
        sun4x_56        compiles with AFS 3.6 Patch 2.0
        sun4x_57        compiles with AFS 3.6 Patch 2.5

    From: Peter Scott <Peter@PSDT.com>
    FYI and FWIW, I have installed this with:
    AFS 3.4.555 library on sun4x_55 with gcc 2.8.1.

    On Solaris 2.6 I built it with AFS 3.5.345.  On Solaris 2.8 it was 3.6.226.
    It built ok on Solaris 2.8 and 3.5 for me without changes, so the
    problem child seems to be Solaris 2.6.
    On Solaris 2.6 with AFS 3.5.345, I needed to define int32 and uint32.
    $d_flag .= ' -Dint32=afs_int32 -Duint32=afs_uint32' if $alpha_sys eq 'sun4x_56';  # From Peter@PSDT.com



FEEDBACK
    I have tested/run the AFS module bundle on several configurations
    and I have also got reports that it is running on configurations, not
    available to me.

      OS             @sys         compiler 
      ------------------------------------
      AIX            rs_aix32       cc       
                     rs_aix41       cc       
                     rs_aix42       cc       

      Solaris        sun4x_55       gcc      
                     sun4x_56       gcc      
                     sun4x_57       gcc      
                     sun4x_58       gcc
                     sun4x_59       gcc

      Irix           sgi_65         cc

      Linux          i386_linux24   gcc
                     amd64_linux24  gcc

      Digital Unix   alpha_dux40  

    If you are building the modules on another architecture I would
    appreciate a note to tell me how you got on. Although I am
    particularly interested to hear about any problems you encounter
    when building the system, I would still like to hear from you even
    if you don't.

    Things I particularly would like to know

       * The Operating system name and version, e.g. SunOS 4.1.3
       * Architecture, e.g. Solaris
       * C compiler, e.g. gcc
       * Where there any warnings/errors printed by the C compiler? If so
         please send the exact output if possible.
       * The Perl version
       * The version of the AFS system libraries


Availability
    The latest version of the AFS module bundle is currently available at

        http://www.MPA-Garching.MPG.de/~nog/perl/AFS-2.2.0.tar.gz
        http://www.cpan.org/authors/id/N/NO/NOG/AFS-2.2.0.tar.gz


MAJOR CHANGES (from version 1 to version 2)
    This module bundle compiles with the AFS system libraries for IBM
    AFS version 3.4.x, 3.5.x, 3.6.x and with the AFS system libraries
    for all OpenAFS versions.

    Since OpenAFS is running on an increasingly number of platforms so
    does the AFS Perl module.  Everywhere you can compile OpenAFS and
    Perl you should be able to install the ASF Perl module.

    The constructor methods for all AFS classes have been corrected to
    conform with the Perl OO conventions.

    In order to have clean Perl interfaces the AFS Perl code has been
    separated into several logical modules.  All modules have been
    implemented as OO classes.

    For more details, please see the file named 'CHANGES which should
    have been included in the AFS module distribution.


COMPATIBILITY
    In version 2, all functions and special variables have been resorted
    into separate modules according to their affiliations to different
    AFS command suits.  These resorted functions and variables are not
    exported by default anymore but they are exported only on request.

    All variables and functions from version 1 are still available for
    compatibility, but are deprecated.  These cases have been marked in
    the documentation.

    You must not intermix names or interfaces from version 1 with names
    or interfaces from version 2. You either stick with version 1 or
    version 2.


DOCUMENTATION
    POD-format documentation for version 1 style is found in the
    directory 'pod/v1' and for version 2 style in the directory
    'pod/v2'.  The POD documentation for version 2 style gets
    automatically installed to the system wide Perl documentation.
    It is readable with the 'perldoc' utility.

    For information about HTML documentation, please check the file
    'pod/v2/README'. 


EXAMPLES
    The 'examples' directory contains some simple examples how to use the
    AFS modules.  In the directory 'examples/v1' you will find version 1
    style examples and in the directory 'examples/v2' you will find
    version 2 style examples.  However I do not guarantee these scripts
    to work.


AUTHORS 
    The current release was written by Norbert E Gruener
    <nog@MPA-Garching.MPG.de>.

    The original AFS interface was written by Roland Schemers
    <schemers@stanford.edu>.  


CREDITS
    See 'afsperl.pod' for details.


COPYRIGHT AND DISCLAIMER
    © 2001-2004 Norbert E. Gruener <nog@MPA-Garching.MPG.de>.
    All rights reserved.

    © 1994 Board of Trustees, Leland Stanford Jr. University.
    All rights reserved.

    This library is free software; you can redistribute it and/or modify
    it under the same terms as Perl itself.

    You should have received a copy of the Perl license along with
    Perl; see the file 'README' in Perl distribution.

    You should have received a copy of the GNU General Public License
    along with Perl; see the file 'COPYING'.  If not, write to the Free
    Software Foundation, 59 Temple Place - Suite 330, Boston, MA
    02111-1307, USA.

    You should have received a copy of the Artistic License
    along with Perl; see the file 'Artistic'.

    The original module is covered by the following copyright:
       Copyright (c) 1994 Board of Trustees, Leland Stanford Jr. University

       Redistribution and use in source and binary forms are permitted
       provided that the above copyright notice and this paragraph are
       duplicated in all such forms and that any documentation,
       advertising materials, and other materials related to such
       distribution and use acknowledge that the software was developed
       by Stanford University.  The name of the University may not be
       used to endorse or promote products derived from this software
       without specific prior written permission.  THIS SOFTWARE IS
       PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
       INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
       MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.


KNOWN PROBLEMS
    The AFS command suite BOS is not yet implemented     :-(


BUGS
    Please send all bug reports and suggestions for improvements to
    Norbert E Gruener <nog@MPA-Garching.MPG.de>.  When reporting
    bugs/problems please include information about operating system
    version, perl version, AFS version, AFS module version.  Comments
    and suggestions are always welcome.


Share and Enjoy!

Norbert
