First stab documenting writing a .psgi file

diff --git a/TODO b/TODO
index d1364ba..f47c6b4 100644 (file)
--- a/TODO
+++ b/TODO
@@ -30,6 +30,7 @@ http://github.com/willert/catalyst-plugin-log4perl-simple/tree
 
 ###  Blockers
 
+  * Add a warning for PSGI engine compat hack
   * Test all the options work on all of the scripts
   * Document how to use your own .psgi (and how you need to do ReverseProxy yourself if you do)
   * Document migration for setting engine in setup

diff --git a/lib/Catalyst/PSGI.pod b/lib/Catalyst/PSGI.pod
new file mode 100644 (file)
index 0000000..07590e7
--- /dev/null
+++ b/lib/Catalyst/PSGI.pod
@@ -0,0 +1,66 @@
+=pod
+
+=head1 Catalyst and PSGI
+
+Catalyst used to contain a whole set of C<< Catalyst::Engine::XXXX >> classes to
+adapt to various different web servers, and environments (e.g. CGI, FastCGI, mod_perl)
+etc.
+
+This has been changed so that all of that work is done by Catalyst just implementing
+the L<PSGI> specification, and using L<Plack>'s adaptors to implement that functionality.
+
+This means that we can share common code, and fixes for specific web servers.
+
+=head1 I already have an application
+
+If you already have a Catalyst application, then this means very little, and you should be
+able to upgrade to the latest release with little or no trouble (See notes in L<Catalyst::Upgrading>
+for specifics about your web server deployment).
+
+=head1 Writing your own PSGI file.
+
+=head2 What is a .psgi file
+
+A C<< .psgi >> file lets you manually controll how your application code reference is built.
+
+Catalyst normally takes care of this for you, but it's possible to do it manually by
+creating a C<myapp.psgi> file in the root of your application.
+
+The simplest C<.psgi> file for an application called C<TestApp> would be:
+
+    use strict;
+    use warnings;
+    use TestApp;
+
+    my $app = sub { TestApp->psgi_app(@_) };
+
+It should be noted that Catalyst may apply a number of middleware components for
+you automatically, and these B<will not> be applied if you manually create
+a psgi file yourself. Details of these middlewares can be found XXXX FIXME
+
+Additional information about psgi files can be found at:
+L<http://search.cpan.org/dist/Plack/lib/Plack.pm#.psgi_files>
+
+=head2 Why would I want to make a .psgi file?
+
+Writing your own .psgi file allows you to use the alternate L<plackup> command
+to start your application, and allows you to add classes and extensions
+that implement L<Plack::Middleware>, such as L<Plack::Middleware::ErrorDocument>,
+or L<Plack::Middleware::AccessLog>.
+
+=head2 What is in the .psgi Catalyst generates by default?
+
+=head1 SEE ALSO
+
+L<Catalyst::Upgrading>, L<Plack>, L<PSGI::FAQ>, L<PSGI>.
+
+=head1 AUTHORS
+
+Catalyst Contributors, see Catalyst.pm
+
+=head1 COPYRIGHT
+
+This library is free software. You can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut

diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod
index a0896f9..c12ea90 100644 (file)
--- a/lib/Catalyst/Upgrading.pod
+++ b/lib/Catalyst/Upgrading.pod
@@ -14,8 +14,10 @@ be taken with this upgrade and that testing should be greater than would be
 the case with a minor point update.
 
 It is highly recommended that you become familar with the L<Plack> ecosystem
-and documentation.  Being able to take advantage of L<Plack> development and
-middleware is a major bonus to this upgrade.
+and documentation. Being able to take advantage of L<Plack> development and
+middleware is a major bonus to this upgrade. Documentation about how to
+take advantage of L<Plack::Middleware> by writing your own C<< .psgi >> file
+is contained in L<Catalyst::PSGI>.
 
 If you have created a custom subclass of L<Catalyst:Engine> you will need to
 convert it to be a subclass of L<Plack::Handler>.