
This is the INSTALL file for the Perl extension module AFS (Version v2.6.3)
for the OpenAFS 64-bit version

README
    Read the README file first.


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

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


RECOMMENDATIONS
    It is highly recommended to place the installation directory in
    the AFS file system.  Otherwise most of the test cases
    ('make test') are skipped.


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

        * Perl v5.10.0 or newer
        * C compiler
        * OpenAFS system libraries 64-bit version (PIC type or standard)


WHAT TYPE OF OpenAFS SYSTEM LIBRARIES ARE NEEDED
    Depending on the installed Perl version you have to use the proper
    type of OpenAFS system libraries. If you have a "threaded" version
    of Perl, you have to link the AFS modules against the PIC type
    system libraries, for a "non-threaded" Perl you have to use the
    standard libraries.

    To find out what type of Perl you are using, just run the command:

       perl ./test_ptype

    If it says
                'Your Perl is 'Non-Threaded Perl'
    then you need the standard system libraries and you can skip to
    the next section (BUILDING & INSTALLING).

    If it says
                Your Perl is 'Threaded Perl'
    then you need the PIC type system libraries.  Unfortunately the
    PIC type system libraries are not created for OpenAFS 1.4.X by
    default.  Therefore you have to patch your OpenAFS installation.

    This is the sequence of commands to build the PIC type system libraries:

        gunzip AFS-<version>.tar.gz
        tar xvf AFS-<version>.tar
        cd openafs-1.4.X
        patch < AFS-<version>/openafs-pic.patch
        make clean
        make
        make install

    Now you have created the additional PIC type system libraries for
    OpenAFS 1.4.X and you can start building the AFS modules.


BUILDING & INSTALLING
    Building the modules is straightforward. The AFS module bundle is
    distributed as a single gzipped tar archive file:

            AFS-<version>.tar.gz

    Unpack the archive to create an AFS installation directory:

        gunzip AFS-<version>.tar.gz
        tar xvf AFS-<version>.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 because
    you can't run the "fs sysname" command, you can specify the
    environment variable 'AFS_SYSNAME' before you start [2].

    This is the sequence of commands to build the modules:

        cd AFS-<version>

        [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

        [2] this step is optional
        setenv AFS_SYSNAME 'AFS_system_type'              # tcsh-shell
        export AFS_SYSNAME 'AFS_system_type'              # sh-shell

        perl Makefile.PL
             ---->  Which AFS system libraries should be used? [/usr/afsws]
        make
        make test
        make install
        make html   ;#(if you want to get the HTML documentation, see also next section)


PLATFORMS
    In the meantime I have only access to Linux machines.  Therefore I
    have tested this version of the AFS module bundle only on the
    Linux platform with the following combinations

        OS             @sys         compiler    OpenAFS    Perl   (threaded/non-threaded)
        ---------------------------------------------------------------------------------
        Linux 64-bit   amd64_linux26  gcc       1.4.11     5.10.0  non-threaded
                       amd64_linux26  gcc       1.4.12     5.10.0  non-threaded

                       amd64_linux26  gcc       1.4.12(*)  5.10.0  threaded
                                                (*) => modified libraries libafsrpc.a
                                                       and libafsauthent.a


FEEDBACK
    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


KNOWN PROBLEMS
    Under SunOS, several people have encountered problems while compiling
    and installing the AFS module bundle.


CURRENT AUTHOR
    Norbert E. Gruener <nog@MPA-Garching.MPG.de>


AUTHOR EMERITUS
    Roland Schemers <schemers@stanford.edu>


COPYRIGHT AND DISCLAIMER
    © 2001-2012 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.
