.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Test::Compile 3pm"
.TH Test::Compile 3pm "2014-09-20" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Compile \- Check whether Perl files compile correctly.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    # 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();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Test::Compile\*(C'\fR lets you check the whether your perl modules and scripts
compile properly, and report its results in standard \f(CW\*(C`Test::Simple\*(C'\fR fashion.
.PP
The basic usage \- as shown above, will locate your perl files and test that they
all compile.
.PP
Module authors can (and probably should) include the following in a \fIt/00\-compile.t\fR
file and have \f(CW\*(C`Test::Compile\*(C'\fR automatically find and check all Perl files
in a module distribution:
.PP
.Vb 7
\&    #!perl
\&    use strict;
\&    use warnings;
\&    use Test::Compile;
\&    my $test = Test::Compile\->new();
\&    $test\->all_files_ok();
\&    $test\->done_testing();
.Ve
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP """new()""" 4
.el .IP "\f(CWnew()\fR" 4
.IX Item "new()"
A basic constructor, nothing special except that it returns a
Test::Compile::Internal object.
.ie n .IP """all_files_ok(@dirs)""" 4
.el .IP "\f(CWall_files_ok(@dirs)\fR" 4
.IX Item "all_files_ok(@dirs)"
Checks all the perl files it can find for compilation errors.
.Sp
If \f(CW@dirs\fR is defined then it is taken as an array of directories to
be searched for perl files, otherwise it searches some default locatioons
\&\- see \*(L"\fIall_pm_files()\fR\*(R" and \*(L"\fIall_pl_files()\fR\*(R".
.ie n .IP """all_pm_files(@dirs)""" 4
.el .IP "\f(CWall_pm_files(@dirs)\fR" 4
.IX Item "all_pm_files(@dirs)"
Returns a list of all the perl module files \- that is any files ending in \fI.pm\fR
in \f(CW@dirs\fR and in directories below. If \f(CW@dirs\fR is undefined, it
searches \fIblib\fR if \fIblib\fR exists, or else \fIlib\fR.
.Sp
Skips any files in \f(CW\*(C`CVS\*(C'\fR or \f(CW\*(C`.svn\*(C'\fR directories.
.Sp
The order of the files returned is machine-dependent. If you want them
sorted, you'll have to sort them yourself.
.ie n .IP """all_pl_files(@dirs)""" 4
.el .IP "\f(CWall_pl_files(@dirs)\fR" 4
.IX Item "all_pl_files(@dirs)"
Returns a list of all the perl script files \- that is, any files in \f(CW@dirs\fR that
either have a \fI.pl\fR extension, or have no extension and have a perl shebang line.
.Sp
If \f(CW@dirs\fR is undefined, it searches \fIscript\fR if \fIscript\fR exists, or else
\&\fIbin\fR if \fIbin\fR exists.
.Sp
Skips any files in \f(CW\*(C`CVS\*(C'\fR or \f(CW\*(C`.svn\*(C'\fR directories.
.Sp
The order of the files returned is machine-dependent. If you want them
sorted, you'll have to sort them yourself.
.ie n .IP """pl_file_compiles($file)""" 4
.el .IP "\f(CWpl_file_compiles($file)\fR" 4
.IX Item "pl_file_compiles($file)"
Returns true if \f(CW$file\fR compiles as a perl script.
.ie n .IP """pm_file_compiles($file)""" 4
.el .IP "\f(CWpm_file_compiles($file)\fR" 4
.IX Item "pm_file_compiles($file)"
Returns true if \f(CW$file\fR compiles as a perl module.
.ie n .IP """verbose($verbose)""" 4
.el .IP "\f(CWverbose($verbose)\fR" 4
.IX Item "verbose($verbose)"
An accessor to get/set the verbose flag.  If \f(CW\*(C`verbose\*(C'\fR is set, you can get some
extra diagnostics when compilation fails.
.Sp
Verbose is set on by default.
.SS "Test Methods"
.IX Subsection "Test Methods"
\&\f(CW\*(C`Test::Compile::Internal\*(C'\fR encapsulates a \f(CW\*(C`Test::Builder\*(C'\fR object, and provides
access to some of its methods.
.ie n .IP """done_testing()""" 4
.el .IP "\f(CWdone_testing()\fR" 4
.IX Item "done_testing()"
Declares that you are done testing, no more tests will be run after this point.
.ie n .IP """ok($test,$name)""" 4
.el .IP "\f(CWok($test,$name)\fR" 4
.IX Item "ok($test,$name)"
Your basic test. Pass if \f(CW$test\fR is true, fail if \f(CW$test\fR is false. Just
like \f(CW\*(C`Test::Simple\*(C'\fR's \f(CW\*(C`ok()\*(C'\fR.
.ie n .IP """plan($count)""" 4
.el .IP "\f(CWplan($count)\fR" 4
.IX Item "plan($count)"
Defines how many tests you plan to run.
.ie n .IP """exported_to($caller)""" 4
.el .IP "\f(CWexported_to($caller)\fR" 4
.IX Item "exported_to($caller)"
Tells \f(CW\*(C`Test::Builder\*(C'\fR 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.
.ie n .IP """diag(@msgs)""" 4
.el .IP "\f(CWdiag(@msgs)\fR" 4
.IX Item "diag(@msgs)"
Prints out the given \f(CW@msgs\fR. Like print, arguments are simply appended
together.
.Sp
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.
.Sp
We encourage using this rather than calling print directly.
.ie n .IP """skip($reason)""" 4
.el .IP "\f(CWskip($reason)\fR" 4
.IX Item "skip($reason)"
Skips the current test, reporting the \f(CW$reason\fR.
.ie n .IP """skip_all($reason)""" 4
.el .IP "\f(CWskip_all($reason)\fR" 4
.IX Item "skip_all($reason)"
Skips all the tests, using the given \f(CW$reason\fR. Exits immediately with 0.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .IP """all_pm_files_ok(@files)""" 4
.el .IP "\f(CWall_pm_files_ok(@files)\fR" 4
.IX Item "all_pm_files_ok(@files)"
Checks all the perl module files it can find for compilation errors.
.Sp
It uses \f(CW\*(C`all_pm_files(@files)\*(C'\fR to find the perl module files.
.Sp
It also calls the \f(CW\*(C`plan()\*(C'\fR function for you (one test for each module), so
you can't have already called \f(CW\*(C`plan\*(C'\fR. Unfortunately, this also means
you can't use this function with \f(CW\*(C`all_pl_files_ok()\*(C'\fR.  If this is a problem
you should really be using the object oriented interface.
.Sp
Returns true if all Perl module files are ok, or false if any fail.
.Sp
Module authors can include the following in a \fIt/00_compile.t\fR file
and have \f(CW\*(C`Test::Compile\*(C'\fR automatically find and check all Perl module files
in a module distribution:
.Sp
.Vb 8
\&    #!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();
.Ve
.ie n .IP """all_pl_files_ok(@files)""" 4
.el .IP "\f(CWall_pl_files_ok(@files)\fR" 4
.IX Item "all_pl_files_ok(@files)"
Checks all the perl script files it can find for compilation errors.
.Sp
It uses \f(CW\*(C`all_pl_files(@files)\*(C'\fR to find the perl script files.
.Sp
It also calls the \f(CW\*(C`plan()\*(C'\fR function for you (one test for each script), so
you can't have already called \f(CW\*(C`plan\*(C'\fR. Unfortunately, this also means
you can't use this function with \f(CW\*(C`all_pm_files_ok()\*(C'\fR.  If this is a problem
you should really be using the object oriented interface.
.Sp
Returns true if all Perl script files are ok, or false if any fail.
.Sp
Module authors can include the following in a \fIt/00_compile_scripts.t\fR file
and have \f(CW\*(C`Test::Compile\*(C'\fR automatically find and check all Perl script files
in a module distribution:
.Sp
.Vb 8
\&    #!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();
.Ve
.ie n .IP """pm_file_ok($filename,$testname)""" 4
.el .IP "\f(CWpm_file_ok($filename,$testname)\fR" 4
.IX Item "pm_file_ok($filename,$testname)"
\&\f(CW\*(C`pm_file_ok()\*(C'\fR will okay the test if \f(CW$filename\fR compiles as a perl module.
.Sp
The optional second argument \f(CW$testname\fR is the name of the test. If it is
omitted, \f(CW\*(C`pm_file_ok()\*(C'\fR chooses a default test name \f(CW\*(C`Compile test for
$filename\*(C'\fR.
.ie n .IP """pl_file_ok($filename,$testname)""" 4
.el .IP "\f(CWpl_file_ok($filename,$testname)\fR" 4
.IX Item "pl_file_ok($filename,$testname)"
\&\f(CW\*(C`pl_file_ok()\*(C'\fR will okay the test if \f(CW$filename\fR 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 \f(CW\*(C`script/filename\*(C'\fR.
.Sp
The optional second argument \f(CW$testname\fR is the name of the test. If it is
omitted, \f(CW\*(C`pl_file_ok()\*(C'\fR chooses a default test name \f(CW\*(C`Compile test for
$filename\*(C'\fR.
.ie n .IP """all_pm_files(@dirs)""" 4
.el .IP "\f(CWall_pm_files(@dirs)\fR" 4
.IX Item "all_pm_files(@dirs)"
Returns a list of all the perl module files \- that is, files ending in \fI.pm\fR
\&\- in \fI\f(CI@dirs\fI\fR and in directories below. If no directories are passed, it
defaults to \fIblib\fR if \fIblib\fR exists, or else \fIlib\fR if not. Skips any files
in \f(CW\*(C`CVS\*(C'\fR or \f(CW\*(C`.svn\*(C'\fR directories.
.Sp
The order of the files returned is machine-dependent. If you want them
sorted, you'll have to sort them yourself.
.ie n .IP """all_pl_files(@dirs)""" 4
.el .IP "\f(CWall_pl_files(@dirs)\fR" 4
.IX Item "all_pl_files(@dirs)"
Returns a list of all the perl script files \- that is, any files in \f(CW@dirs\fR that
either have a \fI.pl\fR extension, or have no extension and have a perl shebang line.
.Sp
If \f(CW@dirs\fR is undefined, it searches \fIscript\fR if \fIscript\fR exists, or else
\&\fIbin\fR if \fIbin\fR exists.
.Sp
Skips any files in \f(CW\*(C`CVS\*(C'\fR or \f(CW\*(C`.svn\*(C'\fR directories.
.Sp
The order of the files returned is machine-dependent. If you want them
sorted, you'll have to sort them yourself.
.SH "AUTHORS"
.IX Header "AUTHORS"
Sagar R. Shah \f(CW\*(C`<srshah@cpan.org>\*(C'\fR,
Marcel Gru\*:nauer, \f(CW\*(C`<marcel@cpan.org>\*(C'\fR,
Evan Giles, \f(CW\*(C`<egiles@cpan.org>\*(C'\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2007\-2014 by the authors.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test::Compile::Internal provides the object oriented interface to (and the
inner workings for) the Test::Compile functionality.
.PP
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.