+=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
BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
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 attributes, then they need to be made lazy
-to correctly initialize.
+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
+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<all> Moose features work as expected.
=head3 use Moose in MyApp
package MyApp;
use Moose;
+ use Catalyst;
+
extends 'Catalyst';
+
+ __PACKAGE__->config( name => 'MyApp' );
__PACKAGE__->setup(qw/
ConfigLoader
/);
*$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