Update podlators to version 4.03
[perl.git] / cpan / podlators / t / lib / Test / RRA / Config.pm
1 # Configuration for Perl test cases.
2 #
3 # In order to reuse the same Perl test cases in multiple packages, I use a
4 # configuration file to store some package-specific data.  This module loads
5 # that configuration and provides the namespace for the configuration
6 # settings.
7
8 package Test::RRA::Config;
9
10 use 5.006;
11 use strict;
12 use warnings;
13
14 # For Perl 5.006 compatibility.
15 ## no critic (ClassHierarchies::ProhibitExplicitISA)
16
17 use Exporter;
18 use Test::More;
19
20 # Declare variables that should be set in BEGIN for robustness.
21 our (@EXPORT_OK, @ISA, $VERSION);
22
23 # Set $VERSION and everything export-related in a BEGIN block for robustness
24 # against circular module loading (not that we load any modules, but
25 # consistency is good).
26 BEGIN {
27     @ISA       = qw(Exporter);
28     @EXPORT_OK = qw(
29       $COVERAGE_LEVEL @COVERAGE_SKIP_TESTS @CRITIC_IGNORE $LIBRARY_PATH
30       $MINIMUM_VERSION %MINIMUM_VERSION @POD_COVERAGE_EXCLUDE @STRICT_IGNORE
31       @STRICT_PREREQ
32     );
33
34     # This version should match the corresponding rra-c-util release, but with
35     # two digits for the minor version, including a leading zero if necessary,
36     # so that it will sort properly.
37     $VERSION = '5.09';
38 }
39
40 # If BUILD or SOURCE are set in the environment, look for data/perl.conf under
41 # those paths for a C Automake package.  Otherwise, look in t/data/perl.conf
42 # for a standalone Perl module.  Don't use Test::RRA::Automake since it may
43 # not exist.
44 our $PATH;
45 for my $base ($ENV{BUILD}, $ENV{SOURCE}, 't') {
46     next if !defined($base);
47     my $path = "$base/data/perl.conf";
48     if (-r $path) {
49         $PATH = $path;
50         last;
51     }
52 }
53 if (!defined($PATH)) {
54     BAIL_OUT('cannot find data/perl.conf');
55 }
56
57 # Pre-declare all of our variables and set any defaults.
58 our $COVERAGE_LEVEL = 100;
59 our @COVERAGE_SKIP_TESTS;
60 our @CRITIC_IGNORE;
61 our $LIBRARY_PATH;
62 our $MINIMUM_VERSION = '5.008';
63 our %MINIMUM_VERSION;
64 our @POD_COVERAGE_EXCLUDE;
65 our @STRICT_IGNORE;
66 our @STRICT_PREREQ;
67
68 # Load the configuration.
69 if (!do($PATH)) {
70     my $error = $@ || $! || 'loading file did not return true';
71     BAIL_OUT("cannot load data/perl.conf: $error");
72 }
73
74 1;
75 __END__
76
77 =for stopwords
78 Allbery rra-c-util Automake perlcritic .libs namespace subdirectory
79 sublicense MERCHANTABILITY NONINFRINGEMENT
80
81 =head1 NAME
82
83 Test::RRA::Config - Perl test configuration
84
85 =head1 SYNOPSIS
86
87     use Test::RRA::Config qw($MINIMUM_VERSION);
88     print "Required Perl version is $MINIMUM_VERSION\n";
89
90 =head1 DESCRIPTION
91
92 Test::RRA::Config encapsulates per-package configuration for generic Perl
93 test programs that are shared between multiple packages using the
94 rra-c-util infrastructure.  It handles locating and loading the test
95 configuration file for both C Automake packages and stand-alone Perl
96 modules.
97
98 Test::RRA::Config looks for a file named F<data/perl.conf> relative to the
99 root of the test directory.  That root is taken from the environment
100 variables BUILD or SOURCE (in that order) if set, which will be the case
101 for C Automake packages using C TAP Harness.  If neither is set, it
102 expects the root of the test directory to be a directory named F<t>
103 relative to the current directory, which will be the case for stand-alone
104 Perl modules.
105
106 The following variables are supported:
107
108 =over 4
109
110 =item $COVERAGE_LEVEL
111
112 The coverage level achieved by the test suite for Perl test coverage
113 testing using Test::Strict, as a percentage.  The test will fail if test
114 coverage less than this percentage is achieved.  If not given, defaults
115 to 100.
116
117 =item @COVERAGE_SKIP_TESTS
118
119 Directories under F<t> whose tests should be skipped when doing coverage
120 testing.  This can be tests that won't contribute to coverage or tests
121 that don't run properly under Devel::Cover for some reason (such as ones
122 that use taint checking).  F<docs> and F<style> will always be skipped
123 regardless of this setting.
124
125 =item @CRITIC_IGNORE
126
127 Additional directories to ignore when doing recursive perlcritic testing.
128 The contents of this directory must be either top-level directory names or
129 directory names starting with F<tests/>.
130
131 =item $LIBRARY_PATH
132
133 Add this directory (or a F<.libs> subdirectory) relative to the top of the
134 source tree to LD_LIBRARY_PATH when checking the syntax of Perl modules.
135 This may be required to pick up libraries that are used by in-tree Perl
136 modules so that Perl scripts can pass a syntax check.
137
138 =item $MINIMUM_VERSION
139
140 Default minimum version requirement for included Perl scripts.  If not
141 given, defaults to 5.008.
142
143 =item %MINIMUM_VERSION
144
145 Minimum version exceptions for specific directories.  The keys should be
146 minimum versions of Perl to enforce.  The value for each key should be a
147 reference to an array of either top-level directory names or directory
148 names starting with F<tests/>.  All files in those directories will have
149 that minimum Perl version constraint imposed instead of $MINIMUM_VERSION.
150
151 =item @POD_COVERAGE_EXCLUDE
152
153 Regexes that match method names that should be excluded from POD coverage
154 testing.  Normally, all methods have to be documented in the POD for a
155 Perl module, but methods matching any of these regexes will be considered
156 private and won't require documentation.
157
158 =item @STRICT_IGNORE
159
160 Additional directories to ignore when doing recursive Test::Strict testing
161 for C<use strict> and C<use warnings>.  The contents of this directory
162 must be either top-level directory names or directory names starting with
163 F<tests/>.
164
165 =item @STRICT_PREREQ
166
167 A list of Perl modules that have to be available in order to do meaningful
168 Test::Strict testing.  If any of the modules cannot be loaded via C<use>,
169 Test::Strict checking will be skipped.  There is currently no way to
170 require specific versions of the modules.
171
172 =back
173
174 No variables are exported by default, but the variables can be imported
175 into the local namespace to avoid long variable names.
176
177 =head1 AUTHOR
178
179 Russ Allbery <eagle@eyrie.org>
180
181 =head1 COPYRIGHT AND LICENSE
182
183 Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior
184 University
185
186 Permission is hereby granted, free of charge, to any person obtaining a
187 copy of this software and associated documentation files (the "Software"),
188 to deal in the Software without restriction, including without limitation
189 the rights to use, copy, modify, merge, publish, distribute, sublicense,
190 and/or sell copies of the Software, and to permit persons to whom the
191 Software is furnished to do so, subject to the following conditions:
192
193 The above copyright notice and this permission notice shall be included in
194 all copies or substantial portions of the Software.
195
196 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
197 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
198 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
199 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
200 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
201 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
202 DEALINGS IN THE SOFTWARE.
203
204 =head1 SEE ALSO
205
206 perlcritic(1), Test::MinimumVersion(3), Test::RRA(3),
207 Test::RRA::Automake(3), Test::Strict(3)
208
209 This module is maintained in the rra-c-util package.  The current version
210 is available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>.
211
212 The C TAP Harness test driver and libraries for TAP-based C testing are
213 available from L<http://www.eyrie.org/~eagle/software/c-tap-harness/>.
214
215 =cut