NAME
ucpan - improved CPAN modules updater
SYNOPSIS
ucpan # update outdated modules,
# but skip previously failed modules
ucpan --local-lib /my/local/lib
# update modules into your local lib, like cpanm
ucpan --mirror http://example.com/CPAN/mirror
# use CPAN mirror site, like cpanm and cpan-outdated
ucpan -f # update outdated modules even if failed previously
ucpan -s # show previously failed modules and exit
ucpan -c # check outdated modules and exitDESCRIPTION
ucpan is module update program.
This program has the following advantages over executing "cpan-outdated | cpanm" from the command line.
Display the outdated module list in easy-to-see table format.
Display the progress from fetch to install compactly (in principle, in one line).
Display summary of results in table format.
This program are executed in the following order.
- 1. Check Phase
-
Outdated modules are checked and listed. The version number of the module that failed in the previous execution record is compared with the latest version number and if not updated it is marked to skip the installation. The list is displayed in tabular form.
(example) >>> Checking Outdated Modules... Name Current Latest Fail at... App::Cpan 1.66 1.675 Archive::Tar 2.24_01 2.32 B::Debug 1.24 1.26 bigint 0.47 0.51 Carp 1.42 1.50 Compress::Zlib 2.074 2.084 Test ......... Unicode::Collate 1.19 1.27 Unicode::Normalize 1.25 1.26 version 0.9917 0.9924 7sec.The update target and the skip module are displayed in a color-coded manner.
- 2. Installation Phase
-
Outdated modules are sequentially installed for each distribution. The progress of installation will be displayed in one line, one by one in order of fetch, build, test, installation. If it fails in the middle, "Failure" is displayed, and it moves to the next module. If a dependent module is found, the display is indented and the same process is done.
(example) >>> Upgrading outdated modules Archive-Tar [Archive::Tar] (1/57) Fetch..Configure..Build..Test..FAIL(23 sec) B-Debug [B::Debug] (2/57) Fetch..Configure..Build..Test..Install..SUCCESS(10 sec) CPAN [App::Cpan] (3/57) Fetch..Configure..Dependency found! Compress-Bzip2 [Compress::Bzip2] Fetch..Configure..Build..Test..Install..SUCCESS(47 sec) File-HomeDir [File::HomeDir] Fetch..Configure..Dependency found! File-Which [File::Which] Fetch..Configure..Build..Test..Install..SUCCESS(8 sec) -->[File-HomeDir]Build..Test..Install..SUCCESS(19 sec) Module-Build [Module::Build] Fetch..Configure..Build..Test..FAIL(88 sec) ...... Archive-Zip [Archive::Zip] Fetch..Configure..Dependency found! Test-MockModule [Test::MockModule] Fetch..FAIL(0 sec) --> Archive-Zip...FAIL(1 sec) --> CPAN...FAIL(709 sec) Carp [Carp] (9/57) Fetch..Configure..Ongoing process, SUCCESS, FAIL etc are color coded.
Installation logs and working files are placed under $HOME/.cpanm (like cpanm).
- 3. Result Phase
-
The results sammary of the installation will be displayed in tabular form with a list of successes and failures, and displayed the number of successful modules, added modules and failed modules.
(example) **************** SUMMARY **************** Upgrade Success---------------------------------------------- Compress::Raw::Bzip2 2.074 2.084 Net::HTTP ~ 6.18 HTML::Entities ~ 3.69 HTTP::Daemon ~ 6.01 Config::Perl::V 0.280 0.310 ...... Filter::Util::Call 1.550 1.590 Test::YAML ~ 1.07 Fail to upgrade---------------------------------------------- App::Cpan 1.660 1.675 Dependency IO::Pty 1.12 Configure Archive::Tar 2.240100 2.320 Test ExtUtils::Command 7.240 7.340 Test Test::MockModule v0.170.0 Fetch DB_File 1.840 1.843 Build Math::BigInt::FastCalc 0.500500 0.500800 Dependency 47 modules upgraded. 32 modules added. 20 modules FAILURE.
COMMANDS
The commands can control the execution of this program.
Only one command can be specified to determine the execution mode. If the command is not specified, it is executed in the check and installation mode.
- -c, --check-only
-
Check updated modules and exit.
- -s, --show-fails
-
Display previously failed modules list in table format and exit. Note that this list is generated from previous execution record, therefore, the latest version number of modules installed without this program after the last execution is not reflected.
- -r, --recover
-
Recover recoding file againt unwanted result. In this mode, failed modules are removed from the previous execution record except usual failure( this failure is marked as "UNKNOWN" ).
- -v, --version
-
Display the version number.
- -h, --help
-
Display the help message.
OPTIONS
- -f, --force-try
-
Also install modules marked as skipped.
- -l, --local-lib
- -L, --local-lib-conained
-
Works same as cpanm, and also same as cpan-outdated.
See cpanm for more detail.
- --exclude-core
-
Never list the core modules in the outdated module list.
- --mirror
-
Works same as cpanm, and also same as cpan-outdated, but cpanm and cpan-outdated have differences in the behavior of this option.
Note: This option follows the behavior of cpan-outdated:
cpanm can take more than one mirror, but cpan-outdated only enables last one.
cpan-outdated only looks at the modules list of the mirror looking for outdated modules. It does not reference metacpan's database like cpanm.
- --configure-timeout
-
Specify the timeout length (in seconds) to wait for the configure. Current default value is 60
- --build-timeout
-
Specify the timeout length (in seconds) to wait for the build. Current default value is 3600
- --test-timeout
-
Specify the timeout length (in seconds) to wait for the build. Current default value is 1800
- -j, --test-jobs
-
Control the parallel job habits of the test. Please do not give zero, the program ends with a warning. Note that this option internally replaces the environment variable HARNESS_OPTIONS.
- -S, --sudo
- --no-sudo
-
Switch to the root user with sudo when installing modules, or deny this.
See cpanm for more detail.
RECODING FILE
The previous result is recorded in the recoding file of this program. Normally you do not need to edit this file.
The recoding file is named .ucpandb and placed in the top of @INC (ie. $INC[0]). For example, if using local::lib, it is placed in /your/local/lib/$Config{archname}/.ucpandb. This is to ensure that the settings do not interfere with running this program for different Perl environments.
In the recording file, the following items are recorded in YAML format.
- Successful module
-
Module name, preinstallation version, installed version
- Failed distribution
-
Distribution file path, distribution version, module name of included module, version before installation, latest version, reason (for example, build, test, test timeout), processing time (seconds)
BRIEF EXPLANATION OF THE MECHANISM
At first, the previous execution record is loaded from the recoding file.
In Check Phase, information on outdated modules is gathered via cpan-outdated. The module to be skipped is determined by collating with the previous execution record.
In Installation Phase, the installation work is progressed using the function of loaded cpanm (yes, loading cpanm). Success of the result, which phases of the work failed, etc. are recorded.
In Result Phase, the summary is assembled and displayed based on the record of the installation.
Finally, the execution record is written to the recoding file.
SPECIAL FEATURE FOR WIN32
In the Win32 environment, the following matters have been improved for cpanm.
- Symbolic link
-
cpanm creates a symbolic link of the latest build log and working directory directly under $HOME/.cpanm, but it is not created under Win32 environment. ucpan can emulate symlink() and create it using Win32's mklink command. (There is no one working in FAT32 environment anymore, is it?)
- Timeout
-
cpanm ignores the --*-timeout option in Win32 environment, but in Win32 environment SIGALARM can also be used to implement timeout processing. ucpan implements this.
ENVIRONMENT VARIABLES
The following environment variables affect this program.
- PERL5LIB, PERL_LOCAL_LIB_ROOT, PERL_MB_OPT, PERL_MM_OPT,
- PERL_CPANM_HOME, PERL_CPANM_OPT
- HARNESS_OPTIONS( for test environment )
SEE ALSO
App::ucpan, App::cpanminus, cpanm
LICENSE
Copyright (C) KPEE.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
AUTHOR
KPEE <kpee.cpan@gmail.com>