tests/README

   1 The test suite was originally written by Steve McGee and Chris Arthur.
   2 It is covered by the GNU General Public License (Version 2), described
   3 in the file COPYING.  It has been maintained as part of GNU make proper
   4 since GNU make 3.78.
   5
   6 This entire test suite, including all test files, are copyright and
   7 distributed under the following terms:
   8
   9  -----------------------------------------------------------------------------
  10  Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
  11  2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2011, 2012 Free Software
  12  Foundation, Inc.
  13  This file is part of GNU Make.
  14
  15  GNU Make is free software; you can redistribute it and/or modify it under the
  16  terms of the GNU General Public License as published by the Free Software
  17  Foundation; either version 3 of the License, or (at your option) any later
  18  version.
  19
  20  GNU Make is distributed in the hope that it will be useful, but WITHOUT ANY
  21  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  22  A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  23
  24  You should have received a copy of the GNU General Public License along with
  25  this program.  If not, see <http://www.gnu.org/licenses/>.
  26  -----------------------------------------------------------------------------
  27
  28 The test suite requires Perl.  These days, you should have at least Perl
  29 5.004 (available from ftp.gnu.org, and portable to many machines).  It
  30 used to work with Perl 4.036 but official support for Perl 4.x was
  31 abandoned a long time ago, due to lack of testbeds, as well as interest.
  32
  33 The test suite assumes that the first "diff" it finds on your PATH is
  34 GNU diff, but that only matters if a test fails.
  35
  36 To run the test suite on a UNIX system, use "perl ./run_make_tests"
  37 (or just "./run_make_tests" if you have a perl on your PATH).
  38
  39 To run the test suite on Windows NT or DOS systems, use
  40 "perl.exe ./run_make-tests.pl".
  41
  42 By default, the test engine picks up the first executable called "make"
  43 that it finds in your path.  You may use the -make_path option (ie,
  44 "perl run_make_tests -make_path /usr/local/src/make-3.78/make") if
  45 you want to run a particular copy.  This now works correctly with
  46 relative paths and when make is called something other than "make" (like
  47 "gmake").
  48
  49 Tests cannot end with a "~" character, as the test suite will ignore any
  50 that do (I was tired of having it run my Emacs backup files as tests :))
  51
  52 Also, sometimes the tests may behave strangely on networked
  53 filesystems.  You can use mkshadow to create a copy of the test suite in
  54 /tmp or similar, and try again.  If the error disappears, it's an issue
  55 with your network or file server, not GNU make (I believe).  This
  56 shouldn't happen very often anymore: I've done a lot of work on the
  57 tests to reduce the impacts of this situation.
  58
  59 The options/dash-l test will not really test anything if the copy of
  60 make you are using can't obtain the system load.  Some systems require
  61 make to be setgid sys or kmem for this; if you don't want to install
  62 make just to test it, make it setgid to kmem or whatever group /dev/kmem
  63 is (ie, "chgrp kmem make;chmod g+s make" as root).  In any case, the
  64 options/dash-l test should no longer *fail* because make can't read
  65 /dev/kmem.
  66
  67 A directory named "work" will be created when the tests are run which
  68 will contain any makefiles and "diff" files of tests that fail so that
  69 you may look at them afterward to see the output of make and the
  70 expected result.
  71
  72 There is a -help option which will give you more information about the
  73 other possible options for the test suite.
  74
  75
  76 Open Issues
  77 -----------
  78
  79 The test suite has a number of problems which should be addressed.  One
  80 VERY serious one is that there is no real documentation.  You just have
  81 to see the existing tests.  Use the newer tests: many of the tests
  82 haven't been updated to use the latest/greatest test methods.  See the
  83 ChangeLog in the tests directory for pointers.
  84
  85 The second serious problem is that it's not parallelizable: it scribbles
  86 all over its installation directory and so can only test one make at a
  87 time.  The third serious problem is that it's not relocatable: the only
  88 way it works when you build out of the source tree is to create
  89 symlinks, which doesn't work on every system and is bogus to boot.  The
  90 fourth serious problem is that it doesn't create its own sandbox when
  91 running tests, so that if a test forgets to clean up after itself that
  92 can impact future tests.
  93
  94
  95 Bugs
  96 ----
  97
  98 Any complaints/suggestions/bugs/etc. for the test suite itself (as
  99 opposed to problems in make that the suite finds) should be handled the
 100 same way as normal GNU make bugs/problems (see the README for GNU make).
 101
 102
 103                                                 Paul D. Smith
 104                                                 Chris Arthur