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