File: README.mkdn

package info (click to toggle)
libtest-compile-perl 0.13-1
  • links: PTS, VCS
  • area: main
  • in suites: squeeze
  • size: 308 kB
  • ctags: 228
  • sloc: perl: 3,034; makefile: 2
file content (189 lines) | stat: -rw-r--r-- 6,246 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
# NAME

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

# SYNOPSIS

    #!perl -w
    use strict;
    use warnings;
    use Test::Compile;
    all_pm_files_ok();

# DESCRIPTION

`Test::Compile` lets you check the validity of a Perl module file or Perl
script file, and report its results in standard `Test::Simple` fashion.

    BEGIN {
        use Test::Compile tests => $num_tests;
        pm_file_ok($file, "Valid Perl module file");
    }

It's probably a good idea to run this in a BEGIN block. The examples below
omit it for clarity.

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:

    use Test::More;
    eval "use Test::Compile 0.09";
    Test::More->builder->BAIL_OUT(
        "Test::Compile 0.09 required for testing compilation") if $@;
    all_pm_files_ok();

You can also specify a list of files to check, using the
`all_pm_files()` function supplied:

    use strict;
    use Test::More;
    eval "use Test::Compile 0.09";
    Test::More->builder->BAIL_OUT(
        "Test::Compile 0.09 required for testing compilation") if $@;
    my @pmdirs = qw(blib script);
    all_pm_files_ok(all_pm_files(@pmdirs));

Or even (if you're running under [Apache::Test](http://search.cpan.org/perldoc?Apache::Test)):

    use strict;
    use Test::More;
    eval "use Test::Compile 0.09";
    Test::More->builder->BAIL_OUT(
        "Test::Compile 0.09 required for testing compilation") if $@;

    my @pmdirs = qw(blib script);
    use File::Spec::Functions qw(catdir updir);
    all_pm_files_ok(
        all_pm_files(map { catdir updir, $_ } @pmdirs)
    );

Why do the examples use `BAIL_OUT()` instead of `skip_all()`? Because
testing whether a module compiles is important. `skip_all()` is ok to use
with [Test::Pod](http://search.cpan.org/perldoc?Test::Pod), because if the pod is malformed the program is still going
to run. But checking whether a module even compiles is something else.
Test::Compile should be mandatory, not optional.

# FUNCTIONS

- `pm_file_ok(FILENAME[, TESTNAME ])`

`pm_file_ok()` will okay the test if the Perl module compiles correctly.

When it fails, `pm_file_ok()` will show any compilation errors as
diagnostics.

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 the Perl script compiles correctly. 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`.

When it fails, `pl_file_ok()` will show any compilation errors as
diagnostics.

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_ok([@files/@directories])`

Checks all the files in `@files` for compilation. It runs L<all_pm_files()>
on each file/directory, and calls the `plan()` function for you (one test for
each function), so you can't have already called `plan`.

If `@files` is empty or not passed, the function finds all Perl module files
in the `blib` directory if it exists, or the `lib` directory if not. A Perl
module file is one that ends with `.pm`.

If you're testing a module, just make a `t/00_compile.t`:

    use Test::More;
    eval "use Test::Compile 0.09";
    plan skip_all => "Test::Compile 0.09 required for testing compilation"
      if $@;
    all_pm_files_ok();

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

Or you could just let [Module::Install::StandardTests](http://search.cpan.org/perldoc?Module::Install::StandardTests) do all the work for
you.

- `all_pl_files_ok([@files])`

Checks all the files in `@files` for compilation. It runs L<pl_file_ok()>
on each file, and calls the `plan()` function for you (one test for
each file), so you can't have already called `plan`.

If `@files` is empty or not passed, the function uses all_pl_files() to find
scripts to test

If you're testing a module, just make a `t/00_compile_scripts.t`:

    use Test::More;
    eval "use Test::Compile 0.09";
    plan skip_all => "Test::Compile 0.09 required for testing compilation"
      if $@;
    all_pl_files_ok();

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

- `all_pm_files([@dirs])`

Returns a list of all the perl module files - that is, files ending in `.pm`
- in _$dir_ 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([@files/@dirs])`

Returns a list of all the perl script files - that is, files ending in `.pl`
or with no extension. Directory arguments are searched recursively . If
arguments are passed, it defaults to `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.

# BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through the web interface at
<http://rt.cpan.org>.

# INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

# AVAILABILITY

The latest version of this module is available from the Comprehensive Perl
Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a CPAN
site near you. Or see <http://search.cpan.org/dist/Test-Compile/>.

# AUTHORS

Sagar R. Shah `<srshah@cpan.org>`

Marcel Gr&uuml;nauer, `<marcel@cpan.org>`

# COPYRIGHT AND LICENSE

Copyright 2007-2009 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::LoadAllModules](http://search.cpan.org/perldoc?Test::LoadAllModules) just handles modules, not script files, but has more
fine-grained control.