X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FUpgrading.pod;h=4fec7d3275882d414b5466450ea2fb783b45672a;hb=14148e06102a2c318d4509e7a9d3345baeef4e8c;hp=09b6e682f3f9aff50b2df335021687724202913e;hpb=82452b29b497132f2ae9261635344543a0a2c3f6;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index 09b6e68..4fec7d3 100644 --- a/lib/Catalyst/Upgrading.pod +++ b/lib/Catalyst/Upgrading.pod @@ -2,26 +2,28 @@ Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst -=head1 Upgrading to Catalyst 5.90 +=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 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. +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. -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. +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 @@ -37,13 +39,15 @@ enough 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. +L (for mod_perl 1, and Apache 1.x) and +L (for mod_perl 2, and Apache 2.x) +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? +does not support mod_perl version 1.99. This is unlikely to be a problem +for anyone, as 1.99 was a brief beta-test release for mod_perl 2, and any users +are encouraged to upgrade to a supported release of Apache 2 and mod_perl 2. =head2 Upgrading the HTTP Engine @@ -59,13 +63,33 @@ myapp_cgi.pl script is already upgraded enough 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. -XXX FIXME - note how to run Starman with different options. +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; + +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. + +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 +server. =head2 Upgrading the PSGI Engine -If you were using L this new release supercedes this +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. @@ -104,15 +128,31 @@ Instead, you now say: MyCatalystApp->psgi_app; }; -And also rename C<< script/myapp.psgi >> to C<< myapp.psgi >>. +In the simplest case: + + MyCatalystApp->setup_engine('PSGI'); + my $app = sub { MyCatalystApp->run(@_) } + +becomes + + MyCatalystApp->setup_engine('PSGI'); + my $app = MyCatalystApp->psgi_app(@_); + +B: + + my $app = sub { MyCatalystApp->psgi_app(@_) }; + # If you make ^^ this mistake, your app won't work, and will confuse the hell out of you! -If you rename your .psgi file without these modifications, then any tests run via +You can now move C<< script/myapp.psgi >> to C<< myapp.psgi >> and the built-in +Catalyst scripts and your test suite will start using your .psgi file. + +B If you rename your .psgi file without these modifications, then any tests run via L will not be compatible with the new release, and will result in the development server starting, rather than the expected test running. =head2 Engines which are known broken -The following engines B work as of Catalyst version 5.90. The core +The following engines B work as of Catalyst version 5.9. 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 @@ -122,6 +162,14 @@ to the engine code. =item Catalyst::Engine::Wx +=item Catalyst::Engine::Zeus + +=item Catalyst::Engine::JobQueue::POE + +=item Catalyst::Engine::XMPP2 + +=item Catalyst::Engine::SCGI + =back =head2 Engines with unknown status @@ -129,23 +177,34 @@ to the engine code. The following engines have untested or unknown compatibility. Reports are highly welcomed: - Catalyst::Engine::Embeddable - needs testing, should work? - Catalyst::Engine::XMPP2 - Catalyst::Engine::SCGI - Catalyst::Engine::Mojo - 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) +=over + +=item Catalyst::Engine::Mojo + +=item Catalyst::Engine::Server (Marked as Deprecated) + +=item Catalyst::Engine::HTTP::POE (Marked as Deprecated) + +=back + +=head2 Specifying the engine in the call to ->setup + +XXX FIXME + +=head2 Plack functionality + +See L. -=head2 Using middleware +=head2 Tests in 5.9 -XXX Should this be here or elsewhere? +Tests should generally work the same in Catalyst 5.9, however there are some differences. -=head2 Making an app.psgi file +Previously, if using L and doing local requests (against a local server), +if the application threw an exception then this exception propagated into the test. -=head2 Running with plackup? +This behavior has been removed, and now a 500 response will be returned to the test. +This change unifies behavior, to make local test requests behave similarly to remote +requests. =head1 Upgrading to Catalyst 5.80 @@ -159,7 +218,7 @@ issues upgrading to this release. Most issues found with pre-existing components have been easy to solve. This document provides a complete description of behavior changes which may cause compatibility issues, and of new Catalyst warnings which -be unclear. +might be unclear. If you think you have found an upgrade-related issue which is not covered in this document, please email the Catalyst list to discuss the problem. @@ -170,7 +229,7 @@ this document, please email the Catalyst list to discuss the problem. You can only apply method modifiers after the application's C<< ->setup >> method has been called. This means that modifiers will not work with methods -which run during the call to C<< ->setup >>. +run during the call to C<< ->setup >>. See L for more information about using L in your applications. @@ -230,7 +289,7 @@ you identify the ones in conflict, and resolve them. To be able to generate a linear @ISA, the list of superclasses for each class must be resolvable using the C3 algorithm. Unfortunately, when superclasses are being used as mixins (to add functionality used in your class), -and with multiple inheritence, it is easy to get this wrong. +and with multiple inheritance, it is easy to get this wrong. Most common is the case of: @@ -517,7 +576,7 @@ is highly deprecated. The first time one of these methods is called, a warning will be emitted: Class $class is calling the deprecated method Catalyst::Dispatcher::$public_method_name, - this will be removed in Catalyst 5.9X + this will be removed in Catalyst 5.9 You should B be calling any of these methods from application code.