view release on metacpan or  search on metacpan

share/README.md  view on Meta::CPAN

identifying all of the Perl modules you've installed from CPAN to use
in your application.  Once you've identified all of the artifacts
necessary to include in your package (so your application will run
somewhere other than your laptop) you need to package those up
somehow. At the very least you need to create a manifest that
can be used when your application is installed.

Identifying non-core Perl modules required by your application can be
done manually by:

* inspecting each Perl module and finding where you `use` or `require` a module.
* determining the version of that module that has been tested with your
application
* determining if that module version was core in the Perl version your
application will running on or it needs to be installed

> `perl` provides a utility (`corelist`) which will report the version
> of `perl` that a particlular module was added or removed from core.
> Make sure you have an updated version of `corelist` installed!

This project uses the `scandeps-static.pl` utility to resolve
dependencies. this utility is distributed with the
[Module::ScanDeps::Static](https://metacpan.org/pod/Module::ScanDeps::Static)
Perl module. It is a rewrite of `perl.req` found in RedHat systems.

I've found it to do a better job than `scandeps.pl` or any of the
other dependency resolvers you might stumble across.  That's not to
say that it is fool proof or even the best dependency checker for
Perl.  That is a subject of a long blog post I think I should write
some day. Oh wait I did...

[Perl Dependency Checking](http://blogs.perl.org/users/rlauer/2019/01/perl-dependency-checking.html)

If you don't want to use that utility but have another favorite Perl
module dependency resolver then you're free to use that by providing
it on the command line (-r) of the `bash` helper script
(`make-cpan-dist`) or in the build specification. The function you
specify should simply provide a list of Perl modules one per line and
output that to STDOUT.

You can replace the use of `scandeps-static.pl` with `scandeps.pl` by
specifying the `-s` option to the helper script.

Other competing dependency checkers include:

* `Devel::Modlist`
* `Perl::PrereqScanner`

...all of which will give about the same results as `scandeps.pl`

If you use any of those other checkers, wrap them in a script to make
sure they output the list in the correct format.

```
cat <<eof > dep_resolver
#!/bin/bash

perl -MDevel::Modlist=nocore \$1.pm 2>&1 | awk '{ print \$1}'
eof

chmod +x dep_resolver
make-cpan-dist -a 'Rob Lauer <rlauer6@comcast.net>' \
   -m MyFunc -R no -l . -d "my function" \
   -r dep_resolver
```

[Back to Table of Contents](#table-of-contents)

# What Next?

After successfully building and installing the project you will have
available two utilities that are used together to build a CPAN
distribution.

* `make-cpan-dist`
* `make-cpan-dist.pl`

When using a buildspec file you need only be concerned with
`make-cpan-dist.pl` and simply pass the buildspec file as a parameter.

```
make-cpan-dist.pl -b buildspec.yml
```

[Back to Table of Contents](#table-of-contents)

# Creating a CPAN Distribution

There are three possible ways to create a CPAN distribution using the
utiities contained in this project, each with varying degrees of
simplicity and flexibility.  As a reminder, the point of these
utilities is to provide a __simple__ solution right?  So the
_simplest_ thing you can do is run the utility against a
`buildspec.yml` file that describes the distribution you would like to
create.

## The Easy Way

Create a `buildspec.yml` file that looks something like this:

```
project:
  git: https://github.com/rlauer6/perl-Amazon-Credentials.git 
  description: "AWS credentials discoverer"
  author:
    name: Rob Lauer
    mailto: rlauer6@comcast.net
pm_module: Amazon::Credentials
path:
  pm_module: src/main/perl/lib
  tests: src/main/perl/t
  exe_files: src/main/perl/bin
```

You specify some project metadata in the `project:` section and
possibly a pointer to the project in a git repository that will be
cloned.

You must also provide the name of the Perl module to package
(`pm_module`) and include a `path:` section that will point to the
modules and artifacts to be packaged.