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 exit

DESCRIPTION

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.

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>