From: Jesse Sheidlower Date: Tue, 4 Jul 2006 02:27:52 +0000 (+0000) Subject: Installation doc adds; tweaks to docs of C.pm X-Git-Tag: 5.7099_04~442 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=8641855930b874893d1a898a552799f999a2084a Installation doc adds; tweaks to docs of C.pm --- diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm index b3cf87b..d7b53ae 100644 --- a/lib/Catalyst.pm +++ b/lib/Catalyst.pm @@ -87,6 +87,7 @@ Catalyst - The Elegant MVC Web Application Framework =head1 SYNOPSIS + # Install Catalyst::Devel for helpers and other development tools # use the helper to create a new application catalyst.pl MyApp @@ -171,7 +172,10 @@ See L for additional information. =head1 DESCRIPTION -Catalyst is a modern framework for making web applications without the pain usually associated with this process. This document is a reference to the main Catalyst application. If you are a new user, we suggest you start with L or L +Catalyst is a modern framework for making web applications without the +pain usually associated with this process. This document is a reference +to the main Catalyst application. If you are a new user, we suggest you +start with L or L. See L for more documentation. @@ -196,15 +200,16 @@ arguments when Catalyst is loaded: use Catalyst qw/-Debug My::Module/; The position of plugins and flags in the chain is important, because -they are loaded in exactly the order in which they appear. +they are loaded in the order in which they appear. The following flags are supported: =head2 -Debug Enables debug output. You can also force this setting from the system -environment with CATALYST_DEBUG or _DEBUG. The environment settings -override the app, with _DEBUG having highest priority. +environment with CATALYST_DEBUG or _DEBUG. The environment +settings override the application, with _DEBUG having the highest +priority. =head2 -Engine @@ -217,7 +222,7 @@ C prefix of the engine name, i.e.: Forces Catalyst to use a specific home directory, e.g.: - use Catalyst qw[-Home=/usr/sri]; + use Catalyst qw[-Home=/usr/mst]; =head2 -Log @@ -234,7 +239,7 @@ stringifies to the action name. See L. =head2 $c->namespace -Returns the namespace of the current action, i.e., the uri prefix +Returns the namespace of the current action, i.e., the URI prefix corresponding to the controller of the current action. For example: # in Controller::Foo::Bar @@ -244,8 +249,9 @@ corresponding to the controller of the current action. For example: =head2 $c->req -Returns the current L object. See -L. +Returns the current L object, giving access to +information about the current client request (including parameters, +cookies, HTTP headers, etc.). See L. =head2 REQUEST FLOW HANDLING @@ -253,7 +259,7 @@ L. =head2 $c->forward( $class, $method, [, \@arguments ] ) -Forwards processing to another action, by it's private name. If you give a +Forwards processing to another action, by its private name. If you give a class name but no method, C is called. You may also optionally pass arguments in an arrayref. The action will receive the arguments in C<@_> and C<$c-Ereq-Eargs>. Upon returning from the function, @@ -267,15 +273,15 @@ call to forward. $c->forward(qw/MyApp::Model::DBIC::Foo do_stuff/); $c->forward('MyApp::View::TT'); -Note that forward implies an C<> around the call (well, actually -C does), thus de-fatalizing all 'dies' within the called action. If -you want C to propagate you need to do something like: +Note that forward implies an C<> around the call (actually +C does), thus de-fatalizing all 'dies' within the called +action. If you want C to propagate you need to do something like: $c->forward('foo'); die $c->error if $c->error; -Or make sure to always return true values from your actions and write your code -like this: +Or make sure to always return true values from your actions and write +your code like this: $c->forward('foo') || return; @@ -298,7 +304,7 @@ sub detach { my $c = shift; $c->dispatcher->detach( $c, @_ ) } =head2 $c->res -Returns the current L object. +Returns the current L object, q.v. =head2 $c->stash @@ -306,7 +312,9 @@ Returns a hashref to the stash, which may be used to store data and pass it between components during a request. You can also set hash keys by passing arguments. The stash is automatically sent to the view. The stash is cleared at the end of a request; it cannot be used for -persistent storage. +persistent storage (for this you must use a session; see +L for a complete system integrated with +Catalyst). $c->stash->{foo} = $bar; $c->stash( { moose => 'majestic', qux => 0 } ); @@ -380,8 +388,6 @@ sub clear_errors { } - - # search via regex sub _comp_search { my ( $c, @names ) = @_; @@ -472,7 +478,8 @@ Gets a L instance by name. $c->controller('Foo')->do_stuff; -If name is omitted, will return the controller for the dispatched action. +If the name is omitted, will return the controller for the dispatched +action. =cut @@ -524,8 +531,9 @@ Gets a L instance by name. $c->view('Foo')->do_stuff; -If the name is omitted, it will look for a config setting 'default_view', -or check if there is only one view, and forward to it if that's the case. +If the name is omitted, it will look for a config setting +'default_view', or check if there is only one view, and forward to it if +that's the case. =cut @@ -628,9 +636,9 @@ sub config { =head2 $c->log -Returns the logging object instance. Unless it is already set, Catalyst sets -this up with a L object. To use your own log class, set the -logger with the C<< __PACKAGE__->log >> method prior to calling +Returns the logging object instance. Unless it is already set, Catalyst +sets this up with a L object. To use your own log class, +set the logger with the C<< __PACKAGE__->log >> method prior to calling C<< __PACKAGE__->setup >>. __PACKAGE__->log( MyLogger->new ); @@ -640,8 +648,8 @@ And later: $c->log->info( 'Now logging with my own logger!' ); -Your log class should implement the methods described in the -L man page. +Your log class should implement the methods described in +L. =head2 $c->debug @@ -852,17 +860,18 @@ EOF =head2 $c->uri_for( $path, @args?, \%query_values? ) -Merges path with C<$c-Erequest-Ebase> for absolute uri's and -with C<$c-Enamespace> for relative uri's, then returns a -normalized L object. If any args are passed, they are added at the -end of the path. If the last argument to uri_for is a hash reference, -it is assumed to contain GET parameter key/value pairs, which will be -appended to the URI in standard fashion. +Merges path with C<$c-Erequest-Ebase> for absolute URIs and with +C<$c-Enamespace> for relative URIs, then returns a normalized L +object. If any args are passed, they are added at the end of the path. +If the last argument to C is a hash reference, it is assumed to +contain GET parameter key/value pairs, which will be appended to the URI +in standard fashion. -Instead of $path, you can also optionally pass a $action object which will -be resolved to a path using $c->dispatcher->uri_for_action; if the first -element of @args is an arrayref it is treated as a list of captures to be -passed to uri_for_action. +Instead of C<$path>, you can also optionally pass a C<$action> object +which will be resolved to a path using +C<$c-Edispatcher-Euri_for_action>; if the first element of +C<@args> is an arrayref it is treated as a list of captures to be passed +to C. =cut @@ -1762,9 +1771,10 @@ sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) } =head2 $c->setup_components -Sets up components. Specify a C config option to pass additional options -directly to L. To add additional search paths, specify a key named -C as an array reference. Items in the array beginning with C<::> will have the +Sets up components. Specify a C config option to pass +additional options directly to L. To add additional +search paths, specify a key named C as an array +reference. Items in the array beginning with C<::> will have the application class name prepended to them. =cut @@ -2108,8 +2118,8 @@ the plugin name does not begin with C. =head2 $c->stack -Returns an arrayref of the internal execution stack (actions that are currently -executing). +Returns an arrayref of the internal execution stack (actions that are +currently executing). =head2 $c->write( $data ) @@ -2197,9 +2207,9 @@ If you do not wish to use the proxy support at all, you may set: =head1 THREAD SAFETY -Catalyst has been tested under Apache 2's threading mpm_worker, mpm_winnt, -and the standalone forking HTTP server on Windows. We believe the Catalyst -core to be thread-safe. +Catalyst has been tested under Apache 2's threading C, +C, and the standalone forking HTTP server on Windows. We +believe the Catalyst core to be thread-safe. If you plan to operate in a threaded environment, remember that all other modules you are using must also be thread-safe. Some modules, most notably diff --git a/lib/Catalyst/Manual/Installation.pod b/lib/Catalyst/Manual/Installation.pod index fdf9f51..1d878a2 100644 --- a/lib/Catalyst/Manual/Installation.pod +++ b/lib/Catalyst/Manual/Installation.pod @@ -8,21 +8,34 @@ How to install Catalyst. =head1 INSTALLATION -On one hand, Catalyst gains immediate power and flexibility -through its use of CPAN (the Comprehensive Perl Archive -Network, an enormous global repository containing over 10,000 -free modules). On the other hand, Catalyst's reliance on CPAN -can complicate initial installations, especially in -shared-hosting environments where you, the user, do not have -easy control over what versions other modules are installed. - -It is worth stressing that the difficulties found in installing -Catalyst are caused not by anything intrinsic to Catalyst -itself, but rather by the interrelated dependencies of a large -number of required modules. - -Fortunately, there are a growing number of methods that can -dramatically ease this undertaking: +One of the frequent problems reported by new users of Catalyst is that +it can be extremely time-consuming and difficult to install. + +One of the great strengths of Perl as a programming language is its use +of CPAN, the Comprehensive Perl Archive Network, an enormous global +repository containing over 10,000 free modules. For almost any basic +task--and a very large number of non-basic ones--there is a module on +CPAN that will help you. Catalyst has taken advantage of this, and uses +a very large number of CPAN modules, rather than reinventing the wheel +over and over again. On the one hand, Catalyst gains power and +flexibility through this re-use of existing code. On the other hand, +Catalyst's reliance on CPAN can complicate initial installations, +especially in shared-hosting environments where you, the user, do not +have easy control over what versions of other modules are installed. + +It is worth stressing that the difficulties found in installing Catalyst +are caused not by anything intrinsic to Catalyst itself, but rather by +the interrelated dependencies of a large number of required modules. + +Fortunately, there are a growing number of methods that can dramatically +ease this undertaking. Note that for many of these, you will probably +need to install additional Catalyst-related modules (especially plugins) +to do the things you want. As of version 5.70, Catalyst has split into +two packages, L, which includes the core elements +necessary to deploy a Catalyst application, and L, +which includes the Helpers and other things necessary or useful for +developing Catalyst applications. In a purely deployment environment +you can omit L. =over 4 @@ -35,7 +48,11 @@ C can be a quick and painless way to get Catalyst up and running on your system. Just download the script from the link above and type C. This script automates the process of installing Catalyst itself and its dependencies, with bits of overriding -so that the process does not require user interaction. +so that the process does not require user interaction. C +installs Catalyst and its dependencies using the L module, so that +modules are installed the same way you would probably install them +normally--it just makes it easier. This is a recommended solution for +installation. =item * @@ -78,7 +95,7 @@ variety of other installation techniques: CPAN -The traditional way to install Catalyst is directly from CPAN using +The traditional way to install Catalyst is directly from CPAN using the C bundle: $ perl -MCPAN -e 'install Task::Catalyst' @@ -121,15 +138,13 @@ Catalyst uses Subversion for version control. To checkout the latest: =back -B Although all of the above methods can be used to -install a base Catalyst system, only the VMWare image is -likely to have all of the plugins and modules you need to use -Catalyst properly, and to complete the tutorial. When you -start the C