+=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.
with L<Class::C3::Adopt::NEXT>, forcing all components to resolve methods using
C3, rather than the unpredictable dispatch order of L<NEXT>.
-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<Catalyst::Plugin::Session::Store::FastMmap> - 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 GoesBang;
use base qw/Component1 Component2/;
-And the Catalyst plugin most often causing this, is
-L<Catalyst::Plugin::Sesssion::Store::FastMMap> - 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<Class::C3::Adopt::NEXT>.
=head2 Components which inherit from Moose::Object before Catalyst::Component
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<Catalyst::Component> inherits from C<Moose::Object>, and so C< @ISA > fails
-to linearise.
+to linearize.
The fix for this is to not inherit directly from C<Moose::Object>
yourself. Having components which do not inherit their constructor from
Note that the C< extends > declaration needs to occur in a begin block for
L<attributes> to operate correctly.
-You also don't get the L<Moose::Object> constructor, and therefore attribute
-initialization will not work as normally expected. If you want to use Moose
+You also don't get the L<Moose::Object> 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).
+(although BUILDARGS is not).
If you depend on Catalyst 5.8, then B<all> Moose features work as expected.
*$full_method_name = subname $full_method_name, sub { ... };
Additionally, you can take advantage of Catalysts use of L<Class::MOP> 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);
=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 {
... # 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
BaseClass->foo('base class');
Child->foo('sub class');
-
+
use Test::More;
isnt(BaseClass->can('foo'), Child->can('foo'));
=head1 WARNINGS
+=head2 Catalyst::Base
+
+Any code using L<Catalyst::Base> 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
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
=head2 $c->plugin method
-Calling the plugin method is deprecated, and calling it at runtime is B<highly
+Calling the plugin method is deprecated, and calling it at run time is B<highly
deprecated>.
Instead you are recommended to use L< Catalyst::Model::Adaptor > or similar to
projects / catagits/Catalyst-Runtime.git / blobdiff