NAME

CPAN::Cpanorg::Auxiliary - Methods used in cpan.org infrastructure

USAGE

    use CPAN::Cpanorg::Auxiliary;

DESCRIPTION

The objective of this library is to provide methods which can be used to write replacements for programs used on the CPAN master server and stored in github.com in the perlorg/cpanorg and devel/cpanorg-generators repositories.

In particular, each of those repositories has an executable program with subroutines identical, or nearly so, to subroutines found in a program in the other. Those programs are:

• cpanorg-generators: bin/perl-sorter.pl

• cpanorg: bin/cpanorg_perl_releases

By extracting these subroutines into a single package, we hope to improve the maintainability of code running on the CPAN infrastructure.

METHODS

new()

• Purpose

  CPAN::Cpanorg::Auxiliary constructor. Primarily used to check for the presence of certain directories and files on the server. Also stores certain values that are currently hard-coded in various methods in perl-sorter.pl and cpanorg_per_releases.

• Arguments

      my $self = CPAN::Cpanorg::Auxiliary->new({});

  Hash reference, required. Elements in that hash include:

  • path

    Absolute path to the directory on the server which serves as the "top-level" of the infrastructure. Beneath this directory we expect to find these directories already in existence:

        ./CPAN
        ./CPAN/src
        ./CPAN/src/5.0
        ./CPAN/authors
        ./CPAN/authors/id
        ./content
        ./data

  • verbose

    If provided with a Perl-true value, all methods produce extra output on STDOUT when run. (However, no methods are yet coded for extra output.)

  • versions_json

    String holding the basename of a file to be created (or regenerated) on server holding metadata in JSON format about all releases of perl. Optional; defaults to perl_version_all.json.

  • search_api_url

    String holding the URL for making an API call to get metadata about all releases of perl. Optional; defaults to http://search.cpan.org/api/dist/perl.

• Return Value

  CPAN::Cpanorg::Auxiliary object.

• Comment

fetch_perl_version_data()

• Purpose

  Compares JSON data found on disk to result of API call to CPAN for 'perl' distribution.

• Arguments

  None at the present time.

• Return Value

  List of two array references:

  • List of hash references, one per stable perl release.

  • List of hash references, one per developmental or RC perl release.

  Side effect: Guarantees existence of file data/perl_version_all.json beneath the top-level directory.

• Comment

  Assumes existence of subdirectory data/ beneath current working directory.

add_release_metadata()

• Purpose

  Enhance object's data structures with metadata about perl releases.

• Arguments

  None.

• Return Value

  None.

write_security_files_and_symlinks()

• Purpose

  For each perl release, create three security files: md5 sha1 sha256. Create symlinks from the src and src/5.0 directories to the originals underneath the release manager's directory under authors/id.

• Arguments

  None.

• Return Value

  Returns true value upon success.

create_latest_only_symlinks()

• Purpose

  Create two symlinks in src directory:

      /src/latest.tar....
      /src/stable.tar....

  One symlink for each compression format for a particular release.

• Arguments

  None.

• Return Value

  Returns true value upon success.

• Comment

  Per https://www.cpan.org/src/ (retrieved Jun 10 2018): The "latest" and "stable" are now just aliases for "maint", and "maint" in turn is the maintenance branch with the largest release number.

print_file()

• Purpose

  Write out data from an array reference, here, data from the result of an HTTP get call which returns data in JSON format.

• Arguments

      $self->print_file($file, $array_ref);

  Two arguments: basename of a file to be written to (implicitly, in a subdirectory called data/); reference to an array of JSON elements.

• Return Value

  Implicitly returns true value upon success. Dies otherwise.

• Comment

file_meta

    my $meta = file_meta($file);

        print $meta->{file};
        print $meta->{filename};
        print $meta->{filedir};
    print $meta->{md5};
    print $meta->{sha256};
    print $meta->{mtime};
    print $meta->{sha1};

Get or calculate meta information about a file

create_symlink

    create_symlink($oldfile, $newfile);

Will unlink $newfile if it already exists and then create the symlink.

sort_versions()

• Purpose

  Produce appropriately sorted list of Perl releases.

• Arguments

      my $latest = sort_versions( [ values %{$latest_per_version} ] )->[0];

• Return Value

• Comment

  Call last.

extract_first_perl_version_in_list()

• Purpose

• Arguments

• Return Value

• Comment

cpanm CPAN::Cpanorg::Auxiliary

perl -MCPAN -e shell
install CPAN::Cpanorg::Auxiliary