The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-Compile-v1.2.1
River stage three • 93 direct dependents • 156 total dependents
9 ++
/ Test::Compile

NAME

Test::Compile - Check whether Perl files compile correctly.

SYNOPSIS

    # The OO way (recommended)
    use Test::Compile;
    my $test = Test::Compile->new();
    $test->all_files_ok();
    $test->done_testing();

    # The procedural way
    use Test::Compile;
    all_pm_files_ok();

DESCRIPTION

Test::Compile lets you check the whether your perl modules and scripts compile properly, and report its results in standard Test::Simple fashion.

The basic usage - as shown above, will locate your perl files and test that they all compile.

Module authors can (and probably should) include the following in a t/00-compile.t file and have Test::Compile automatically find and check all Perl files in a module distribution:

    #!perl
    use strict;
    use warnings;
    use Test::Compile;
    my $test = Test::Compile->new();
    $test->all_files_ok();
    $test->done_testing();

METHODS

new()

A basic constructor, nothing special except that it returns a Test::Compile::Internal object.

all_files_ok(@dirs)

Checks all the perl files it can find for compilation errors.

If @dirs is defined then it is taken as an array of directories to be searched for perl files, otherwise it searches some default locatioons - see "all_pm_files()" and "all_pl_files()".

all_pm_files(@dirs)

Returns a list of all the perl module files - that is any files ending in .pm in @dirs and in directories below. If @dirs is undefined, it searches blib if blib exists, or else lib.

Skips any files in CVS or .svn directories.

The order of the files returned is machine-dependent. If you want them sorted, you'll have to sort them yourself.

all_pl_files(@dirs)

Returns a list of all the perl script files - that is, any files in @dirs that either have a .pl extension, or have no extension and have a perl shebang line.

If @dirs is undefined, it searches script if script exists, or else bin if bin exists.

Skips any files in CVS or .svn directories.

The order of the files returned is machine-dependent. If you want them sorted, you'll have to sort them yourself.

pl_file_compiles($file)

Returns true if $file compiles as a perl script.

pm_file_compiles($file)

Returns true if $file compiles as a perl module.

verbose($verbose)

An accessor to get/set the verbose flag. If verbose is set, you can get some extra diagnostics when compilation fails.

Verbose is set on by default.

Test Methods

Test::Compile::Internal encapsulates a Test::Builder object, and provides access to some of its methods.

done_testing()

Declares that you are done testing, no more tests will be run after this point.

ok($test,$name)

Your basic test. Pass if $test is true, fail if $test is false. Just like Test::Simple's ok().

plan($count)

Defines how many tests you plan to run.

exported_to($caller)

Tells Test::Builder what package you exported your functions to. I am not sure why you would want to do that, or whether it would do you any good.

diag(@msgs)

Prints out the given @msgs. Like print, arguments are simply appended together.

Output will be indented and marked with a # so as not to interfere with test output. A newline will be put on the end if there isn't one already.

We encourage using this rather than calling print directly.

skip($reason)

Skips the current test, reporting the $reason.

skip_all($reason)

Skips all the tests, using the given $reason. Exits immediately with 0.

FUNCTIONS

all_pm_files_ok(@files)

Checks all the perl module files it can find for compilation errors.

It uses all_pm_files(@files) to find the perl module files.

It also calls the plan() function for you (one test for each module), so you can't have already called plan. Unfortunately, this also means you can't use this function with all_pl_files_ok(). If this is a problem you should really be using the object oriented interface.

Returns true if all Perl module files are ok, or false if any fail.

Module authors can include the following in a t/00_compile.t file and have Test::Compile automatically find and check all Perl module files in a module distribution:

    #!perl -w
    use strict;
    use warnings;
    use Test::More;
    eval "use Test::Compile";
    Test::More->builder->BAIL_OUT(
        "Test::Compile required for testing compilation") if $@;
    all_pm_files_ok();
all_pl_files_ok(@files)

Checks all the perl script files it can find for compilation errors.

It uses all_pl_files(@files) to find the perl script files.

It also calls the plan() function for you (one test for each script), so you can't have already called plan. Unfortunately, this also means you can't use this function with all_pm_files_ok(). If this is a problem you should really be using the object oriented interface.

Returns true if all Perl script files are ok, or false if any fail.

Module authors can include the following in a t/00_compile_scripts.t file and have Test::Compile automatically find and check all Perl script files in a module distribution:

    #!perl -w
    use strict;
    use warnings;
    use Test::More;
    eval "use Test::Compile";
    plan skip_all => "Test::Compile required for testing compilation"
      if $@;
    all_pl_files_ok();
pm_file_ok($filename,$testname)

pm_file_ok() will okay the test if $filename compiles as a perl module.

The optional second argument $testname is the name of the test. If it is omitted, pm_file_ok() chooses a default test name Compile test for $filename.

pl_file_ok($filename,$testname)

pl_file_ok() will okay the test if $filename compiles as a perl script. You need to give the path to the script relative to this distribution's base directory. So if you put your scripts in a 'top-level' directory called script the argument would be script/filename.

The optional second argument $testname is the name of the test. If it is omitted, pl_file_ok() chooses a default test name Compile test for $filename.

all_pm_files(@dirs)

Returns a list of all the perl module files - that is, files ending in .pm - in @dirs and in directories below. If no directories are passed, it defaults to blib if blib exists, or else lib if not. Skips any files in CVS or .svn directories.

The order of the files returned is machine-dependent. If you want them sorted, you'll have to sort them yourself.

all_pl_files(@dirs)

Returns a list of all the perl script files - that is, any files in @dirs that either have a .pl extension, or have no extension and have a perl shebang line.

If @dirs is undefined, it searches script if script exists, or else bin if bin exists.

Skips any files in CVS or .svn directories.

The order of the files returned is machine-dependent. If you want them sorted, you'll have to sort them yourself.

AUTHORS

Sagar R. Shah <srshah@cpan.org>, Marcel Grünauer, <marcel@cpan.org>, Evan Giles, <egiles@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2007-2014 by the authors.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Test::Compile::Internal provides the object oriented interface to (and the inner workings for) the Test::Compile functionality.

Test::Strict proveds functions to ensure your perl files comnpile, with added bonus that it will check you have used strict in all your files. Test::LoadAllModules just handles modules, not script files, but has more fine-grained control.