X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FUpgrading.pod;h=dc5486110c1488e774eed105b3f59155456512ac;hb=93a57b4bb80efb5cee28d335a0a2e6a681ecd7d7;hp=47b6971de254fa7514c2ed81a03212705b19d0d5;hpb=5d5f4a737bb6e3ef3c1b4c35ee91d162417b2552;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index 47b6971..dc54861 100644 --- a/lib/Catalyst/Upgrading.pod +++ b/lib/Catalyst/Upgrading.pod @@ -2,11 +2,11 @@ Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst -=head2 Upgrading to Catalyst 5.90 +=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 +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 @@ -31,73 +31,112 @@ Advice for specific subclasses of L follows: =head2 Upgrading the FastCGI Engine - TBD +No upgrade needed if your myapp_fastcgi.pl script is already upgraded +enough to use L. =head2 Upgrading the mod_perl / Apache Engines -The three engines that are build upon the various iterations of mod_perl, -L, L and +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. -=head2 Upgrading the HTTP Engine +L, is however no longer supported, as Plack +does not support mod_perl version 1.99??? FIXME - is this true? -If you were using L (the default development server -that comes with the L distribution) you should now use... +=head2 Upgrading the HTTP Engine - TBD +The default development server that comes with the L distribution +should continue to work as expected with no changes as long as your C +script is upgraded to use L. =head2 Upgrading the CGI Engine -If you were using L you should now use... - - TBD +If you were using L there is no upgrade needed if your +myapp_cgi.pl script is already upgraded enough to use L. =head2 Upgrading the Preforking Engine -If you were using L you should now use... +If you were using L then L +is automatically loaded. - TBD +XXX FIXME - note how to run Starman with different options. -=head2 Upgrading the Restarter Engines +=head2 Upgrading the PSGI Engine -If you were using L or -L these are now longer part of the -L distribution. You should now use... +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. Additionally, if you have an C script 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. - TBD +For example, if you were using L in the past, you will +have written (or generated) an C file similar to this one: -=head2 Upgrading the PSGI Engine + use Plack::Builder; + use MyCatalytApp; -If you were using L this new release supercedes this -engine in supporting L. You should now do... + MyCatalystApp->setup_engine('PSGI'); + + builder { + enable ... # enable your desired middleware + sub { MyCatalystApp->run(@_) }; + }; - TBD +Instead, you should now just do: + + use Plack::Builder; + use MyCatalystApp; + + builder { + enable ... #enable your desired middleware + MyCatalystApp->psgi_app; + }; + +Applications that were using and deploying via L +previously should entirely continue to work in this release with no changes, +however if you were using Catalyst::Engine::PSGI previously, then this is +not compatible with L in the new version, and instead of +running a test server + +=head2 Engines which are known broken + +The following engines B work as of Catalyst version 5.90. The core +team is extremely happy to work with the developers and/or users of these +engines to help them port to the new Plack/Engine system, however applications +which are currently using these engines B run without modification +to the engine code. + +=over + +=item Catalyst::Engine::Wx + +=back =head2 Engines with unknown status The following engines have untested or unknown compatibility. Reports are highly welcomed: - Catalyst::Engine::Embeddable + Catalyst::Engine::Embeddable - needs testing, should work? Catalyst::Engine::XMPP2 Catalyst::Engine::SCGI Catalyst::Engine::Mojo - Catalyst::Engine::Zeus - Catalyst::Engine::JobQueue::POE - Catalyst::Engine::Wx - Catalyst::Engine::Stomp + Catalyst::Engine::Zeus - broken for ages + Catalyst::Engine::JobQueue::POE - broken for ages + Catalyst::Engine::Stomp - fixed Catalyst::Engine::Server (Marked as Deprecated) Catalyst::Engine::HTTP::POE (Marked as Deprecated) -=head2 Engines known to not be compatible. +=head2 Using middleware + +XXX Should this be here or elsewhere? -If you are using one of the following L subclasses, your -application may require significant work after upgrading. We recommend you -test heavily and sandbox your upgrade. +=head2 Making an app.psgi file - TBD +=head2 Running with plackup? =head1 Upgrading to Catalyst 5.80