CPAN+changelog.pl SAMPLE USAGE ============================== Date: 2006/03/04 To give you an impression of how to work with the script, we take a short tour from a fresh install of Perl 5.8.8 to an installation ready for spam-scanning with amavisd-new and SpamAssassin. The machine is called shlab, it runs SuSE9.1 which ships with Perl 5.8.3. For some reason we want to use Perl 5.8.8, but we do not want to interfere with SuSE's original Perl installation. SuSE (as of 9.2) does not use /usr/local for Perl, so the new Perl goes there. Other Linux distributions will use /usr/local for their Perl (e.g. Debian), our choice of installation path might lead to problems under those distros. Screen output is prefixed with '|'. Some lines that are not of interest are skipped, this is indicated with a '| ...' line. 'Calling ""' is used as a shorthand for invoking 'CPAN+changelog.pl '. Assume we just installed Perl 5.8.8 under /usr/local: | shlab:~ # /usr/local/bin/perl -v | | This is perl, v5.8.8 built for i686-linux | | Copyright 1987-2006, Larry Wall | ... now we configure the CPAN module. We will use /root/.cpanlocal, since /root/.cpan is already taken by SuSE's original Perl installation. Don't mix CPAN directories, or you will regret it. Don't ask, I know for sure :-) | shlab:~ # /usr/local/bin/perl -MCPAN -e shell | We have to reconfigure CPAN.pm due to following uninitialized parameters: | | cpan_home, keep_source_where, build_dir, build_cache, scan_cache, index_expire, gzip, tar, unzip, make, pager, makepl_arg, make_arg, make_install_arg, urllist, inhibit_startup_message, ftp_proxy, http_proxy, no_proxy, prerequisites_policy, cache_metadata | | /usr/local/lib/perl5/5.8.8/CPAN/Config.pm initialized. | | | CPAN is the world-wide archive of perl resources. It consists of about | 100 sites that all replicate the same contents all around the globe. | ... Further assume that we have edited /usr/local/bin/CPAN+changelog.pl so that its first line (the interpreter line) reads: #!/usr/local/bin/perl and invoking the script calls up our local Perl 5.8.8 At the moment of writing, the script was at version 1.28: | shlab:~ # /usr/local/bin/CPAN+changelog.pl -version | This is CPAN+changelog.pl version 1.28 | shlab:~ # Note that we do not call "-init" right now, because our modules are not yet uptodate with CPAN. First we install Bundle::LWP and Bundle::CPAN. The CPAN modules sometimes exhibits strange behaviour if LWP is not available. | shlab:~ # /usr/local/bin/CPAN+changelog.pl -install Bundle::LWP | # Support EDRI! They defend your civil digital rights. | # see http://www.edri.org/edrigram why this is necessary. | #----------------------------------------------------------------------- | # Finding version numbers for installed modules... | CPAN: Storable loaded ok | LWP not available | LWP not available | | Trying with "/usr/bin/lynx -source" to get | http://www.planet-elektronik.de/CPAN/authors/01mailrc.txt.gz | ... | Wrote bundle file | /root/.cpanlocal/Bundle/Snapshot_2006_03_04_00.pm | | # BuildLog will be saved as /root/.cpanlocal/BuildLogs/BuildLog-20060304-153121-LaxvHA.gz | shlab:~ # /usr/local/bin/CPAN+changelog.pl -install Bundle::CPAN | # Support EDRI! They defend your civil digital rights. | # see http://www.edri.org/edrigram why this is necessary. | #----------------------------------------------------------------------- | # Finding version numbers for installed modules... | CPAN: Storable loaded ok | Going to read /root/.cpanlocal/Metadata | Database was generated on Sat, 04 Mar 2006 11:16:44 GMT | # Installing: Bundle::CPAN | #----------------------------------------------------------------------- | # Calling CPAN::Shell->install(Bundle::CPAN) | CPAN: LWP::UserAgent loaded ok | Fetching with LWP: | http://www.planet-elektronik.de/CPAN/authors/id/A/AN/ANDK/Bundle-CPAN-1.85.tar.gz | ... | Wrote bundle file | /root/.cpanlocal/Bundle/Snapshot_2006_03_04_01.pm | ... | # WARN: CPAN have changed. CPAN might require reconfiguration. | # BuildLog will be saved as /root/.cpanlocal/BuildLogs/BuildLog-20060304-153620-4xO9In.gz and because the updated CPAN.pm has some new configuration options, we call vanilla CPAN again to finish CPAN configuration: | shlab:~ # /usr/local/bin/perl -MCPAN -e shell | Sorry, we have to rerun the configuration dialog for CPAN.pm due to | the following indispensable but missing parameters: | | mbuild_arg, mbuild_install_arg, mbuild_install_build_command, mbuildpl_arg | | /usr/local/lib/perl5/5.8.8/CPAN/Config.pm initialized. | ... | Are you ready for manual configuration? [yes] | ... Note that we configured CPANs policy for dependencies to "Follow" to ensure all required modules will be installed without having to answer any questions. We check what's new on CPAN: | shlab:~ # /usr/local/bin/CPAN+changelog.pl -r | less | ... | #----------------------------------------------------------------------- | # Upgradeables: CGI,Devel::PPPort,Encode,Locale::Maketext,Pod::Man,Test::Builder::Module,Text::Soundex,Time::HiRes,Time::Local,threads::shared | # CGI current:3.15 cpan:3.17 | # Devel::PPPort current:3.06_01 cpan:3.08 | # Encode current:2.12 cpan:2.14 | # Locale::Maketext current:1.09 cpan:1.10 | # Pod::Man current:1.37 cpan:2.09 | # Test::Builder::Module current:0.02 cpan:0.03 | # Text::Soundex current:1.01 cpan:3.02 | # Time::HiRes current:1.86 cpan:1.87 | # Time::Local current:1.11 cpan:1.12 | # threads::shared current:0.94 cpan:0.96 | lines 2925-2951/2951 (END) that's 10 modules to be updated and some 2000 lines of ChangeLog. Since our Perl installation is not yet in production use we do not read them (big time saver:). We just upgrade them all and head for a cup of coffee, erm, other work, while the update runs: | shlab:~ # /usr/local/bin/CPAN+changelog.pl -install CGI,Devel::PPPort,Encode,Locale::Maketext,Pod::Man,Test::Builder::Module,Text::Soundex,Time::HiRes,Time::Local,threads::shared | ... | Wrote bundle file | /root/.cpanlocal/Bundle/Snapshot_2006_03_04_02.pm | | # Autobundle changes: | 1c1 | < package Bundle::Snapshot_2006_03_04_01; | --- | > package Bundle::Snapshot_2006_03_04_02; | 11c11 | < Bundle::Snapshot_2006_03_04_01 - Snapshot of installation on shlab on Sat Mar 4 15:40:38 2006 | --- | > Bundle::Snapshot_2006_03_04_02 - Snapshot of installation on shlab on Sat Mar 4 15:53:32 2006 | 15c15 | < perl -MCPAN -e 'install Bundle::Snapshot_2006_03_04_01' | --- | > perl -MCPAN -e 'install Bundle::Snapshot_2006_03_04_02' | 79c79 | < CGI 3.15 | --- | > CGI 3.17 | ... | 1049c1105 | < threads::shared 0.94 | --- | > threads::shared 0.96 | # BuildLog will be saved as /root/.cpanlocal/BuildLogs/BuildLog-20060304-154829-HrPay4.gz The install automatically created a Snapshot. We are shown the diff between this and the last Snapshot and the name of the BuildLog where we can look for errors or warnings. Now that all our modules are uptodate we call "-init", which brings the ChangeLog database at /root/.cpanlocal/ChangeLogs up to date: | shlab:~ # /usr/local/bin/CPAN+changelog.pl -init | ... | # updated /root/.cpanlocal/ChangeLogs/URI/Changes with /root/.cpanlocal/build/URI-1.35/Changes | # updated /root/.cpanlocal/ChangeLogs/Unicode-Collate/Changes with /root/.cpanlocal/build/Unicode-Collate-0.52/Changes | # updated /root/.cpanlocal/ChangeLogs/Unicode-Normalize/Changes with /root/.cpanlocal/build/Unicode-Normalize-0.32/Changes | # updated /root/.cpanlocal/ChangeLogs/XSLoader/Changes with /root/.cpanlocal/build/XSLoader-0.06/Changes | # updated /root/.cpanlocal/ChangeLogs/base/Changes with /root/.cpanlocal/build/base-2.03/Changes | # updated /root/.cpanlocal/ChangeLogs/if/Changes with /root/.cpanlocal/build/if-0.0401/Changes | # updated /root/.cpanlocal/ChangeLogs/threads-shared/Changes with /root/.cpanlocal/build/threads-shared-0.96/Changes Then, just for the sake of showing that it is possible, we downgrade the Time::HiRes module. Nicely, this modules distribution file carries the modules name and shares the version number (for an example of not-so-obvious naming, have a look at the libwww-perl distribution). | shlab:~ # /usr/local/bin/CPAN+changelog.pl -install J/JH/JHI/Time-HiRes-1.85.tar.gz | ... | Wrote bundle file | /root/.cpanlocal/Bundle/Snapshot_2006_03_04_03.pm | | # Autobundle changes: | 1c1 | < package Bundle::Snapshot_2006_03_04_02; | --- | > package Bundle::Snapshot_2006_03_04_03; | 11c11 | < Bundle::Snapshot_2006_03_04_02 - Snapshot of installation on shlab on Sat Mar 4 15:53:32 2006 | --- | > Bundle::Snapshot_2006_03_04_03 - Snapshot of installation on shlab on Sat Mar 4 15:57:19 2006 | 15c15 | < perl -MCPAN -e 'install Bundle::Snapshot_2006_03_04_02' | --- | > perl -MCPAN -e 'install Bundle::Snapshot_2006_03_04_03' | 897c897 | < Time::HiRes 1.87 | --- | > Time::HiRes 1.85 | # BuildLog will be saved as /root/.cpanlocal/BuildLogs/BuildLog-20060304-155535-W9Cluu.gz Time::HiRes is not up-to-date anymore. Let's take a look at what we would gain by (re-)installing the newest latest Time::HiRes | shlab:~ # /usr/local/bin/CPAN+changelog.pl -r | # Support EDRI! They defend your civil digital rights. | # see http://www.edri.org/edrigram why this is necessary. | #----------------------------------------------------------------------- | CPAN: Storable loaded ok | Going to read /root/.cpanlocal/Metadata | Database was generated on Sat, 04 Mar 2006 11:16:44 GMT | Running get for module Time::HiRes | CPAN: Digest::SHA loaded ok | CPAN: Module::Signature loaded ok | 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 /root/.cpanlocal/sources/authors/id/J/JH/JHI/CHECKSUMS ok | CPAN: Compress::Zlib loaded ok | Checksum for /root/.cpanlocal/sources/authors/id/J/JH/JHI/Time-HiRes-1.87.tar.gz ok | Scanning cache /root/.cpanlocal/build for sizes | Time-HiRes-1.87/ | Time-HiRes-1.87/Changes | Time-HiRes-1.87/fallback/ | Time-HiRes-1.87/fallback/const-c.inc | Time-HiRes-1.87/fallback/const-xs.inc | Time-HiRes-1.87/hints/ | Time-HiRes-1.87/hints/dec_osf.pl | Time-HiRes-1.87/hints/dynixptx.pl | Time-HiRes-1.87/hints/irix.pl | Time-HiRes-1.87/hints/sco.pl | Time-HiRes-1.87/hints/solaris.pl | Time-HiRes-1.87/hints/svr4.pl | Time-HiRes-1.87/HiRes.pm | Time-HiRes-1.87/HiRes.xs | Time-HiRes-1.87/Makefile.PL | Time-HiRes-1.87/MANIFEST | Time-HiRes-1.87/META.yml | Time-HiRes-1.87/ppport.h | Time-HiRes-1.87/README | Time-HiRes-1.87/t/ | Time-HiRes-1.87/t/HiRes.t | Time-HiRes-1.87/TODO | Time-HiRes-1.87/typemap | Removing previously used /root/.cpanlocal/build/Time-HiRes-1.87 | Package came without SIGNATURE | | #----------------------------------------------------------------------- | # Upgradeables: Time::HiRes | # Time::HiRes current:1.85 cpan:1.87 | #----------------------------------------------------------------------- | # Time::HiRes current:1.85 cpan:1.87 | # Time::HiRes J/JH/JHI/Time-HiRes-1.87.tar.gz /root/.cpanlocal/ChangeLogs/Time-HiRes/Changes /root/.cpanlocal/build/Time-HiRes-1.87/Changes | 2a3,14 | > 1.87 [2006-02-13] | > - [rt.cpan.org #17442] 'make test' frequently fails under | > Cygwin Perl v5.8.8, reported and patched by J. R. Hedden | > (two race condition bugs in the END block in the case the | > main process dies before the timer process, unearthed | > by a bug in Cygwin ualarm) | > | > 1.86 [2005-12-17] | > - HiRes.t:s/ok 32/ok 33/, from Dominic Dunlop | > - tighten up the clock() test marginally by requiring non-negative | > - clock_nanosleep() and clock() doc tweaks | > | #----------------------------------------------------------------------- | # Upgradeables: Time::HiRes | # Time::HiRes current:1.85 cpan:1.87 Looks like we don't need to rush into an upgrade of the Time::HiRes module. If we were to produce a "-r" report on a daily basis, we might get annoyed by the CPAN background noise distracting from the real information. The script tries to be nice and suppresses this output if it does not run on a tty, e.g. if called from cron. Here we simulate this using a pipe for stdin: | shlab:~ # echo | /usr/local/bin/CPAN+changelog.pl -r | WARNING: This key is not certified with a trusted signature! | Primary key fingerprint: 2E66 557A B97C 19C7 91AF 8E20 328D A867 450F 89EC | #----------------------------------------------------------------------- | # Upgradeables: Time::HiRes | # Time::HiRes current:1.85 cpan:1.87 | #----------------------------------------------------------------------- | # Time::HiRes current:1.85 cpan:1.87 | # Time::HiRes J/JH/JHI/Time-HiRes-1.87.tar.gz /root/.cpanlocal/ChangeLogs/Time-HiRes/Changes /root/.cpanlocal/build/Time-HiRes-1.87/Changes | 2a3,14 | > 1.87 [2006-02-13] | > - [rt.cpan.org #17442] 'make test' frequently fails under | > Cygwin Perl v5.8.8, reported and patched by J. R. Hedden | > (two race condition bugs in the END block in the case the | > main process dies before the timer process, unearthed | > by a bug in Cygwin ualarm) | > | > 1.86 [2005-12-17] | > - HiRes.t:s/ok 32/ok 33/, from Dominic Dunlop | > - tighten up the clock() test marginally by requiring non-negative | > - clock_nanosleep() and clock() doc tweaks | > | #----------------------------------------------------------------------- | # Upgradeables: Time::HiRes | # Time::HiRes current:1.85 cpan:1.87 | shlab:~ # Now this looks suitable for a regular mail report. We want our Perl installation to support full-fledged spam scanning for amavisd-new with SpamAssassin. We happen to have a Snapshot from an active amavisd-new system. We are lazy and do not want to answer so many questions, so we start the install from inside of an at job, and any questions a modules install wants to ask us will have to use their default answer: | shlab:~ # cp Snapshot_2005_12_20_03.pm /root/.cpanlocal/Bundle/ | shlab:~ # echo /usr/local/bin/CPAN+changelog.pl -install Bundle::Snapshot_2005_12_20_03 | at +1min | warning: commands will be executed using /bin/sh | job 34 at 2006-03-04 15:59 | shlab:~ # Half an hour later, coming back from a coffee break aka tech meeting we check the BuildLog for errors: | shlab:~ # zcat /root/.cpanlocal/BuildLogs/BuildLog-20060304-155900-qUyRqz | less | ... Seems it went ok. Let's see if everything is uptodate: | shlab:~ # /usr/local/bin/CPAN+changelog.pl -r | ... | #----------------------------------------------------------------------- | # Upgradeables: DBD::File | # DBD::File current:0.33 cpan:0.34 | #----------------------------------------------------------------------- | # DBD::File current:0.33 cpan:0.34 | # DBD::File J/JZ/JZUCKER/DBD-File-0.34.tar.gz /root/.cpanlocal/ChangeLogs/DBD-File/Changes /root/.cpanlocal/build/DBD-File-0.34/Changes | # WARN: no changes found in Changes | #----------------------------------------------------------------------- | # Upgradeables: DBD::File | # DBD::File current:0.33 cpan:0.34 | shlab:~ # DBD::File was installed successfully, but Perl still uses the old version. And because it is already installed, the ChangeLog database contains the "Changes" file from 0.34, which is why we see the WARN: line that tells us that the "Changes" file has not changed :-) The new version of DBD::File is installed at a different location with a lower precedence: | shlab:~ # find /usr/local -name File.pm | xargs grep -H "^\$VERSION =" | grep DBD | /usr/local/lib/perl5/site_perl/5.8.8/DBD/File.pm:$VERSION = '0.34'; | /usr/local/lib/perl5/site_perl/5.8.8/i686-linux/DBD/File.pm:$VERSION = '0.33'; The i686-linux directory takes precedence, so Perl does not see our new version, although it installed successfully. We need to manually remove the old version. | shlab:~ # rm /usr/local/lib/perl5/site_perl/5.8.8/i686-linux/DBD/File.pm A final test: | shlab:~ # /usr/local/bin/CPAN+changelog.pl -r | # Support EDRI! They defend your civil digital rights. | # see http://www.edri.org/edrigram why this is necessary. | #----------------------------------------------------------------------- | CPAN: Storable loaded ok | Going to read /root/.cpanlocal/Metadata | Database was generated on Sat, 04 Mar 2006 11:16:44 GMT And now that we had a little activity with our Perl installation, we check out what "-history" can do for us. Remember, we did downgrade the Time::HiRes module, but somehow it is uptodate now. We investigate what happened to it: | shlab:~ # /usr/local/bin/CPAN+changelog.pl -history Time::HiRes | # Support EDRI! They defend your civil digital rights. | # see http://www.edri.org/edrigram why this is necessary. | #----------------------------------------------------------------------- | CPAN: Storable loaded ok | Going to read /root/.cpanlocal/Metadata | Database was generated on Sat, 04 Mar 2006 11:16:44 GMT | | CPAN home: /root/.cpanlocal | | Local distribution files under sources/authors/id: | J/JH/JHI/Time-HiRes-1.85.tar.gz | J/JH/JHI/Time-HiRes-1.87.tar.gz | | Bundle/Snapshot_2005_12_20_03.pm (20051220-013318): | Time::HiRes 1.82 | | Bundle/Snapshot_2006_03_04_00.pm (20060304-153618): | Time::HiRes 1.86 (1.82) | | BuildLogs/BuildLog-20060304-154829-HrPay4.gz: | # Installing: CGI,Devel::PPPort,Encode,Locale::Maketext,Pod::Man,Test::Builder::Module,Text::Soundex,Time::HiRes,Time::Local,threads::shared | Running make for J/JH/JHI/Time-HiRes-1.87.tar.gz | Wrote bundle file /root/.cpanlocal/Bundle/Snapshot_2006_03_04_02.pm | | Bundle/Snapshot_2006_03_04_02.pm (20060304-155332): | Time::HiRes 1.87 (1.86) | | BuildLogs/BuildLog-20060304-155535-W9Cluu.gz: | # Installing: J/JH/JHI/Time-HiRes-1.85.tar.gz | Running make for J/JH/JHI/Time-HiRes-1.85.tar.gz | Wrote bundle file /root/.cpanlocal/Bundle/Snapshot_2006_03_04_03.pm | | Bundle/Snapshot_2006_03_04_03.pm (20060304-155719): | Time::HiRes 1.85 (1.87) | | BuildLogs/BuildLog-20060304-155900-qUyRqz.gz: | # Installing: Bundle::Snapshot_2005_12_20_03 | Running make for J/JH/JHI/Time-HiRes-1.87.tar.gz | Wrote bundle file /root/.cpanlocal/Bundle/Snapshot_2006_03_04_04.pm | | Bundle/Snapshot_2006_03_04_04.pm (20060304-161343): | Time::HiRes 1.87 (1.85) From this report and because we know our Perl installation was done in 2006, we can derive: - Snapshot_2005_12_20_03.pm is older than our Perl installation, we have to ignore it. Alternatively, one might want to remove that file and re-run the history report. - Snapshot_2006_03_04_00.pm is only listed because it looks as if the version number of Time::HiRes had changed between this snapshot and Snapshot_2005_12_20_03.pm - Time::HiRes module started with v1.86 at 20060304-153618 (and still v1.86 after installing Bundle::LWP, Bundle::CPAN) updated to v1.87 at 20060304-155332 (the big update) downgraded to v1.85 at 20060304-155719 (explicit downgrade) back to v1.87 at 20060304-161343 (upgrade via Snapshot) - for further investigation we have these distribution files available locally: /root/.cpanlocal/sources/authors/id/J/JH/JHI/Time-HiRes-1.85.tar.gz /root/.cpanlocal/sources/authors/id/J/JH/JHI/Time-HiRes-1.87.tar.gz For the sake of completeness, an example for "-history" with multiple modules: | shlab:~ # /usr/local/bin/CPAN+changelog.pl -history Time::HiRes,Mail::SpamAssassin | # Support EDRI! They defend your civil digital rights. | # see http://www.edri.org/edrigram why this is necessary. | #----------------------------------------------------------------------- | CPAN: Storable loaded ok | Going to read /root/.cpanlocal/Metadata | Database was generated on Sat, 04 Mar 2006 11:16:44 GMT | | CPAN home: /root/.cpanlocal | | Local distribution files under sources/authors/id: | J/JH/JHI/Time-HiRes-1.85.tar.gz | J/JH/JHI/Time-HiRes-1.87.tar.gz | J/JM/JMASON/Mail-SpamAssassin-3.1.0.tar.gz | | Bundle/Snapshot_2005_12_20_03.pm (20051220-013318): | Mail::SpamAssassin 3.001000 | Time::HiRes 1.82 | | Bundle/Snapshot_2006_03_04_00.pm (20060304-153618): | Mail::SpamAssassin !!!MISSING!!! | Time::HiRes 1.86 (1.82) | | BuildLogs/BuildLog-20060304-154829-HrPay4.gz: | # Installing: CGI,Devel::PPPort,Encode,Locale::Maketext,Pod::Man,Test::Builder::Module,Text::Soundex,Time::HiRes,Time::Local,threads::shared | Running make for J/JH/JHI/Time-HiRes-1.87.tar.gz | Wrote bundle file /root/.cpanlocal/Bundle/Snapshot_2006_03_04_02.pm | | Bundle/Snapshot_2006_03_04_02.pm (20060304-155332): | Time::HiRes 1.87 (1.86) | | BuildLogs/BuildLog-20060304-155535-W9Cluu.gz: | # Installing: J/JH/JHI/Time-HiRes-1.85.tar.gz | Running make for J/JH/JHI/Time-HiRes-1.85.tar.gz | Wrote bundle file /root/.cpanlocal/Bundle/Snapshot_2006_03_04_03.pm | | Bundle/Snapshot_2006_03_04_03.pm (20060304-155719): | Time::HiRes 1.85 (1.87) | | BuildLogs/BuildLog-20060304-155900-qUyRqz.gz: | # Installing: Bundle::Snapshot_2005_12_20_03 | Running make for J/JM/JMASON/Mail-SpamAssassin-3.1.0.tar.gz | Running make for J/JH/JHI/Time-HiRes-1.87.tar.gz | Wrote bundle file /root/.cpanlocal/Bundle/Snapshot_2006_03_04_04.pm | | Bundle/Snapshot_2006_03_04_04.pm (20060304-161343): | Mail::SpamAssassin 3.001000 | Time::HiRes 1.87 (1.85) Here we see Mail::SpamAssassin has a "!!!MISSING!!!" marker for Bundle/Snapshot_2006_03_04_00.pm. This is another artefact from using Bundle::Snapshot_2005_12_20_03. In this Snapshot, Mail::SpamAssassin was installed, and it predates our installation. CPAN+changelog.pl sees that Mail::SpamAssassin existed in the old snapshot, but not in the next one, so it reports it as missing. Note for historians: you can use "-history" with the special name "all" to see a history report for every currently installed module. Now that you followed the tour 'til the end, you know everything you need to put this program to good use. Enjoy!