NAME

STEVEB::Dist::Mgr - My distribution development cycle toolkit

DESCRIPTION

This distribution is for my personal development cycle. At this time, is relies on using <c>module-starter</c> for initial distribution creation, Github for repository and bugtracker, and the ExtUtils::MakeMaker build system, which utilizes Makefile.PL files.

SYNOPSIS

    use STEVEB::Dist::Mgr qw(:all)

    my $results = bump_version('2.02');

    my $file_versions = get_version_info();

EXPORT_OK

We do not automatically import anything into your namespace, you must request functionality explicitly. Available functions are:

    # Makefile.PL functions

    add_bugtracker
    add_repository

    # Module file functions

    bump_version
    get_version_info

    # CI functions

    ci_github
    ci_badges

NOTE: You can auto import everything at once by specifying the :all tag.

FUNCTIONS

add_bugtracker

Adds bugtracker information to the Makefile.PL file. If the required META_MERGE section doesn't exist, we'll create it.

Currently, only Github is supported.

Parameters:

    $author

Mandatory, String: The Github username of the software author. For example, mine is stevieb9.

    $repository

Mandatory, String: The name of the repository. For example, the repository name for this distribution is steveb-dist-mgr.

    $makefile

Optional, String: The path and name of the Makefile.PL file to use. We default to ./Makefile.PL.

Returns: 0 upon success.

add_repository

Adds repository information to the Makefile.PL file. If the required META_MERGE section doesn't exist, we'll create it.

Currently, only Github is supported.

Parameters:

    $author

Mandatory, String: The Github username of the software author. For example, mine is stevieb9.

    $repository

Mandatory, String: The name of the repository. For example, the repository name for this distribution is steveb-dist-mgr.

    $makefile

Optional, String: The path and name of the Makefile.PL file to use. We default to ./Makefile.PL.

Returns: 0 upon success.

bump_version

Finds and updates the version number of a Perl module file, or all Perl module files in a directory structure.

Parameters:

    $version

Mandatory, String: The new version to update to.

Dry run mode

The $version parameter can be prepended with an optional dash (-), and if so, we'll operate in "dry-run" mode, where we'll return the results, but won't have written to any files. Eg: bump_version('-1.01').

    $fs_entry

Optional, String: The directory or file to operate on. If a directory is sent in, we'll iterate over all files in all directories recursively.

Default: lib/

Returns: An HoH:

    $VAR1 = {
        't/data/work/Two.pm' => {
            'dry_run'   => 0,
            'from'      => '2.66',
            'to'        => '2.67',
            'content'   => '' # Module file code (snipped for brevity)
        },
        't/data/work/One.pm' => {
            'dry_run'   => 0,
            'from'      => '2.66',
            'to'        => '2.67',
            'content'   => '' # Module file code (snipped for brevity)
        },
    };

get_version_info

Fetches the file version information of Perl module files. Can operate on a single file, or iterate over a directory structure.

Parameters:

    $fs_entry

Optional, String: The directory or file to operate on. If a directory is sent in, we'll iterate over all files in all directories recursively.

Default: lib/

Returns: Hash reference:

    $VAR1 = {
        't/data/orig/One.pm'    => '2.66'
        't/data/orig/Two.pm'    => '2.66',
        't/data/orig/Three.pm'  => '2.66',
        't/data/orig/Bad.pm'    => undef,   # $VERSION can't be parsed
        't/data/orig/No.pm'     => undef,   # No $VERSION defined
    };

ci_github

Installs a Github Actions configuration file into .github/workflows. We'll create the directory if it doesn't exist.

Parameters:

    $os

Optional, Array Reference: A list of the Operating Systems you want to run your tests on.

Valid values: l, w, m, where:

    l == Linux (Ubuntu to be specific)
    w == Windows
    m == MacOS

Returns: An array of the contents of the generated file.

ci_badges

Inserts various CI and coverage badges into module files.

Parameters:

    $author

Mandatory, String: The repository owner (eg. mine is 'stevieb9').

    $repository

Mandatory, String: The name of the repository (eg. this one is 'steveb-dist-mgr').

    $fs_entry

Optional, String: The path and name of a Perl module file, or a directory that contains Perl module files. If a directory is sent in, we'll operate recursively.

Returns: 0 upon success.

manifest_skip

Generates a MANIFEST.SKIP file.

Parameters:

    $directory

Optional, String: The directory where we'll create the file. If not specified, we'll create it in the current directory, ..

AUTHOR

Steve Bertrand, <steveb at cpan.org>

LICENSE AND COPYRIGHT

Copyright 2020 Steve Bertrand.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

AUTHOR

Steve Bertrand, <steveb at cpan.org>

LICENSE AND COPYRIGHT

Copyright 2020 Steve Bertrand.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

cpanm STEVEB::Dist::Mgr

perl -MCPAN -e shell
install STEVEB::Dist::Mgr