$Id: README,v 1.13 1999/11/20 05:43:51 rcaputo Exp $

TABLE OF CONTENTS
=================

Table of Contents; About POE; Compatibility (Non-Requirements and
Requirements); Availability; Support Resources; Installing and
Testing; The Future


ABOUT POE
=========

"POE" is an acronym for Perl Object Environment.

First and foremost, it is a programming framework for event-driven
state machines.

POE includes high-level, functional interfaces for select, alarms,
sockets and file I/O.  The interfaces are robust but incomplete.

From different vantage points, POE may look like other things:

  It may seem to be a cooperative multithreading model.
  It may be interpreted as a portable component architecture.

Because it implements a low-level programming concept, POE can do many
things.


COMPATIBILITY
=============

POE has been tested with as many Perl versions as the author (and
testing pool) can find.  It is known to work with older Perl versions,
back to 5.004_03 (maybe earlier).  It should also work with the latest
stable release (the latest development release may also work).  For
the most recent compatibility results, see
<http://www.perl.org/cpan-testers/results.cgi?request=dist&dist=POE>.

As of this writing, Windows seems to have broken ioctl constants, and
its select returns strange values.  POE should work on sufficiently
POSIX systems, but Windows doesn't appear to be one of them.

MacOS is suspected to support POE.  If someone could confirm or deny
this, it would be greatly appreciated.

Please let me or the list know if any of this is wrong.  Thanks!

CPAN.pm will ensure that you have up-to-date copies of all the modules
POE uses.  I'm not sure whether to consider this a bug or a feature,
since most of POE's module requirements are only advisory.


Non-requirements:
-----------------

POE is compatible with fork(), but it is not used.  This distribution
includes a sample server that uses a pool of forked children.

POE will use Time::HiRes, if it's available.  Nothing untoward should
happen if it's not.

POE currently doesn't use XS modules, so you don't need a C compiler.


Requirements:
-------------

For portability, POE uses POSIX system calls and constants.  There
should be no problem running it on systems that have sufficient POSIX
support.

Some of POE's sample programs require a recent IO bundle, but you get
that for free with recent versions of Perl.

Filter::Reference requires either Storable, FreezeThaw or some other
freeze/thaw package.  Storable tends to be fastest.

Filter::HTTPD requires a small world of modules: HTTP::Status;
HTTP::Request; HTTP::Date and URI::URL.

The httpd.perl sample program uses Filter::HTTPD, which uses all that
other stuff.

The preforkedserver.perl sample program uses fork(), which may not be
available on your planet.

Other sample programs may require other modules, but the required
modules aren't required if you don't require those specific features.


AVAILABILITY
============

The latest stable release of POE is available three ways:

  perl -MCPAN -e 'install POE'

  In the /authors/id/R/RC/RCAPUTO/ on your favorite CPAN mirror.

  If you don't have a favorite CPAN mirror, you really ought to pick
  one.  You can download and manually install the latest stable POE
  from <http://www.cpan.org/authors/id/R/RC/RCAPUTO/> until then.

Beta versions of the next release are available from the author.  They
tend to be mostly stable, and other module and program authors tend to
use them because they're incrementally better than what's on the CPAN.


SUPPORT RESOURCES
=================

Places on the Internet where you can find more information about POE:

POE has a mailing list thanks to Arturn Bergman.  You may subscribe to
it by sending e-mail:

  From: (the address to which you want your mail sent)
  To: majordomo@vogon.se
  Subject: (anything will do)

  subscribe poe

All forms of feedback are welcome.


POE has a web site thanks to Johnathan Vail.  The latest POE
development snapshot, along with the Changes file and some other stuff
can be found at <http://www.newts.org/~troc/>.


INSTALLING AND TESTING
======================

If you've been using POE since before 0.06, please, PLEASE read the
Changes file before installing.  Many things have been broken between
versions 0.05 and 0.06.

To build and test this distribution, type:

  perl Makefile.PL
  make
  make test

Actually, 'make test' doesn't do anything important.  The closest
thing to real tests are the programs in the 'samples' directory.
These show how to use various bits of POE, exercising each as a side
effect.

Once everything looks good, POE can be installed by typing:

  make install


THE FUTURE
==========

A next-generation POE (code-named "POE2") is in the works.  It is a
complete rewrite, supporting some of the more difficult feature
requests.  An "RFC" level pre-alpha release is available from the POE
home page.


-- Rocco Caputo / troc@netrus.net / Thank you for reading.
