X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FUpgrading.pod;h=1955bfb642845dba22be309dd82fd48a74669ef9;hb=e60068484721132e6fe1855f53f9542d8bb17a35;hp=e51e18ad80b9fd62285dc85a9c74844999333a03;hpb=75d68821eb2e68df557b479fd5a869590e094642;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index e51e18a..1955bfb 100644 --- a/lib/Catalyst/Upgrading.pod +++ b/lib/Catalyst/Upgrading.pod @@ -2,48 +2,53 @@ Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst -=head1 Upgrading to Catalyst 5.90 - -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 would be -possible that edge case differences would 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. - -It is highly recommended that you become familar with the L ecosystem -and documentation. Being able to take advantage of L development and -middleware is a major bonus to this upgrade. - -If you have created a custom subclass of L you will need to -convert it to be a subclass of L. +=head1 Upgrading to Catalyst 5.9 + +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 +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 are using the L engine, L, this new -release supercedes that code. +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 seemless 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??? FIXME - is this true? +L, however, is no longer supported, as +Plack does not support mod_perl version 1.99 =head2 Upgrading the HTTP Engine @@ -54,32 +59,53 @@ 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 If you were using L then L -is automatically loaded. +is automatically loaded. You should (at least) change your C +to depend on Starman. + +You can regenerate your C script with C +and implement a C class that looks like this: + + package MyApp::Script::Server; + use Moose; + use namespace::autoclean; + + extends 'CatalystX::Script::Server::Starman'; + + 1; -XXX FIXME - note how to run Starman with different options. +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, and then use the L utility to start the +server. =head2 Upgrading the PSGI Engine -If you were using L this new release supercedes 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