X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FUpgrading.pod;h=fbad34cbcd3db6ae86e5d72c046a4ad95c3b0776;hb=7ebac5f89810aab16ec76fc28dea45e936172a67;hp=92db2ae56424ef5d3ac65555251c603db6c90cb6;hpb=8f912f0befe612150816bd29cb931de1ab73a499;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index 92db2ae..fbad34c 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 @@ -38,12 +40,12 @@ enough to use L. The engines that are build upon the various iterations of mod_perl, L and -L should be seemless upgrades and will +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? +does not support mod_perl version 1.99 =head2 Upgrading the HTTP Engine @@ -61,11 +63,13 @@ myapp_cgi.pl script is already upgraded enough to use L. If you were using L then L is automatically loaded. -XXX FIXME - note how to run Starman with different options. +If you were customising your server script to pass options to the prefork engine, +then this is no longer supported. The recommended route to implement this functionality +is to write a simple .psgi file for your application, then use the L utility. =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. @@ -75,7 +79,7 @@ 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 +now has a new method C which returns a L compatible coderef which you can wrap in middleware of your choice. Catalyst will use the .psgi for your application if it is located in the C @@ -101,18 +105,34 @@ Instead, you now say: builder { enable ... #enable your desired middleware - MyCatalystApp->raw_psgi_app; + MyCatalystApp->psgi_app; }; -And also rename C<< script/myapp.psgi >> to C<< myapp.psgi >>. +In the simplest case: -If you rename your .psgi file without these modifications, then any tests run via + 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! + +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 +142,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 +157,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 +198,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 +209,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 +269,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 +556,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.