X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FUpgrading.pod;h=0e4b76f2568599fb8112894cbc9a30fa65472f42;hb=5b6f82d2a814300635703289c910683f4133ebdc;hp=69141d7c26b08d3fa32b6fb602c3eae068d173eb;hpb=38f90e4941605c36b800159739cc030ad44905b2;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index 69141d7..0e4b76f 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. @@ -23,9 +27,23 @@ 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. -To be able to do this, however, entails that the graph of superclasses for each -class must be linearizable using the C3 algorithm. Unfortunately, when -superclasses are being used as mixins, it is easy to get this wrong. +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: @@ -38,13 +56,10 @@ Most common is the case of: package GoesBang; use base qw/Component1 Component2/; -And the Catalyst plugin most often causing this, is -L - if you are using this plugin -and see issues, then please upgrade! +Any situation like this will cause your application to fail to start. -This 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. +Please see additional documentation about this issue, and how to resolve it in +L. =head2 Components which inherit from Moose::Object before Catalyst::Component @@ -57,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 @@ -82,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 @@ -103,7 +126,11 @@ etc) then the correct technique is: package MyApp; use Moose; + use Catalyst; + extends 'Catalyst'; + + __PACKAGE__->config( name => 'MyApp' ); __PACKAGE__->setup(qw/ ConfigLoader /); @@ -124,7 +151,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); @@ -132,7 +159,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 { @@ -157,7 +184,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 @@ -203,7 +230,7 @@ The following test demonstrates the problem: BaseClass->foo('base class'); Child->foo('sub class'); - + use Test::More; isnt(BaseClass->can('foo'), Child->can('foo')); @@ -236,6 +263,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 @@ -270,7 +302,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 @@ -287,7 +319,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