[Catalyst-commits] r7192 - trunk/examples/CatalystAdvent/root/2007/pen

Sun Dec 2 00:42:20 GMT 2007

Author: jgoulah
Date: 2007-12-02 00:42:20 +0000 (Sun, 02 Dec 2007)
New Revision: 7192

Modified:
   trunk/examples/CatalystAdvent/root/2007/pen/12.pod
Log:
first draft of local::lib article for day 12

Modified: trunk/examples/CatalystAdvent/root/2007/pen/12.pod
===================================================================

--- trunk/examples/CatalystAdvent/root/2007/pen/12.pod	2007-12-01 22:38:44 UTC (rev 7191)
+++ trunk/examples/CatalystAdvent/root/2007/pen/12.pod	2007-12-02 00:42:20 UTC (rev 7192)
@@ -1,5 +1,148 @@
+
 =head1 local::lib and Catalyst
 
+Today we'll have a glance at how to run the Catalyst server under local::lib
+for development use and also how to use local::lib as a build environment for 
+putting your application into production.
+
+=head2 About local::lib 
+
+L<local::lib> provides an easy way to localize a perl module library to a 
+particular users environment.  It can be advantageous on shared hosts for full 
+control over non-root installations and a powerful tool for building and 
+deploying Catalyst applications.
+
+=head2 Prerequisites
+
+The prerequisites require a toolchain (make, C compiler, etc) and an outbound 
+connection (to connect with CPAN).
+
+=head2 Getting Started
+
+This article follows the bootstrap instructions for installing local::lib. 
+
+=head3 Setup CPAN 
+
+If your user does not have a ~/.cpan directory, then run this command, accept 
+the defaults and quit when its done setup
+
+ % perl -MCPAN -eshell 
+ % cpan> exit 
+
+=head3 Download
+
+The first step is to download local::lib from CPAN. As of this writing, the 
+current version is 1.001000 so we'll grab that
+
+  % wget http://search.cpan.org/CPAN/authors/id/A/AP/APEIRON/local-lib-1.001000.tar.gz
+
+and unpack it
+
+ % tar xvzf local-lib-1.001000.tar.gz
+
+=head2 Installation
+
+If any of the following steps hang for any reason, you may need to go into the 
+build directory (~/.cpan/build/CPAN-1.92) and run make install, but the typical
+process is simply
+
+ % cd ~/local-lib-1.001000
+ % perl Makefile.PL --bootstrap
+ % make test
+ % make install
+ % eval `perl -I$HOME/perl5/lib/perl5 -Mlocal::lib` >> ~/.bashrc
+ % source .bashrc
+
+=head3 Verifying the Installation 
+
+You can now check that MODULEBUILDRC, PERL5LIB, PERL_MM_OPT and PATH all 
+mention your new setup under ~/perl5 using the 'set' command. Then install a 
+few basic modules for faster downloading, checksum checking, and stopping 
+persistant state warnings, respectively
+
+ % perl -MCPAN -e 'install(LWP)'
+ % perl -MCPAN -e 'install Digest::SHA'
+ % perl -MCPAN -e 'install(YAML)'
+
+=head2 Getting Catalyst Running
+
+There is really nothing new to getting a basic Catalyst application working at
+this point, except to understand that you are now using the modules under 
+~/perl5 so you can install anything you please. There are several suggestions 
+L<here|Catalyst::Manual::Installation> for getting Catalyst installed.  For 
+development all you need is to install L<Catalyst::Devel> like so 
+
+ % perl -MCPAN -e 'install Catalyst::Devel'
+
+Then you can create an app and fire it up 
+
+ % catalyst.pl MyApp
+ % cd MyApp
+ % script/myapp_server.pl
+
+=head2 Additional Benefits of local::lib
+
+=head3 Using Makefile.PL to Install Your App Dependencies
+
+If you start with an empty site_perl (only core modules) and a fresh local::lib
+installation, you can actually build your application, test it works, and use 
+the modules in the deployment of your app (Note: a fresh perl installation  
+requires root).  This also requires that you have been adding the application 
+dependencies to your Makefile.PL. For example, you would probably have a 
+dependency that looks like this, along with the other modules the app is using
+
+ requires 'Catalyst' => '5.7010';
+
+Once you've added all of your dependencies, you can install them 
+
+ % cd My-Module-branch
+ % perl Makefile.PL && make installdeps 
+
+Assuming you have a fresh perl and local::lib installation, the dependency list
+will show each module as 'missing' which makes it build all of the 
+dependencies into your ~/perl5/lib/perl5 directory. For testing, just verify 
+your application starts up. You can then take this set of modules and deploy it
+with your application on another box, knowing that set of modules works with
+that version of the application being deployed. 
+
+This is also useful in an environment with multiple developers.
+If a dependency is added, it has to go into Makefile.PL. Making sure modules
+are only installed with 'make installdeps' verifies that when the code is 
+committed that uses a new module, other developers can easily install it into 
+their local::lib (with 'perl Makefile.PL && make installdeps'), and thus 
+becomes a new dependecy in the build process.
+
+=head3 Testing Module Code In Your Environment 
+
+One more useful thing about local::lib is that you can use it to test patches 
+to code that you are working on.  For example, if you've made a patch or just 
+want to test out a branch of code, you can install it to your local::lib in the
+typical way
+
+ % perl Makefile.PL && make install
+
+Then later if you want to rollback to the current version of the module fire up 
+cpan and drop into the shell of the current module
+
+ % cpan
+ cpan> look My::Module
+
+You should now be in a shell in which you can install the module in the usual 
+way to overwrite your version 
+
+ Working directory is /home/user/.cpan/build/My-Module-0.00000-NvZbRI
+ % perl Makefile.PL && make install 
+
+=head2 Summary
+
+We have seen where you can use local::lib as a development environment
+and touched on how you can use it to build modules for deploying on other 
+hosts. It can be handy for control over your modules on shared hosts and in a 
+multi-developer setting as well as an easy way to work on external code.  
+
 =head1 AUTHOR
 
-John Goulah
+John Goulah, E<lt>jgoulah at gmail.comE<gt>
+
+=cut
+


