From: Jesse Sheidlower Date: Sun, 14 Aug 2011 20:08:36 +0000 (-0400) Subject: Doc changes to Upgrading and PSGI. X-Git-Tag: 5.9000~7 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=e60068484721132e6fe1855f53f9542d8bb17a35 Doc changes to Upgrading and PSGI. --- diff --git a/lib/Catalyst/PSGI.pod b/lib/Catalyst/PSGI.pod index 1aec1f8..b12b76b 100644 --- a/lib/Catalyst/PSGI.pod +++ b/lib/Catalyst/PSGI.pod @@ -6,29 +6,46 @@ Catalyst::PSGI - How Catalyst and PSGI work together =head1 SYNOPSIS -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. +The L specification defines an interface between web servers and +Perl-based web applications and frameworks. It supports the writing of +portable applications that can be run using various methods (as a +standalone server, or using mod_perl, FastCGI, etc.). L is a set +of middleware tools for running Perl applications compatible with the +PSGI specification. -This has been changed so that all of that work is done by Catalyst just implementing -the L specification, and using L's adaptors to implement that functionality. +Catalyst used to contain an entire set of C<< Catalyst::Engine::XXXX >> +classes to handle various web servers and environments (e.g. CGI, +FastCGI, mod_perl) etc. -This means that we can share common code, and fixes for specific web servers. +This has been changed in Catalyst 5.9 so that all of that work is done +by Catalyst implementing the L specification, using L's +adaptors to implement that functionality. + +This means that we can share common code, and share 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 -for specifics about your web server deployment). +If you already have a Catalyst application, then you should be able to +upgrade to the latest release with little or no trouble (see the notes +in L for specifics about your web server +deployment). =head1 Writing your own PSGI file. -=head2 What is a .psgi file +=head2 What is a .psgi file? + +A C<< .psgi >> file lets you control how your application code reference +is built. Catalyst will automatically handle this for you, but it's +possible to do it manually by creating a C file in the root +of your application. -A C<< .psgi >> file lets you manually controll how your application code reference is built. +=head2 Why would I want to write my own .psgi file? -Catalyst normally takes care of this for you, but it's possible to do it manually by -creating a C file in the root of your application. +Writing your own .psgi file allows you to use the alternate L command +to start your application, and allows you to add classes and extensions +that implement L, such as L +or L. The simplest C<.psgi> file for an application called C would be: @@ -38,25 +55,19 @@ The simplest C<.psgi> file for an application called C would be: 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 be applied if you manually create -a psgi file yourself. Details of these middlewares can be found below. +Note that Catalyst will apply a number of middleware components for you +automatically, and these B be applied if you manually create a +psgi file yourself. Details of these components can be found below. Additional information about psgi files can be found at: L -=head2 Why would I want to make a .psgi file? - -Writing your own .psgi file allows you to use the alternate L command -to start your application, and allows you to add classes and extensions -that implement L, such as L, -or L. - -=head2 What is in the .psgi Catalyst generates by default? +=head2 What is in the .psgi file Catalyst generates by default? -Catalyst generates an application which, if the C<< using_frontend_proxy >> -setting is on, is wrapped in L, and contains some -engine specific fixes for uniform behaviour, as contained in: +Catalyst generates an application which, if the C<< using_frontend_proxy +>> setting is on, is wrapped in L, and +contains some engine-specific fixes for uniform behaviour, as contained +in: =over @@ -68,11 +79,11 @@ engine specific fixes for uniform behaviour, as contained in: =back -If you override the default by providing your own C<< .psgi >> file, then -none of these things will be done automatically for you by the PSGI -application returned when you call C<< MyApp->psgi_app >>, and if you need -any of this functionality, you'll need to implement this in your C<< .psgi >> -file yourself. +If you override the default by providing your own C<< .psgi >> file, +then none of these things will be done automatically for you by the PSGI +application returned when you call C<< MyApp->psgi_app >>. Thus, if you +need any of this functionality, you'll need to implement this in your +C<< .psgi >> file yourself. An apply_default_middlewares method is supplied to wrap your application in the default middlewares if you want this behaviour and you are providing diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index f15995e..1955bfb 100644 --- a/lib/Catalyst/Upgrading.pod +++ b/lib/Catalyst/Upgrading.pod @@ -4,14 +4,17 @@ Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst =head1 Upgrading to Catalyst 5.9 -The major change is that L now replaces most of the subclasses of -L. If you are using one of the standard subclasses of -L this should be a straightforward upgrade for you. It was -a design goal for this release to be as backwardly compatible as possible. -However since L is different from L it is possible -that edge case differences exist. Therefore we recommend care be taken with -this upgrade and that testing should be greater than would be the case with a -minor point update. +The major change is that L, a toolkit for using the L +stack, now replaces most of the subclasses of L. If +you are using one of the standard subclasses of L this +should be a straightforward upgrade for you. It was a design goal for +this release to preserve as much backwards compatibility as possible. +However, since L is different from L, it is +possible that differences exist for edge cases. Therefore, we recommend +that care be taken with this upgrade and that testing should be greater +than would be the case with a minor point update. Please inform the +Catalyst developers of any problems so that we can fix them and +incorporate tests. It is highly recommended that you become familiar with the L ecosystem and documentation. Being able to take advantage of L development and @@ -19,33 +22,33 @@ middleware is a major bonus to this upgrade. Documentation about how to take advantage of L by writing your own C<< .psgi >> file is contained in L. -If you have created a custom subclass of L you will need to -convert it to be a subclass of L. +If you have created a custom subclass of L, you will +need to convert it to be a subclass of L. If you are using the L engine, L, this new release supersedes that code. -If you are using a subclass of L that is aimed at nonstandard -or internal / testing uses, such as L you should -still be able to continue using that engine. +If you are using a subclass of L that is aimed at +nonstandard or internal/testing uses, such as +L, you should still be able to continue +using that engine. Advice for specific subclasses of L follows: =head2 Upgrading the FastCGI Engine -No upgrade needed if your myapp_fastcgi.pl script is already upgraded -enough to use L. +No upgrade is needed if your myapp_fastcgi.pl script is already upgraded +to use L. =head2 Upgrading the mod_perl / Apache Engines -The engines that are build upon the various iterations of mod_perl, -L and -L should be seamless upgrades and will -work using using L or L -as required. +The engines that are built upon the various iterations of mod_perl, +L and L, +should be seamless upgrades and will work using using +L or L as required. -L, is however no longer supported, as Plack -does not support mod_perl version 1.99 +L, however, is no longer supported, as +Plack does not support mod_perl version 1.99 =head2 Upgrading the HTTP Engine @@ -56,7 +59,7 @@ script is upgraded to use L. =head2 Upgrading the CGI Engine If you were using L there is no upgrade needed if your -myapp_cgi.pl script is already upgraded enough to use L. +myapp_cgi.pl script is already upgraded to use L. =head2 Upgrading the Preforking Engine @@ -75,33 +78,34 @@ and implement a C class that looks like this: 1; -This takes advantage of the new script system, and adds a number of options to -the standard server script as extra options are added by Starman. +This takes advantage of the new script system, and will add a number of +options to the standard server script as extra options are added by +Starman. More information about these options can be seen at L. An alternate route to implement this functionality is to write a simple .psgi -file for your application, then use the L utility to start the +file for your application, and then use the L utility to start the server. =head2 Upgrading the PSGI Engine -If you were using L this new release supersedes this -engine in supporting L. By default the Engine is now always L. -As a result, you can stop depending on L in your -C. +If you were using L, this new release supersedes +this engine in supporting L. By default the Engine is now always +L. As a result, you can remove the dependency on +L in your C. Applications that were using L previously should entirely continue to work in this release with no changes. -However, if you have an C script, then you no longer -need to specify the PSGI engine. Instead, the L application class -now has a new method C which returns a L compatible coderef -which you can wrap in middleware of your choice. +However, if you have an C script, then you no longer need to +specify the PSGI engine. Instead, the L application class now +has a new method C which returns a L compatible coderef +which you can wrap in the middleware of your choice. Catalyst will use the .psgi for your application if it is located in the C -directory of the application +directory of the application. For example, if you were using L in the past, you will have written (or generated) a C