tests/tap/perl/Test/RRA/Automake.pm

   1 # Helper functions for Perl test programs in Automake distributions.
   2 #
   3 # This module provides a collection of helper functions used by test programs
   4 # written in Perl and included in C source distributions that use Automake.
   5 # They embed knowledge of how I lay out my source trees and test suites with
   6 # Autoconf and Automake.  They may be usable by others, but doing so will
   7 # require closely following the conventions implemented by the rra-c-util
   8 # utility collection.
   9 #
  10 # All the functions here assume that BUILD and SOURCE are set in the
  11 # environment.  This is normally done via the C TAP Harness runtests wrapper.
  12 #
  13 # The canonical version of this file is maintained in the rra-c-util package,
  14 # which can be found at <http://www.eyrie.org/~eagle/software/rra-c-util/>.
  15 #
  16 # Written by Russ Allbery <eagle@eyrie.org>
  17 # Copyright 2013
  18 #     The Board of Trustees of the Leland Stanford Junior University
  19 #
  20 # Permission is hereby granted, free of charge, to any person obtaining a
  21 # copy of this software and associated documentation files (the "Software"),
  22 # to deal in the Software without restriction, including without limitation
  23 # the rights to use, copy, modify, merge, publish, distribute, sublicense,
  24 # and/or sell copies of the Software, and to permit persons to whom the
  25 # Software is furnished to do so, subject to the following conditions:
  26 #
  27 # The above copyright notice and this permission notice shall be included in
  28 # all copies or substantial portions of the Software.
  29 #
  30 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  31 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  32 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  33 # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  34 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  35 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  36 # DEALINGS IN THE SOFTWARE.
  37
  38 package Test::RRA::Automake;
  39
  40 use 5.006;
  41 use strict;
  42 use warnings;
  43
  44 # For Perl 5.006 compatibility.
  45 ## no critic (ClassHierarchies::ProhibitExplicitISA)
  46
  47 use Exporter;
  48 use File::Spec;
  49 use Test::More;
  50 use Test::RRA::Config qw($LIBRARY_PATH);
  51
  52 # Used below for use lib calls.
  53 my ($PERL_BLIB_ARCH, $PERL_BLIB_LIB);
  54
  55 # Determine the path to the build tree of any embedded Perl module package in
  56 # this source package.  We do this in a BEGIN block because we're going to use
  57 # the results in a use lib command below.
  58 BEGIN {
  59     $PERL_BLIB_ARCH = File::Spec->catdir(qw(perl blib arch));
  60     $PERL_BLIB_LIB  = File::Spec->catdir(qw(perl blib lib));
  61
  62     # If BUILD is set, we can come up with better values.
  63     if (defined($ENV{BUILD})) {
  64         my ($vol, $dirs) = File::Spec->splitpath($ENV{BUILD}, 1);
  65         my @dirs = File::Spec->splitdir($dirs);
  66         pop(@dirs);
  67         $PERL_BLIB_ARCH = File::Spec->catdir(@dirs, qw(perl blib arch));
  68         $PERL_BLIB_LIB  = File::Spec->catdir(@dirs, qw(perl blib lib));
  69     }
  70 }
  71
  72 # Prefer the modules built as part of our source package.  Otherwise, we may
  73 # not find Perl modules while testing, or find the wrong versions.
  74 use lib $PERL_BLIB_ARCH;
  75 use lib $PERL_BLIB_LIB;
  76
  77 # Declare variables that should be set in BEGIN for robustness.
  78 our (@EXPORT_OK, @ISA, $VERSION);
  79
  80 # Set $VERSION and everything export-related in a BEGIN block for robustness
  81 # against circular module loading (not that we load any modules, but
  82 # consistency is good).
  83 BEGIN {
  84     @ISA       = qw(Exporter);
  85     @EXPORT_OK = qw(automake_setup perl_dirs test_file_path);
  86
  87     # This version should match the corresponding rra-c-util release, but with
  88     # two digits for the minor version, including a leading zero if necessary,
  89     # so that it will sort properly.
  90     $VERSION = '4.09';
  91 }
  92
  93 # Perl directories to skip globally for perl_dirs.  We ignore the perl
  94 # directory if it exists since, in my packages, it is treated as a Perl module
  95 # distribution and has its own standalone test suite.
  96 my @GLOBAL_SKIP = qw(.git perl);
  97
  98 # Perform initial test setup for running a Perl test in an Automake package.
  99 # This verifies that BUILD and SOURCE are set and then changes directory to
 100 # the SOURCE directory by default.  Sets LD_LIBRARY_PATH if the $LIBRARY_PATH
 101 # configuration option is set.  Calls BAIL_OUT if BUILD or SOURCE are missing
 102 # or if anything else fails.
 103 #
 104 # $args_ref - Reference to a hash of arguments to configure behavior:
 105 #   chdir_build - If set to a true value, changes to BUILD instead of SOURCE
 106 #
 107 # Returns: undef
 108 sub automake_setup {
 109     my ($args_ref) = @_;
 110
 111     # Bail if BUILD or SOURCE are not set.
 112     if (!$ENV{BUILD}) {
 113         BAIL_OUT('BUILD not defined (run under runtests)');
 114     }
 115     if (!$ENV{SOURCE}) {
 116         BAIL_OUT('SOURCE not defined (run under runtests)');
 117     }
 118
 119     # BUILD or SOURCE will be the test directory.  Change to the parent.
 120     my $start = $args_ref->{chdir_build} ? $ENV{BUILD} : $ENV{SOURCE};
 121     my ($vol, $dirs) = File::Spec->splitpath($start, 1);
 122     my @dirs = File::Spec->splitdir($dirs);
 123     pop(@dirs);
 124     if ($dirs[-1] eq File::Spec->updir) {
 125         pop(@dirs);
 126         pop(@dirs);
 127     }
 128     my $root = File::Spec->catpath($vol, File::Spec->catdir(@dirs), q{});
 129     chdir($root) or BAIL_OUT("cannot chdir to $root: $!");
 130
 131     # If BUILD is a subdirectory of SOURCE, add it to the global ignore list.
 132     my ($buildvol, $builddirs) = File::Spec->splitpath($ENV{BUILD}, 1);
 133     my @builddirs = File::Spec->splitdir($builddirs);
 134     pop(@builddirs);
 135     if ($buildvol eq $vol && @builddirs == @dirs + 1) {
 136         while (@dirs && $builddirs[0] eq $dirs[0]) {
 137             shift(@builddirs);
 138             shift(@dirs);
 139         }
 140         if (@builddirs == 1) {
 141             push(@GLOBAL_SKIP, $builddirs[0]);
 142         }
 143     }
 144
 145     # Set LD_LIBRARY_PATH if the $LIBRARY_PATH configuration option is set.
 146     ## no critic (Variables::RequireLocalizedPunctuationVars)
 147     if (defined($LIBRARY_PATH)) {
 148         @builddirs = File::Spec->splitdir($builddirs);
 149         pop(@builddirs);
 150         my $libdir = File::Spec->catdir(@builddirs, $LIBRARY_PATH);
 151         my $path = File::Spec->catpath($buildvol, $libdir, q{});
 152         if (-d "$path/.libs") {
 153             $path .= '/.libs';
 154         }
 155         if ($ENV{LD_LIBRARY_PATH}) {
 156             $ENV{LD_LIBRARY_PATH} .= ":$path";
 157         } else {
 158             $ENV{LD_LIBRARY_PATH} = $path;
 159         }
 160     }
 161     return;
 162 }
 163
 164 # Returns a list of directories that may contain Perl scripts and that should
 165 # be passed to Perl test infrastructure that expects a list of directories to
 166 # recursively check.  The list will be all eligible top-level directories in
 167 # the package except for the tests directory, which is broken out to one
 168 # additional level.  Calls BAIL_OUT on any problems
 169 #
 170 # $args_ref - Reference to a hash of arguments to configure behavior:
 171 #   skip - A reference to an array of directories to skip
 172 #
 173 # Returns: List of directories possibly containing Perl scripts to test
 174 sub perl_dirs {
 175     my ($args_ref) = @_;
 176
 177     # Add the global skip list.
 178     my @skip = $args_ref->{skip} ? @{ $args_ref->{skip} } : ();
 179     push(@skip, @GLOBAL_SKIP);
 180
 181     # Separate directories to skip under tests from top-level directories.
 182     my @skip_tests = grep { m{ \A tests/ }xms } @skip;
 183     @skip = grep { !m{ \A tests }xms } @skip;
 184     for my $skip_dir (@skip_tests) {
 185         $skip_dir =~ s{ \A tests/ }{}xms;
 186     }
 187
 188     # Convert the skip lists into hashes for convenience.
 189     my %skip = map { $_ => 1 } @skip, 'tests';
 190     my %skip_tests = map { $_ => 1 } @skip_tests;
 191
 192     # Build the list of top-level directories to test.
 193     opendir(my $rootdir, q{.}) or BAIL_OUT("cannot open .: $!");
 194     my @dirs = grep { -d $_ && !$skip{$_} } readdir($rootdir);
 195     closedir($rootdir);
 196     @dirs = File::Spec->no_upwards(@dirs);
 197
 198     # Add the list of subdirectories of the tests directory.
 199     if (-d 'tests') {
 200         opendir(my $testsdir, q{tests}) or BAIL_OUT("cannot open tests: $!");
 201
 202         # Skip if found in %skip_tests or if not a directory.
 203         my $is_skipped = sub {
 204             my ($dir) = @_;
 205             return 1 if $skip_tests{$dir};
 206             $dir = File::Spec->catdir('tests', $dir);
 207             return -d $dir ? 0 : 1;
 208         };
 209
 210         # Build the filtered list of subdirectories of tests.
 211         my @test_dirs = grep { !$is_skipped->($_) } readdir($testsdir);
 212         closedir($testsdir);
 213         @test_dirs = File::Spec->no_upwards(@test_dirs);
 214
 215         # Add the tests directory to the start of the directory name.
 216         push(@dirs, map { File::Spec->catdir('tests', $_) } @test_dirs);
 217     }
 218     return @dirs;
 219 }
 220
 221 # Find a configuration file for the test suite.  Searches relative to BUILD
 222 # first and then SOURCE and returns whichever is found first.  Calls BAIL_OUT
 223 # if the file could not be found.
 224 #
 225 # $file - Partial path to the file
 226 #
 227 # Returns: Full path to the file
 228 sub test_file_path {
 229     my ($file) = @_;
 230   BASE:
 231     for my $base ($ENV{BUILD}, $ENV{SOURCE}) {
 232         next if !defined($base);
 233         if (-f "$base/$file") {
 234             return "$base/$file";
 235         }
 236     }
 237     BAIL_OUT("cannot find $file");
 238     return;
 239 }
 240
 241 1;
 242 __END__
 243
 244 =for stopwords
 245 Allbery Automake Automake-aware Automake-based rra-c-util ARGS
 246 subdirectories sublicense MERCHANTABILITY NONINFRINGEMENT
 247
 248 =head1 NAME
 249
 250 Test::RRA::Automake - Automake-aware support functions for Perl tests
 251
 252 =head1 SYNOPSIS
 253
 254     use Test::RRA::Automake qw(automake_setup perl_dirs test_file_path);
 255     automake_setup({ chdir_build => 1 });
 256
 257     # Paths to directories that may contain Perl scripts.
 258     my @dirs = perl_dirs({ skip => [qw(lib)] });
 259
 260     # Configuration for Kerberos tests.
 261     my $keytab = test_file_path('config/keytab');
 262
 263 =head1 DESCRIPTION
 264
 265 This module collects utility functions that are useful for test scripts
 266 written in Perl and included in a C Automake-based package.  They assume
 267 the layout of a package that uses rra-c-util and C TAP Harness for the
 268 test structure.
 269
 270 Loading this module will also add the directories C<perl/blib/arch> and
 271 C<perl/blib/lib> to the Perl library search path, relative to BUILD if
 272 that environment variable is set.  This is harmless for C Automake
 273 projects that don't contain an embedded Perl module, and for those
 274 projects that do, this will allow subsequent C<use> calls to find modules
 275 that are built as part of the package build process.
 276
 277 The automake_setup() function should be called before calling any other
 278 functions provided by this module.
 279
 280 =head1 FUNCTIONS
 281
 282 None of these functions are imported by default.  The ones used by a
 283 script should be explicitly imported.  On failure, all of these functions
 284 call BAIL_OUT (from Test::More).
 285
 286 =over 4
 287
 288 =item automake_setup([ARGS])
 289
 290 Verifies that the BUILD and SOURCE environment variables are set and
 291 then changes directory to the top of the source tree (which is one
 292 directory up from the SOURCE path, since SOURCE points to the top of
 293 the tests directory).
 294
 295 If ARGS is given, it should be a reference to a hash of configuration
 296 options.  Only one option is supported: C<chdir_build>.  If it is set
 297 to a true value, automake_setup() changes directories to the top of
 298 the build tree instead.
 299
 300 =item perl_dirs([ARGS])
 301
 302 Returns a list of directories that may contain Perl scripts that should be
 303 tested by test scripts that test all Perl in the source tree (such as
 304 syntax or coding style checks).  The paths will be simple directory names
 305 relative to the current directory or two-part directory names under the
 306 F<tests> directory.  (Directories under F<tests> are broken out separately
 307 since it's common to want to apply different policies to different
 308 subdirectories of F<tests>.)
 309
 310 If ARGS is given, it should be a reference to a hash of configuration
 311 options.  Only one option is supported: C<skip>, whose value should be a
 312 reference to an array of additional top-level directories or directories
 313 starting with C<tests/> that should be skipped.
 314
 315 =item test_file_path(FILE)
 316
 317 Given FILE, which should be a relative path, locates that file relative to
 318 the test directory in either the source or build tree.  FILE will be
 319 checked for relative to the environment variable BUILD first, and then
 320 relative to SOURCE.  test_file_path() returns the full path to FILE or
 321 calls BAIL_OUT if FILE could not be found.
 322
 323 =back
 324
 325 =head1 AUTHOR
 326
 327 Russ Allbery <eagle@eyrie.org>
 328
 329 =head1 COPYRIGHT AND LICENSE
 330
 331 Copyright 2013 The Board of Trustees of the Leland Stanford Junior
 332 University
 333
 334 Permission is hereby granted, free of charge, to any person obtaining a
 335 copy of this software and associated documentation files (the "Software"),
 336 to deal in the Software without restriction, including without limitation
 337 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 338 and/or sell copies of the Software, and to permit persons to whom the
 339 Software is furnished to do so, subject to the following conditions:
 340
 341 The above copyright notice and this permission notice shall be included in
 342 all copies or substantial portions of the Software.
 343
 344 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 345 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 346 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 347 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 348 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 349 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 350 DEALINGS IN THE SOFTWARE.
 351
 352 =head1 SEE ALSO
 353
 354 Test::More(3), Test::RRA(3), Test::RRA::Config(3)
 355
 356 The C TAP Harness test driver and libraries for TAP-based C testing are
 357 available from L<http://www.eyrie.org/~eagle/software/c-tap-harness/>.
 358
 359 This module is maintained in the rra-c-util package.  The current version
 360 is available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>.
 361
 362 =cut