X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FUpgrading.pod;h=608f42603c11eb934652c9b1e0c636121308af88;hb=5d06547d51fe24fbaeea02047325ed4ef6dc4459;hp=ae5a6ffa37240d12003e88fc57a247afa01625f7;hpb=4e68badce837f4ebc4567faeaa707bbae88c5ffd;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index ae5a6ff..608f426 100644 --- a/lib/Catalyst/Upgrading.pod +++ b/lib/Catalyst/Upgrading.pod @@ -1,3 +1,7 @@ +=head1 NAME + +Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst + =head1 Upgrading to Catalyst 5.80 Most applications and plugins should run unaltered on Catalyst 5.80. @@ -16,6 +20,47 @@ this document, then please email the Catalyst list to discuss the problem. =head1 Known backwards compatibility breakages. +=head2 Issues with Class::C3 + +Catalyst 5.80 uses L method dispatch order. This is built into +perl 5.10, and comes via L for perl 5.8. This replaces L +with L, forcing all components to resolve methods using +C3, rather than the unpredictable dispatch order of L. + +This issue is characterised by your application failing to start due to an +error message about having a non-linear @ISA. + +The Catalyst plugin most often causing this, is +L - if you are using this plugin +and see issues, then please upgrade - and please try upgrading your plugins +if you have this issue, as it has been fixed. Note that Makefile.PL in the +distribution will warn about known incompatible components. + +This issue can, however, be found in your own application - the only solution is +to go through each base class of the class the error was reported against, until +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. + +Most common is the case of: + + package Component1; # Note, this is the common case + use base qw/Class::Accessor::Fast Class::Data::Inheritable/; + + package Component2; # Accidentally saying it this way round causes fail. + use base qw/Class::Data::Inheritable Class::Accessor::Fast/; + + package GoesBang; + use base qw/Component1 Component2/; + +Any situation like this will cause your application to fail to start. + +Please see additional documentation about this issue, and how to resolve it in +L. + =head2 Components which inherit from Moose::Object before Catalyst::Component Moose components which say: @@ -27,7 +72,7 @@ Moose components which say: to use the constructor provided by Moose, whilst working (if you do some hacks with the C< BUILDARGS > method), will not work with Catalyst 5.80 as C inherits from C, and so C< @ISA > fails -to linearise. +to linearize. The fix for this is to not inherit directly from C yourself. Having components which do not inherit their constructor from @@ -52,10 +97,18 @@ compatible way is: BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever Note that the C< extends > declaration needs to occur in a begin block for -L to operate correctly. You also don't get the L -constructor, and therefore attribute initialization will not work as normally -expected. If you want to use Moose attributes, then they need to be made lazy -to correctly initialize. +L to operate correctly. + +You also don't get the L constructor, and therefore attribute +initialization will not work as normally expected. If you want to use Moose +attributes, then they need to be made lazy to correctly initialize. + +Note that this only applies if your component needs to maintain component +backwards compatibility for Catalyst versions before 5.71001 - in 5.71001 +attributes work as expected, and the BUILD method is called normally +(although BUILDARGS is not). + +If you depend on Catalyst 5.8, then B Moose features work as expected. =head3 use Moose in MyApp @@ -94,7 +147,7 @@ to use L to name the subroutine. Example: *$full_method_name = subname $full_method_name, sub { ... }; Additionally, you can take advantage of Catalysts use of L and -install the closure using the appropriate metaclass. Example: +install the closure using the appropriate meta class. Example: use Class::MOP; my $metaclass = Moose::Meta::Class->initialize($package_name); @@ -102,7 +155,7 @@ install the closure using the appropriate metaclass. Example: =head2 Hooking into application setup -To execute code during application startup the following snippet in MyApp.pm +To execute code during application start-up the following snippet in MyApp.pm used to work: sub setup { @@ -127,7 +180,7 @@ The right way to do it is this: ... # things to do after the actual setup }; -The setup_finalize hook was introduced as a way to void this issue. +The setup_finalize hook was introduced as a way to avoid this issue. =head2 Components with a new method which returns false @@ -206,6 +259,11 @@ COMPONENT method in your @ISA. =head1 WARNINGS +=head2 Catalyst::Base + +Any code using L will now warn, and this module will be removed +in a future release. + =head2 Methods in Catalyst::Dispatcher The following methods in Catalyst::Dispatcher are both an implementation @@ -240,7 +298,7 @@ should change to using the public API, or, if you do not feel the public API adequately supports your use-case, please email the development list to discuss what API features you need so that you can be appropriately supported. -=head2 Class naming to packages defined does not correspond. +=head2 Class files with names that don't correspond to the packages they define In this version of Catalyst, if a component is loaded from disk, but no symbols are defined in that component's name space after it is loaded, this @@ -257,7 +315,7 @@ to B of the packages defined within that component. =head2 $c->plugin method -Calling the plugin method is deprecated, and calling it at runtime is B. Instead you are recommended to use L< Catalyst::Model::Adaptor > or similar to