################################################################################
# File: ....................... INSTALL
# Original Author: ............ Jeff Nokes
# Last modified by: ........... Jeff Nokes
# Last modified: .............. 03/15/2007 @ 14:46
################################################################################





MODULE INSTALLATION
--------------------------------------------------------------------------------
Method 1:   The traditional Perl process of:

   1.1   download module eBay-API-0.01.tar.gz from CPAN or eBay Developer Zone
         (TBD: eBay Dev Zone URL)
   1.2   cd to directory where tar.gz was downloaded
   1.3   gzip -d eBay-API-0.01.tar.gz
   1.4   tar -xvf eBay-API-0.01.tar
   1.5   (recompress the tar:  gzip --best eBay-API-0.01.tar)
   1.6   cd to eBay-API-0.01

   Determine all build options by:
   1.7   perl Makefile.PL --help

   1.8   perl Makefile.PL  [options]
   1.9   make
   1.10  make test
   1.11  make install

   Notes:  - If you provide the proper arguments to Makefile.PL, all tests
             during the `make test` phase should attempt to execute, otherwise
             some tests that require proper API credentials will skip, but
             return OK.



Method 2:   Pull from a CPAN mirror archive
            (Note: may not be available via CPAN yet)

   2.1   perl -MCPAN -e shell
   2.2   install eBay::API

   Notes:  - By using this method, you will not be able to provide the
             optional arguments to Makefile.PL, and thus the `make test` phase
             of the installation will skip any tests that require proper
             API credentials, but return OK.





NOTES:

(N1)  During the install process, the MAKEFILE.PL will attempt to autogenerate
      all class data-types for you by default, unless you provide the

         --noautogen

      ... switch at runtime.

(N2)  If you would like a test API call during the intallation process, you must
      provide the following options:

         --appid
         --devid
         --certid
         --authtoken

      ... otherwise the test API call step will be skipped.

(N3)  The location for the latest eBay XML API xsd schema file is usually found
      at:

         http://developer.ebay.com/webservices/latest/ebaySvc.xsd

(N4)  If you choose not to autogenerate all of the classes at installation, or
      you are upgrading the classes to a more current schema version, you can
      do it manually at anytime, by following the directions outlined in the
      file

         <your lib dir>/eBay/API/XML/tools/codegen/xsd/README

(N5)  You can generate HTML CPAN-style documentation for all of the provided
      and autogenerated POD documentation in this SDK.  Reference the following
      on how to do this.

         <your lib dir>/eBay/API/XML/tools/doc/README





EXAMPLES (Assuming a Bourne/Bash shell):

(E1)  You want to autogenerate, and you want to test the API call.

         perl MAKEFILE.PL \
            PREFIX=/home/me/my_special_lib_dir \
            --appid='<your appid provided to you by eBay>' \
            --devid='<your devid provided to you by eBay>' \
            --certid='<your certid provided to you by eBay>' \
            --authtoken='<a current authtoken you've generated>'

      Note:  To generate an authtoken, you will need to use your eBay provided
             userid/password and the authentication token generator tool located
             at:
                http://www.developer.ebay.com/tokentool/

             ActiveState users may have to use doublequotes instead of single
             quotes around the option values.

(E2)  You want to autogenerate, but do not want to test the API call.
      (This is the default behavior of MAKEFILE.PL).

         perl MAKEFILE.PL \
            PREFIX=/home/me/my_special_lib_dir

(E3)  You just want to install the core distribution files, and will autognerate
      at a later time.

         perl MAKEFILE.PL \
            --noautogen

      Note:  Obviously, you cannot attempt a test API call without the
             auto-generated classes/data-types.