.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 >0, 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 .\" ======================================================================== .\" .IX Title "Test::Compile 3pm" .TH Test::Compile 3pm 2024-05-08 "perl v5.38.2" "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 \- Assert that your Perl files compile OK. .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use Test::Compile qw(); \& \& my $test = Test::Compile\->new(); \& $test\->all_files_ok(); \& $test\->done_testing(); .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, results are reported 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 4 \& #!perl \& use strict; \& use warnings; \& use Test::Compile qw(); \& \& 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()" The constructor, which actually returns a Test::Compile::Internal object. This gives you access to all the methods provided by \&\f(CW\*(C`Test::Compile::Internal\*(C'\fR, including those listed below. .ie n .IP all_files_ok(@dirs) 4 .el .IP \f(CWall_files_ok(@dirs)\fR 4 .IX Item "all_files_ok(@dirs)" Looks for perl files and tests them all for compilation errors. .Sp See "all_files_ok(@dirs)" in Test::Compile::Internal for the full documentation. .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 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. .SH FUNCTIONS .IX Header "FUNCTIONS" The use of the following functions is deprecated and strongly discouraged. .PP Instead, you should use the object oriented interface described in the "SYNOPSIS" and in Test::Compile::Internal. .PP They are automatically exported to your namespace, which is no longer considered best practise. At some stage in the future, this will stop and you'll have to import them explicitly to keep using them. .PP The object oriented methods also provide a more consistent interface. For example: \f(CWall_pm_files_ok()\fR calls the \f(CWplan()\fR function \- so you can't call multiple test functions in the same test file. .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)" \&\fBThis function is deprecated\fR. Please use "all_pm_files_ok(@dirs)" in Test::Compile::Internal instead. It's pretty much the same, except it doesn't call the \f(CWplan()\fR function. .Sp Checks all the perl module files it can find for compilation errors. .Sp It uses \f(CWall_pm_files(@files)\fR to find the perl module files. .Sp It also calls the \f(CWplan()\fR function for you (one test for each module), so you can't have already called \f(CWplan()\fR. Unfortunately, this also means you can't use this function with \f(CWall_pl_files_ok()\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. .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)" \&\fBThis function is deprecated\fR. Please use "all_pl_files_ok(@dirs)" in Test::Compile::Internal instead. It's pretty much the same, except it doesn't call the \f(CWplan()\fR function. .Sp Checks all the perl script files it can find for compilation errors. .Sp It uses \f(CWall_pl_files(@files)\fR to find the perl script files. .Sp It also calls the \f(CWplan()\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(CWall_pm_files_ok()\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. .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)" \&\fBThis function is deprecated\fR. Please use "all_pm_files_ok(@dirs)" in Test::Compile::Internal instead. It's pretty much the same, except it won't allow you to specify a test name, and it can handle more than one file at a time. .Sp \&\f(CWpm_file_ok()\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(CWpm_file_ok()\fR chooses a default test name \f(CWCompile test for $filename\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)" \&\fBThis function is deprecated\fR. Please use "all_pl_files_ok(@dirs)" in Test::Compile::Internal instead. It's pretty much the same, except you can't specify a test name, and it can handle more than one file at a time. .Sp \&\f(CWpl_file_ok()\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(CWpl_file_ok()\fR chooses a default test name \f(CWCompile test for $filename\fR. .ie n .IP all_pm_files(@dirs) 4 .el .IP \f(CWall_pm_files(@dirs)\fR 4 .IX Item "all_pm_files(@dirs)" \&\fBThis function is deprecated\fR. Please use "all_pm_files(@dirs)" in Test::Compile::Internal instead. .Sp Returns a list of all the perl module files \- that is, files ending in \fI.pm\fR \&\- in \fR\f(CI@dirs\fR\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 \fICVS\fR, \fI.svn\fR, or \fI.git\fR directories. .ie n .IP all_pl_files(@dirs) 4 .el .IP \f(CWall_pl_files(@dirs)\fR 4 .IX Item "all_pl_files(@dirs)" \&\fBThis function is deprecated\fR. Please use "all_pl_files(@dirs)" in Test::Compile::Internal instead. .Sp 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 \fICVS\fR, \fI.svn\fR, or \fI.git\fR directories. .ie n .IP all_files_ok(@dirs) 4 .el .IP \f(CWall_files_ok(@dirs)\fR 4 .IX Item "all_files_ok(@dirs)" \&\fBThis function is deprecated\fR. Please use "all_files_ok(@dirs)" in Test::Compile::Internal instead. .Sp 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 locations \&\- see "all_pm_files(@dirs)" and "all_pl_files(@dirs)". .SH AUTHORS .IX Header "AUTHORS" Sagar R. Shah \f(CW\*(C`\*(C'\fR, Marcel GrĂ¼nauer, \f(CW\*(C`\*(C'\fR, Evan Giles, \f(CW\*(C`\*(C'\fR .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2007\-2023 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 provides functions to ensure your perl files compile, with the added bonus that it will check you have used strict in all your files. .PP Test::LoadAllModules just handles modules, not script files, but has more fine-grained control.