diff --git a/Makefile.PL b/Makefile.PL index 533ada314..ace41914d 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -3,6 +3,7 @@ sub author_tests { die "You need to install Module::Install::AuthorTests and Tes use inc::Module::Install; name 'Plack'; all_from 'lib/Plack.pm'; +readme_from 'lib/Plack.pm'; requires 'Class::Accessor::Fast'; requires 'LWP'; # HTTP::Status, HTTP::Headers and HTTP::Request diff --git a/README b/README new file mode 100644 index 000000000..0adf165ee --- /dev/null +++ b/README @@ -0,0 +1,76 @@ +NAME + Plack - PSGI reference implementation and utilities + +DESCRIPTION + Plack is a set of PSGI reference server implementations and helper + utilities for Web application frameworks, exactly like Ruby's Rack. + + See PSGI for the PSGI specification. + +MODULES AND UTILITIES + Plack::Server + Plack::Server is a namespace for PSGI server implementations. We have + Standalone, CGI, FCGI, Apache, AnyEvent, Coro, Danga::Socket and many + server environments that you can run PSGI applications on. + + See Plack::Server how to write your own server implementation. + + Plack::Loader + Plack::Loader is a loader to load one of Plack::Server backends and run + PSGI application code reference with it. + + Plack::Util + Plack::Util contains a lot of utility functions for server implementors + as well as middleware authors. + + .psgi files + PSGI application is a code reference but it's not easy to pass code + reference in the command line or configuration files, so Plack uses a + convention that you need a file named "app.psgi" or alike, which would + be loaded (via perl's core function "do") to return the PSGI application + code reference. See eg/dot-psgi directory for the example ".psgi" files. + + plackup + plackup is a command line launcher to run PSGI applications from command + line using Plack::Loader to load PSGI backends. It can be used to run + standalone servers and FastCGI daemon processes. Other server backends + like Apache2 needs a separate configuration but ".psgi" application file + can still be the same. + + Plack::Middleware + PSGI middleware is a PSGI application that wraps existent PSGI + application and plays both side of application and servers. From the + servers the wrapped code reference still looks like and behaves exactly + the same as PSGI applications. + + Plack::Middleware gives you an easy way to wrap PSGI applications with a + clean API, and compatibility with Plack::Builder DSL. + + Plack::Builder + Plack::Builder gives you a DSL that you can enable Middleware in ".psgi" + files to wrap existent PSGI applications. + + Plack::Request, Plack::Response + Plack::Request gives you a nice wrapper API around PSGI $env hash to get + headers, cookies and query parameters much like Apache::Request in + mod_perl. + + Plack::Response does the same to construct the response array reference. + + Plack::Test + Plack::Test is an unified interface to test your PSGI application using + standard HTTP::Request and HTTP::Response pair with simple callbacks. + + Plack::Test::Suite + Plack::Test::Suite is a test suite to test a new PSGI server backend. + +AUTHOR + See "AUTHORS" file. + +SEE ALSO + PSGI + +LICENSE + This library is free software; you can redistribute it and/or modify it + under the same terms as Perl itself. + diff --git a/README.md b/README.md deleted file mode 100644 index ffa69cac2..000000000 --- a/README.md +++ /dev/null @@ -1,7 +0,0 @@ -Plack - PSGI reference implementations and utilities - -## What are PSGI and Plack? - -PSGI is a specification of gateway interface protocol between Perl web applications and web servers, like Python's WSGI and Ruby's Rack. See [PSGI specification and FAQ](http://github.com/miyagawa/psgi-specs) for details. - -Plack contains reference implementations of PSGI servers and also has useful utility tools like Plackup (command line server and application launcher), Plack::Util (Useful utilities for server implementors) and Plack::Builder (DSL to quickly enable and configure Plack middleware in .psgi file).