Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

750 lines (542 sloc) 20.069 kb
---- config
# These are YAML settings for Vroom
title: "CPAN::Awesomeness"
height: 21
width: 82
#skip: 35
---- center
CPAN::Awesomeness - A hodgepodge of CPAN niftyness
by Jeff Lavallee
----
== What we'll cover
* CPAN setup (basic & advanced)
* CPAN::Mini
* CPAN::Reporter
* CPAN::Reporter::Smoker
----
== What is the CPAN?
* CPAN - Comprehensive Perl Archive Network
+ * a *lot* of modules
+ * 16292 modules as of 8/11/2009
+ * chances are, there's a module that can help you accomplish your task
+ * CPAN is one of the great strengths of Perl
----
== CPAN Setup
* The first time you run cpan, it will prompt for a lot of information
* Hopefully most of it is pretty self-explanitory
+ * don't worry if you're missing some of the programs it's looking for
+ * generally cpan will work fine without them (I.E. ncftpget)
+* In general, the defaults should be fine
----
== CPAN Setup - some recommendations
* auto commit config changes
- Always commit changes to config variables to disk? [no] yes
+* follow prerequisites
- Policy on building prerequisites
(follow, ask or ignore)? [ask] follow
+* install build_requires: yes (or no, but not ask!)
- Policy on installing 'build_requires' modules
(yes, no, ask/yes, ask/no)? [ask/yes] yes
+* Module::Build as prefered installer
- In case you can choose between running a Makefile.PL or a Build.PL,
which installer would you prefer (EUMM or MB or RAND)? [MB] MB
----
== Using CPAN
* command line client: cpan
* perldoc cpan
+* or man cpan
+* basic usage:
* $> cpan Foo::Bar <---- installs Foo::Bar
+* CPAN shell
+* $> cpan <---- start the CPAN.pm shell
* usually:
* cpan[1]> install Foo::Bar <---- installs Foo::Bar
* cpan[2]> i /FooBar/ <---- search for a module with
"FooBar" in its name
----
== Configuration in the CPAN shell
* cpan[1]> o conf auto_commit <---- view a setting
auto_commit [0]
Type 'o conf' to view all configuration items
+* cpan[3]> o conf auto_commit 1 <---- change a setting
auto_commit [1]
----
== Making it better
* install Bundle::CPAN
+* lots of new functionality added
+ * command history
+ * more configurable
+ * fancy colors
+* the older your perl, the happier Bundle::CPAN will make you!
----
== More configuration
* never run cpan as root again!
+ * cpan[4]> o conf make_install_make_command "sudo /usr/bin/make"
make_install_make_command [sudo /usr/bin/make]
commit: wrote '/Users/jeff/.cpan/CPAN/MyConfig.pm'
+ * cpan[5]> o conf mbuild_install_build_command "sudo ./Build"
mbuild_install_build_command [sudo ./Build]
commit: wrote '/Users/jeff/.cpan/CPAN/MyConfig.pm'
----
== CPAN configuration using you favorite text editor
* CPAN keeps configuration data in MyConfig.pm
(usually ~/.cpan/CPAN/MyConfig.pm)
+* just a big hashref:
---- perl
$CPAN::Config = {
'applypatch' => q[],
'auto_commit' => q[1],
'build_cache' => q[10],
'build_dir' => q[/Users/jeff/.cpan/build],
'build_dir_reuse' => q[1],
'build_requires_install_policy' => q[yes],
'bzip2' => q[/usr/bin/bzip2],
'cache_metadata' => q[1],
'check_sigs' => q[1],
'colorize_debug' => q[bold],
'colorize_output' => q[1],
'colorize_print' => q[white],
'colorize_warn' => q[bold],
'commandnumber_in_prompt' => q[1],
'connect_to_internet_ok' => q[0],
'cpan_home' => q[/Users/jeff/.cpan],
'curl' => q[/usr/bin/curl],
'dontload_hash' => { },
'ftp' => q[/usr/bin/ftp],
'ftp_passive' => q[1],
'ftp_proxy' => q[],
'getcwd' => q[cwd],
'gpg' => q[/usr/local/bin/gpg],
'gzip' => q[/usr/bin/gzip],
'halt_on_failure' => q[0],
'histfile' => q[/Users/jeff/.cpan/histfile],
'histsize' => q[100],
'http_proxy' => q[],
'inactivity_timeout' => q[0],
'index_expire' => q[0.001],
'inhibit_startup_message' => q[0],
'keep_source_where' => q[/Users/jeff/.cpan/sources],
'load_module_verbosity' => q[v],
'lynx' => q[/opt/local/bin/lynx],
'make' => q[/usr/bin/make],
'make_arg' => q[],
'make_install_arg' => q[],
'make_install_make_command' => q[sudo /usr/bin/make],
'makepl_arg' => q[],
'mbuild_arg' => q[],
'mbuild_install_arg' => q[],
'mbuild_install_build_command' => q[sudo ./Build],
'mbuildpl_arg' => q[],
'ncftp' => q[],
'ncftpget' => q[],
'no_proxy' => q[],
'pager' => q[/usr/bin/less],
'patch' => q[/usr/bin/patch],
'perl5lib_verbosity' => q[v],
'prefer_installer' => q[MB],
'prefs_dir' => q[/Users/jeff/.cpan/prefs],
'prerequisites_policy' => q[follow],
'scan_cache' => q[atstart],
'shell' => q[/bin/bash],
'show_unparsable_versions' => q[0],
'show_upload_date' => q[1],
'show_zero_versions' => q[0],
'tar' => q[/usr/bin/tar],
'tar_verbosity' => q[v],
'term_is_latin' => q[0],
'term_ornaments' => q[1],
'test_report' => q[1],
'trust_test_report_history' => q[0],
'unzip' => q[/usr/bin/unzip],
'urllist' => [q[http://localhost/~jeff/CPAN/], q[ftp://cpan.thepirtgroup.com/], q[ftp://cpan.cs.utah.edu/pub/CPAN/], q[ftp://cpan.mirrors.redwire.net/pub/CPAN/]],
'use_sqlite' => q[1],
'wget' => q[/opt/local/bin/wget],
'yaml_load_code' => q[0],
'yaml_module' => q[YAML::Syck],
};
1;
__END__
----
== CPAN is Great!
* I'm using CPAN all time. I love it!
+ * Except when I'm on an airplane
+ * or a boat
+ * or too cheap to pay for wifi
----
== CPAN::Mini to the rescue!
* What is CPAN::Mini?
+* creates a minimal mirror of CPAN
+* only the files needed to install the newest version
of every CPAN distribution:
+ * index files:
* 01mailrc.txt.gz
* 02packages.details.txt.gz
* 03modlist.data.gz
+ * module files:
* the last non-developer release of every dist for every author
----
== CPAN::Mini to the rescue!
* but, but... that must be huge!
+* it's not *that* big - mine is currently 1.1G
+* besides, disk space is cheap!
+* bonus: cpan installs are a lot faster
---- yaml
== CPAN::Mini setup
jeff@pokey:~ $ cat ~/.minicpanrc
local: ~/Sites/CPAN/
remote: http://cpan.hexten.net/
class: CPAN::Mini
also_mirror: indices/find-ls.gz indices/ls-lR.gz authors/00whois.xml
---- shell
== CPAN::Mini crontab
# m h dom mon dow command
20 1 * * * /usr/local/bin/minicpan
+ * or mirror development versions:
# m h dom mon dow command
20 1 * * * /usr/local/bin/minicpan -c CPAN::Mini::Devel
----
== Sweet Emailz!
From: jeff@zeroclue.com
Subject: Cron <jeff@pokey> /usr/local/bin/minicpan
Date: July 27, 2009 1:20:02 AM PDT
To: jeff@zeroclue.com
indices/find-ls.gz ... updated
authors/01mailrc.txt.gz ... updated
modules/02packages.details.txt.gz ... updated
modules/03modlist.data.gz ... up to date
indices/find-ls.gz ... updated
indices/ls-lR.gz ... updated
Scanning 02packages.details ...
CPAN: File::Which loaded ok (v0.05)
Scanning find-ls ...
authors/id/A/AG/AGRUNDMA/Audio-Scan-0.27.tar.gz ... updated
authors/id/A/AG/AGRUNDMA/CHECKSUMS ... updated
authors/id/B/BA/BAYASHI/WWW-Tube8-1.0.1.tar.gz ... updated
authors/id/B/BA/BAYASHI/CHECKSUMS ... updated
---- diff,i-1
.== Teach cpan about CPAN::Mini
.
.Our mirror won't do us much good unless we use it:
.
.--- /Users/jeff/.cpan/CPAN/MyConfig.pm.a 2009-08-11 21:40:04.000000000 -0700
.+++ /Users/jeff/.cpan/CPAN/MyConfig.pm 2009-01-14 19:33:26.000000000 -0800
.@@ -62,3 +62,3 @@
. 'unzip' => q[/usr/bin/unzip],
.- 'urllist' => [q[ftp://cpan.thepirtgroup.com/]],
.+ 'urllist' => [q[http://localhost/~jeff/CPAN/], q[ftp://cpan.thepirtgroup.com/]],
. 'use_sqlite' => q[1],
---- center
Sweet! What's next?
----
== Give something back
* Spend 10 minutes and give something back
to CPAN every time you install a module
+* How?
+* setup CPAN::Reporter
+* send CPAN Test reports every time you install a module!
+* see http://cpantesters.org/
----
== CPAN::Reporter setup
Enable sending test reports:
cpan[1]> o conf init test_report
<snip>
<test_report>
Email test reports if CPAN::Reporter is installed (yes/no)? [yes]
CPAN: CPAN::Reporter loaded ok (v1.1708)
Proceeding to configure CPAN::Reporter.
<snip>
commit: wrote '/Users/jeff/.cpan/CPAN/MyConfig.pm'
---- yaml
== CPAN::Reporter config.ini
jeff@pokey:~ $ cat ~/.cpanreporter/config.ini
cc_author=no
edit_report=default:ask/no pass/na:no
email_from=jeff@zeroclue.com
send_report=default:ask/yes pass/na:yes
smtp_server=smtp.gmail.com
transport=Net::SMTP::TLS User jeff@zeroclue.com Password xxxxxxxxx Port 587
----
== CPAN::Reporter setup - detail
* cc_author=no
* Don't cc authors - some are annoyed by direct emails
+* edit_report=default:ask/no pass/na:no
* if the results are pass or N/A, don't ask to edit
otherwise (failure), ask and default to "no edit"
+* email_from=jeff@zeroclue.com
+* send_report=default:ask/yes pass/na:yes
* if the results are pass or N/A, don't ask - just send
otherwise, ask and default to "yes (send)"
----
== CPAN::Reporter setup - detail
* smtp_server=smtp.gmail.com
+* transport=Net::SMTP::TLS User jeff@zeroclue.com \
Password xxxxxxxxx Port 587
* use Net::SMTP::TLS, because google's SMTP servers
require authentication
specify my username, password, and the port to use
----
== CPAN::Reporter setup
* see also: perldoc CPAN::Reporter::Config
+ * lots of help for setting up CPAN::Reporter
+ * useful to run w/o sending reports:
transport=File ~/saved-reports-dir
----
== CPAN::Reporter in action!
cpan[1]> install Acme::Bleach
CPAN: CPAN::SQLite loaded ok (v0.197)
...
Running make for D/DC/DCONWAY/Acme-Bleach-1.12.tar.gz
CPAN: LWP::UserAgent loaded ok (v5.826)
Fetching with LWP:
http://localhost/~jeff/CPAN/authors/id/D/DC/DCONWAY/Acme-Bleach-1.12.tar.gz
CPAN: Digest::SHA loaded ok (v5.45)
...
CPAN.pm: Going to build D/DC/DCONWAY/Acme-Bleach-1.12.tar.gz
CPAN: CPAN::Reporter loaded ok (v1.1705)
Checking if your kit is complete...
Looks good
...
----
== CPAN::Reporter in action!
...
Writing Makefile for Acme::Bleach
(/usr/local/bin/perl Makefile.PL exited with 0)
CPAN::Reporter: Makefile.PL result is 'pass', No errors.
cp lib/Acme/Bleach.pm blib/lib/Acme/Bleach.pm
cp lib/Acme/Morse.pm blib/lib/Acme/Morse.pm
cp lib/Acme/DWIM.pm blib/lib/Acme/DWIM.pm
Manifying blib/man3/Acme::Morse.3
Manifying blib/man3/Acme::Bleach.3
Manifying blib/man3/Acme::DWIM.3
(/usr/bin/make exited with 0)
CPAN::Reporter: make result is 'pass', No errors.
DCONWAY/Acme-Bleach-1.12.tar.gz
/usr/bin/make -- OK
Running make test
PERL_DL_NONLAZY=1 /usr/local/bin/perl "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/bleach....ok
t/DWIM......ok
t/morse.....ok
All tests successful.
...
----
== CPAN::Reporter in action!
...
Files=3, Tests=30, 0 wallclock secs ( 0.03 usr 0.01 sys + 0.02 cusr 0.01 csys = 0.07 CPU)
Result: PASS
(/usr/bin/make test exited with 0)
CPAN::Reporter: Test result is 'pass', All tests successful.
CPAN::Reporter: preparing a CPAN Testers report for Acme-Bleach-1.12
CPAN::Reporter: sending test report with 'pass' to cpan-testers@perl.org
DCONWAY/Acme-Bleach-1.12.tar.gz
/usr/bin/make test -- OK
Running make install
Prepending /Users/jeff/.cpan/build/Acme-Bleach-1.12-ogVZun/blib/arch /Users/jeff/.cpan/build/Acme-Bleach-1.12-ogVZun/blib/lib to PERL5LIB for 'install'
Installing /usr/local/lib/perl5/site_perl/5.10.0/Acme/Bleach.pm
Installing /usr/local/lib/perl5/site_perl/5.10.0/Acme/DWIM.pm
Installing /usr/local/lib/perl5/site_perl/5.10.0/Acme/Morse.pm
Installing /usr/local/share/man/man3/Acme::Bleach.3
Installing /usr/local/share/man/man3/Acme::DWIM.3
Installing /usr/local/share/man/man3/Acme::Morse.3
Appending installation info to /usr/local/lib/perl5/5.10.0/darwin-2level/perllocal.pod
DCONWAY/Acme-Bleach-1.12.tar.gz
sudo /usr/bin/make install -- OK
cpan[2]>
----
== CPAN::Reporter in action!
cpan[1]> install DBD::Sybase
CPAN: CPAN::SQLite loaded ok (v0.198)
CPAN: LWP::UserAgent loaded ok (v5.829)
CPAN: Time::HiRes loaded ok (v1.9719)
Fetching with LWP:
http://localhost/~jeff/CPAN/authors/01mailrc.txt.gz
CPAN: YAML loaded ok (v0.70)
Fetching with LWP:
http://localhost/~jeff/CPAN/modules/02packages.details.txt.gz
Fetching with LWP:
http://localhost/~jeff/CPAN/modules/03modlist.data.gz
Database was generated on Wed, 14 Oct 2009 05:10:48 GMT
Updating database file ...
...
----
== CPAN::Reporter in action!
Gathering information from index files ...
Obtaining current state of database ...
Populating database tables ...
Done!
Running install for module 'DBD::Sybase'
CPAN: CPAN::Kwalify loaded ok (v5.50)
Running make for M/ME/MEWP/DBD-Sybase-1.09.tar.gz
CPAN: Digest::SHA loaded ok (v5.47)
CPAN: Module::Signature loaded ok (v0.55)
WARNING: This key is not certified with a trusted signature!
Primary key fingerprint: 2E66 557A B97C 19C7 91AF 8E20 328D A867 450F 89EC
Signature for /Users/jeff/.cpan/sources/authors/id/M/ME/MEWP/CHECKSUMS ok
Checksum for /Users/jeff/.cpan/sources/authors/id/M/ME/MEWP/DBD-Sybase-1.09.tar.gz ok
Scanning cache /Users/jeff/.cpan/build for sizes
DONE
CPAN: Archive::Tar loaded ok (v1.54)
DBD-Sybase-1.09/
...
----
== CPAN::Reporter in action!
DBD-Sybase-1.09/Sybase.xs
DBD-Sybase-1.09/t/nsql.t
CPAN: File::Temp loaded ok (v0.22)
Package came without SIGNATURE
CPAN.pm: Going to build M/ME/MEWP/DBD-Sybase-1.09.tar.gz
CPAN: CPAN::Reporter loaded ok (v1.1708)
Please set SYBASE in CONFIG, or set the $SYBASE environment variable at Makefile.PL line 103, <IN> line 44.
(/usr/local/bin/perl Makefile.PL exited with 512)
CPAN::Reporter: Makefile.PL result is 'unknown', Stopped with an error.
CPAN::Reporter: preparing a CPAN Testers report for DBD-Sybase-1.09
Do you want to review or edit the test report? (yes/no) [no]
Do you want to send the report? (yes/no) [yes] no
CPAN::Reporter: test report will not be sent
Warning: No success on command[/usr/local/bin/perl Makefile.PL]
MEWP/DBD-Sybase-1.09.tar.gz
/usr/local/bin/perl Makefile.PL -- NOT OK
Running make test
Make had some problems, won't test
Running make install
Make had some problems, won't install
Failed during this command:
MEWP/DBD-Sybase-1.09.tar.gz : writemakefile NO '/usr/local/bin/perl Makefile.PL' returned status 512
cpan[2]>
----
== Awesome!
* we can install CPAN modules w/o running cpan as root
+* we're able to install CPAN modules from our local mirror
+* we're sending test reports every time we install a CPAN module
+* What's next?
+* CPAN::Reporter::Smoker!
----
== CPAN::Reporter::Smoker
* Turnkey CPAN Testers smoking
+ * No configuration needed
+ * Tests each distribution as a separate CPAN process
- each distribution has prerequisites satisfied from scratch
+ * Automatically checks for new distributions every twelve hours
(configurable)
+ * Continues until interrupted with CTRL-C
+ * Smoke tested modules are NOT installed
----
== CPAN::Reporter::Smoker warning!
WARNING -- smoke testing is risky
Smoke testing will download and run programs that other people have
uploaded to CPAN. These programs could do anything to your system,
including deleting everything on it. Do not run CPAN::Reporter::Smoker
unless you are prepared to take these risks.
----
== CPAN::Reporter::Smoker setup
* none!
+* that's a fib - CPAN::Reporter::Smoker doesn't require much setup,
but there are some things I'd recommend
+ * minimum step: run as a dedicated user
+ * I usually create a user called "smoke" that's not in wheel
or any other privileged group
+ * I usually use a dedicated perl install for testing, I.E.
/usr/local/perl_5_8_9/
----
== CPAN::Reporter::Smoker
* still scared?
+ * Checkout CPAN::Reporter::Smoker::Safer
+ * like CPAN::Reporter::Smoker, but limits the set of distributions
tested to those that are already installed on the system
----
== CPAN::Reporter::Smoker tips
* Use a CPAN::Mini mirror
* You'll reduce load on CPAN mirrors
+* You'll need to mirror the CPAN indicies for the smoker
* see CPAN::Mini ~/.minicpanrc from earlier
* use CPAN.pm "distroprefs" to prevent testing things that
hang your smoker or you know are broken
+* David Golden's set of distroprefs is a great start:
http://echo.dagolden.com/git/?p=distroprefs.git;a=summary
----
== distroprefs?
* CPAN Distroprefs let you give special treatment to particlar modules
+* examples:
+ * set environment variables (during build/test/install)
+ * override CPAN.pm configuration values
+ * specify dependencies the module author missed
+ * in our case, we generally want to prevent smoke testing altogether
+ * example from ~/.cpan/prefs/t_hangs.yml:
---- yaml
---
comment: |
Things that hang in tests
disabled: 1
match:
distribution: |
/(?x:
.^ # never matches, only purpose is to let things align nicely
|Acme-Tests
|ApacheBench
|App-Control
|App-PPBuild # hangs prompting to rm stuff
|Attribute-Persistent # deep recursion
|Authen-CyrusSAS
# ...
|XiaoI
|only # deep recursion
|sitemapper
)-v?\d|
----
== CPAN::Reporter::Smoker tips
+ * use screen to let your smoker run un-attended and un-interuppted
+ * start with $> screen -S smoker
+ * detach with ^a^d
+ * reattach with screen -d -x smoker
----
== Starting your smoker:
jeff@pokey:~ $ screen -S smoker
jeff@pokey:~ $ sudo su - smoke
pokey:~ smoke$ /usr/local/perl_5_8_9/bin/perl -MCPAN::Reporter::Smoker -e start
Starting CPAN::Reporter::SmokerCPAN: Term::ANSIColor loaded ok (v1.12)
CPAN: CPAN::SQLite loaded ok (v0.197)
CPAN: YAML loaded ok (v0.66)
Going to read 126 yaml files from /Users/smoke/.cpan/build/
CPAN: Time::HiRes loaded ok (v1.9711)
............................................................................DONE
Restored the state of 108 (in 1.7040 secs)Database was generated on Wed, 12 Aug 2009 06:56:44 GMT
Smoker: getting modules/02packages.details.txt.gz from CPANCPAN: LWP::UserAgent loaded ok (v5.826)
Fetching with LWP: http://localhost/~jeff/CPAN/modules/02packages.details.txt.gz
Smoker: getting indices/find-ls.gz from CPAN
Fetching with LWP: http://localhost/~jeff/CPAN/indices/find-ls.gz
Smoker: scanning and sorting index
Smoker: found 18954 distributions on CPAN
Scanning cache /Users/smoke/.cpan/build for sizes
............................................................................DONE
Smoker: testing Email-Stuff-2.100 [1/18954] at Wed Aug 12 00:01:48 2009
CPAN: Term::ANSIColor loaded ok (v1.12)
CPAN: File::HomeDir loaded ok (v0.69)
CPAN: CPAN::SQLite loaded ok (v0.197)
CPAN: YAML loaded ok (v0.66)
Going to read 126 yaml files from /Users/smoke/.cpan/build/
CPAN: Time::HiRes loaded ok (v1.9711)
............................................................................DONE
Restored the state of 108 (in 1.7507 secs)
Database was generated on Wed, 12 Aug 2009 06:56:44 GMT
CPAN: CPAN::Kwalify loaded ok (v5.50)
Running make for R/RJ/RJBS/Email-Stuff-2.100.tar.gz
CPAN.pm: Going to build R/RJ/RJBS/Email-Stuff-2.100.tar.gz
----
== Thanks
* Ingy for Vroom::Vroom, what I used to create this slideshow
* Ricardo SIGNES for CPAN::Mini
* David Golden for CPAN::Reporter::Smoker and CPAN::Mini::Devel
* David Westbrook for CPAN::Reporter::Smoker::Safer
* Eric Wilhelm, gracious host of PDX.pm and prolific CPAN author
* all the other CPAN authors whose work these modules depend on
---- center
Questions?
----
== Resources
* http://cpan.org/
* http://search.cpan.org/dist/CPAN-Mini/
* http://search.cpan.org/dist/CPAN-Reporter/
* http://search.cpan.org/dist/CPAN-Reporter-Smoker/
* http://cpantesters.org/
* http://github.com/rjbs/cpan-mini/
* http://echo.dagolden.com/git/?p=distroprefs.git;a=summary
Jump to Line
Something went wrong with that request. Please try again.