NAME

find-requires.pl

SYNOPSIS

find-requires.pl --path src/main/perl list-requires

find-requires.pl --path src/main/perl dump-map

Script to maintain a manifest of Perl module dependencies for a project.

DESCRIPTION

find-requires.pl is a script to help you find and maintain a list of dependencies for your Perl application. The script will create a requires file which can be used to produce a cpanfile typically used by Carton.

The requires file is a JSON file similar to the one shown below.

{
 "requires" : [
    "DBI" : "1.643",
    "Readonly": "2.05",
    ...
  ],
 "exclude" : [
    ...
  ]
}

When find-requires determines dependencies it will automatically exclude Perl modules provided by your application.

Excluding Modules from the Dependency List

You can add entries to the exclude list in the requires file so that specific modules will not be added to your dependency list. You might want to do this if, for example, there are certain modules that are not provided by CPAN and should not be listed in your final cpanfile. The script uses this list by essentially filtering the final dependency list using a regular expression where the module to be excluded "starts with" the string in your exclude list.

Let's suppose you have some custom Perl modules provided by another application (not in CPAN) that have namespace of Foo.

Adding Foo to the exclude list will exclude all modules found as dependencies that begin with Foo.

Adding New Requirements

You can edit the requires file and add new dependencies. You can also allow the script to look for new dependencies and update the list automatically (See RECIPES).

The script can scan your entire application directory or a single file while looking for new dependencies. This makes it ideal for making sure your application depencencies are uptodate whenver a file is modified. If you are using git as your version control system for example, you can create a pre-commit hook that scans the file for new dependencies and either halts the commit or automatically adds the dependency before commiting the file.

OPTIONS

--help, -h         help
--core, --no-core  include core modules (default: false)
--exclude, -e      module(s) to exclude
--exclude-path, -E path(s) to exclude
--file, -f         path to single file to scan
--filter, -F       name of a file containing names of modules to exclude 
                   from requires list
--format, -t       format of output (text|json)
--max-items, -m    maximum number of files to scan 
--min-perl-version minimum version of perl to consider a module as 'core' (default 5.10.1)
--module, -M       module to add when using 'add-requires'
--module-version   module version when adding module to requires list (default: 0)
--no-recurse       do not recurse into subdirectories when lookin for files
--output, -o       file to write output to (default: STDOUT)
--path, -p         path to search for .pm & .pl files
--progress-bar,-P  display progress bar, --no-progress-bar to turn off (default: true)
--requires, -r     name of the file containging the required modules and exclusion list
--update, -u       update the requires file
--versions, -v     include version numbers in output

Commands

add-requires       add a new required module to requires file
check-requires     checks a single file (or all files for new depdenencies)
create-cpanfile    creates a cpanfile from the requires file or as the output of a scan
create-requires    creates the requires file (see below for format specification)
dump-map           dumps a map of files and their dependencies
list-files         lists files to be scanned
list-packages      lists all packages found in files
list-requires      lists the dependencies (unfiltered, raw output)

Notes

* files in the current directory and below will be scanned unless
  --path or --file is provided. Use --no-recurse to stop the scanner
  from traversing below the root of your search path.

* 'dump-map' will always do a re-scan either on a single file or the
  list of files if no --file is given

* 'add-requires' will read a JSON formatted list of required modes
  from STDIN unless --module is provided. The format of the list is the
  same as that produced by 'check-requires' (see Recipes)

* 'check-requires' will look for a file named 'requires' in the
  current working directory unless the --requires option is provided

* 'check-requires' will return a 0 on success and -1 if new
  requirements are found facilitating use in bash scripts and
  Makefile recipes

Recipes

Note: The recipes below that do not use the --path option, assume you are executing the script from the root of your application.

• create the requires file the first time

  find-requires.pl --path src/main/perl create-requires > requires

• check to see if a module has a new requirement

  find-requires.pl -f src/main/perl/lib/TreasurersBriefcase/Foo.pm check-requires

• add new dependencies to the requires file

  find-requires.pl --module Foo --module-version 0.1 add-requires
  
  find-requires.pl --file myscript.pl check-requires | \
     find-requires.pl -u add-requires

• delete a module from the requires file

  find-requires.pl -M Foo::Bar::Baz -u delete-requires

• create a cpanfile from the requires file

  find-requires.pl create-cpanfile

• create listing of each file and its dependencies

  Note: dump-map will always rescan the entire application directory.

  find-requires dump-map

SEE OTHER

Module::ScanDeps::Static

AUTHOR

Rob Lauer - <bigfoot@cpan.org>