CPAN+changelog.pl TECH DETAILS ============================== Date: 2008/11/18 - COMPATIBILITY - Tested on NetBSD2.1 (perl 5.8.7, perl 5.8.8) SuSE Linux 8.1 (perl 5.8.5) SuSE Linux 8.2 (perl 5.8.6) SuSE Linux 9.0 (perl 5.8.1) SuSE Linux 9.1 (perl 5.8.7, perl 5.8.8) SuSE Linux 9.2 (perl 5.8.7) Debian GNU/Linux sarge (perl 5.8.7) SuSE Linux 10.0 (perl 5.8.8) SuSE Linux 10.1 (perl 5.8.8) Debian GNU/Linux etch (perl 5.8.7) (*) Ubuntu 6.06LTS (perl 5.8.7) Ubuntu 8.04LTS (perl 5.8.7) (*) CPAN >= 1.76 File::Basename; File::Temp qw/ tempfile /; FileHandle; (*): yes, this is not the systems default perl installation! - Will not work on Windows because I did not bother to use File::Spec for composing path names but used "/" throughout. Perhaps in a later version if someone asks me nicely :-) - You can continue to use plain CPAN for upgrades without breaking this program. You just have fewer hints for the "-history" function and the local ChangeLog database gets out of sync for those modules, so the next "-r" ChangeLog output might be incorrect for them, but they will still be correctly detected as upgradeable. - PREREQUISITES - a working Perl installation with a working CPAN configuration - gzip, zgrep, xargs and find within your $PATH (ls is also used, but is probably handled by your shell's builtin) - RECOMMENDATION - sometimes the CPAN module behaves strangely when it cannot use LWP to handle internet downloads. Do yourself a favour and install Bundle::LWP. - INSTALLATION Since it is a single file, not much installation action is required. If your perl is not at /usr/bin/perl, edit the first line to point to your perl interpreter. Copy the program to where you deem adequate, e.g. into /usr/local/bin Best install it to a directory that's inside your $PATH. To "-init" or not to "-init": If your Perl modules are already uptodate with CPAN, then you might want to first start the software with the "-init" option to initialise the local ChangeLog database. This reduces future "-r" output to the real novelties in the distributions ChangeLog file. Running "-init" may take quite a while as some files probably need to be fetched from CPAN. ONLY USE "-init" IF YOUR MODULES ARE UP TO DATE! Otherwise the ChangeLog database will be filled with the most recent CPAN versions and you will not see much ChangeLog on the next "-r" run. Other than being treated with the full ChangeLog file instead of just the changes there are no dangers in not using "-init". - INVOCATION CPAN+changelog.pl [...] or /your/installed/CPAN+changelog.pl [...] or /path/to/perl /your/installed/CPAN+changelog.pl [...] If you installed the script to a directory within your $PATH, you can use the first form. The first and second form depend on the correct interpreter line in the script file itself. As it uses your CPAN configuration values, the third form of invocation allows you to manage CPAN updates for several Perl installations on the same host. Just choose the right /path/to/perl. - OPTIONS -r this is the default action if no options are given. shows the list of upgradeable modules and the relevant ChangeLog entries. Note: this requires that the latest distribution files of upgradeable modules are downloaded and unpacked. It might therefore take significantly longer than CPAN's native "r" command. -install [,...] can be the name of a module, a bundle or a distribution. To downgrade a module you need to "-install" the distribution containing the wanted module version. While it is possible to mix bundles, modules, distributions, upgrades and downgrades into a single call, I strongly advise against doing so for the sake of clarity. It calls CPANs native "install" for every while collecting screen output in a BuildLog file. If there are any module version changes after the install, CPANs "autobundle" is called to generate a snapshot of the currently installed modules. Additional output: -ChangeLogs of installed modules -diff against the previous snapshot -full path of the BuildLog -modules that have not changed in spite of having been "install"ed Examples for : Time::HiRes (module) J/JH/JHI/Time-HiRes-1.85.tar.gz (distribution) Bundle::Snapshot_2005_12_15_00 (bundle) Note: The check for every Perl modules' version number can take a while, depending on your CPU and disk speed. This check is done before and after CPANs native "install" function to detect version changes. -shell invokes the interactive CPAN shell (CPAN::shell), so you can use any of the interactive features it provides. As with "-install" above, output is preserved in a BuildLog. If you successfully installed anything, the ChangeLog database will be updated and autobundle is called upon exit. Note: because of the output redirection, the command prompts (readline) may not be where you expect them. Usually, an extra RETURN gets the cpan prompt back, but watch out for readline prompts during module installation. -force (only used with -install) Does a "force install" instead of a "install". Use with caution! Only use -force if you know what you are doing! -history [,...] searches snapshot bundles and BuildLogs for mentions of the named module(s) and displays them in chronological order. Snapshots are only listed if the version number of the module(s) has changed. Also shows the locally available distribution files containing older or newer versions of the module(s). -init initialize the local ChangeLog database. For every module installed it fetches the most recent CPAN version and retrieves the ChangeLog file from it. Note: If you run "-init" while your modules are not uptodate with CPAN, "-r" will not show you any changes next time (but it still shows the upgradeable modules). You might as well choose not to run "-init" at all, but expect "-r" output to be very lengthy the first time a module will be reported as upgradeable. After an "-install" the local ChangeLog for the module will be in sync again. -version shows the RCS revision number -license shows disclaimer, license and notes about the license -addignore [,...] adds an ignore entry for the given distribution file(s) or the current CPAN version of the distribution for a given module name. The ignore list is kept at $CPANHOME/CPAN+changelog.ignore Effect of ignore list entries: - "-r" will not show that revision as upgradeable anymore, only when a newer version than the ignored one is available on CPAN - "-install" will not install an ignored distribution file, provided it was explicitly named as an "-install" argument. This is helpful when you know a certain distribution to be buggy, then the "-r" reports will not be cluttered with an ignored distribution file anymore. If you don't want to see buggy libnet-1.20 anymore in the reports, use "-addignore G/GB/GBARR/libnet-1.20.tar.gz" Note: this does not help against CPAN's auto dependency resolution, which might install it e.g. as part of a Bundle. it only helps you against inadvertedly upgrading a known bad distribution. -delignore [,...] removes ignore entries from the ignore file -showignore lists all currently ignored distribution files with their date of appearance in the list - FILES AND DIRECTORIES external programs: gzip, zgrep, xargs, find $CPAN::Config->{'build_dir'} CPAN build directory $CPAN::Config->{'cpan_home'} CPAN home directory /Bundle/ contains Snapshot bundles /ChangeLogs/ directory-based ChangeLog db / is the base name of a distribution file, with stripped- off version number, ist the name of the ChangeLog file in this distribution (Changes/ChangeLog/WhatsNew) /BuildLogs/ directory for the BuildLogs BuildLog---.gz BuildLog from an install started at - /CPAN+changelog.ignore list of distribution files to be ignored