README

                    Apache HTTP Server Request Library

  What is it?
  -----------
  httpd-apreq is subproject of the Apache HTTP Server Project 
  whose committers develop and maintain the libapreq C library
  and its language bindings for Perl (contributions for additional 
  language bindings are most welcome).

  libapreq is a safe, standards-compliant, high-performance library 
  used for parsing HTTP cookies, query-strings and POST data.  The 
  original version (libapreq-1.X) was designed by Lincoln Stein and Doug 
  MacEachern.  The perl APIs Apache::Request and Apache::Cookie are the
  lightweight mod_perl analogs of the CGI and CGI::Cookie perl modules.

  Version 2 of libapreq is an improved codebase designed around APR
  and Apache-2's input filter API.  The C codebase is separated into
  two independent components:

        1) libapreq2, the shared library.  This library is based 
           solely on libapr and libaprutil, and requires linking
           applications to provide stub code for the apreq_env
           interface (defined by the "apreq_env.h" header file).
           The source files for libapreq2 are in the src/ directory.

        2) A collection of "environment" modules which provide the
           aforementioned supporting functions for the apreq_env API.
           The modules' source files are in the env/ directory.
           Two supported modules are now available

                1) an Apache 2 filter module - mod_apreq.c,

                2) the default CGI module included in libapreq2.

  Version 2 also includes the perl APIs for libapreq2- Apache::Request 
  and Apache::Cookie.  The corresponding XS modules are generated in
  perl/glue/xs by ExtUtils::XSBuilder, which is based on the new build 
  system created specifically for modperl-2.


  The Latest Version
  ------------------

  Details of the latest version can be found on the libapreq
  project page at 

                http://httpd.apache.org/apreq


  Documentation
  -------------

  The documentation is in the docs/ directory.  It is
  based on Doxygen, and can be regenerated by typing

        % make docs

  in the main directory.


  Installation
  ------------

  For full details please consult the INSTALL file.  Briefly,
  to install just the C API (libapreq2 + environment modules)
  on a Unix-like system:

            % ./configure --with-apache2-apxs=/path/to/apache2/bin/apxs
            % make
            % make test
            % make install

   To build and install the perl API as well, either add
   the "--enable-perl-glue" configure option, or let Makefile.PL
   enable it for you:

            % perl Makefile.PL --with-apache2-apxs=/path/to/apache2/bin/apxs
            % make
            % make test 
            % make install

  Licensing
  ---------

  Please see the file called LICENSE.


  Contacts
  --------

     o Project homepage:

        http://httpd.apache.org/apreq/

     o Mailing Lists:

        user lists:
               C/C++ API - modules@apache.org
                Perl API - modperl@perl.apache.org
                 Tcl API - XXX
                Java API - XXX
              Python API - XXX

        developer list (bugs, patches, code contributions, etc.):
                apreq-dev@httpd.apache.org


  Acknowledgments
  ----------------

  We wish to acknowledge the following copyrighted works that
  make up portions of the Apache software:

  libapreq2 relies heavily on the use of the GNU auto-tools 
  to provide a build environment.  The tests are based on 
  the Apache::Test, Test::Harness and Test::Inline.

  Doxygen generates the documentation for libapreq2. The perl glue
  and pods are generated by ExtUtils::XSBuilder.