$Id: README,v 1.15 2000/01/25 19:16:08 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 . The last attempt at writing Windows support into POE was in early January 1999. The Windows code was never completed nor tested, and it has been backed out as of January 2000. The assumption is that ActiveState has been working on bringing its perl port into line with normal things, and it would be better to start cleanly now than try to work with code implementing old assumptions. The Changes file lists the exact versions and dates when the Windows support went in and came out. MacOS is suspected to support POE. It would be greatly appreciated if someone could confirm or deny this. Please let me or the list know if any of this is wrong. Thanks! Non-requirements: ----------------- POE is compatible with fork(), but it is only used upon request. 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, unless you use one of the sample programs that absolutely requires it. POE currently uses no XS in its implementation. It should work wherever a sufficiently complete version of Perl does. 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, and it's checked first. The Reference filter can also use Compress::Zlib upon request, but it works without it too. 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 POE::Kernel::fork(), which in turn uses the fork() built-in. This may or 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: 1: ``perl -MCPAN -e shell'' Then type ``install POE'' at the CPAN prompt. 2: In the /authors/id/R/RC/RCAPUTO/ on your favorite CPAN mirror. This is where the CPAN shell gets it. 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 until then. 3: 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. Relatively stable betas are available from the POE web page, at . 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: poe-help@vogon.se Subject: (anything will do) Anything will do for the body. 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 . 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 -- Rocco Caputo / troc@netrus.net / Thank you for reading.