This file was generated automatically from support.texi.
DO NOT CHANGE THIS FILE MANUALLY!

Note: This file is the `README' file of the `test' directory in the GPC
source distribution, _and_ the file `BUGS' in GPC binary distributions.

The GPC Test Suite
******************

Here you can find information on where to find the most up-to-date
information about GPC, how you can get support (professional or
voluntary), how to use GPC's Test Suite, and how to report new bugs you
might encounter.

If you have problems with GNU Pascal, please read the relevant sections
of the GPC Manual. The most current version of the manual is available
at `http://agnes.dida.physik.uni-essen.de/~gnu-pascal/gpc-doc.html' for
online browsing.  You can also download the complete manual in HTML
format (tar.gz) (`gpc-html.tar.gz' on GPC's WWW home page).  The manual
is also available in DVI format (gzipped) (`gpc.dvi.gz' on GPC's WWW
home page) and PostScript format (gzipped) (`gpc.ps.gz' on GPC's WWW
home page) for printing.

If the manual doesn't help you, here is what we recommend you to do:

The GPC FAQ
===========

Please see the file `FAQ'.

If the FAQ and the documentation do not help you, you have detected a
*bug* in it which should be reported, *Note Mailing List::.  Please
really do it, so we can improve the documentation.

The GPC Mailing List
====================

There is a mailing list devoted to GNU Pascal, <gpc@gnu.de>. Mails to
the list should be in English.  To subscribe, send the command
     subscribe gpc your@email.address
in the body of a mail to <majordomo@gnu.de>. The subject is ignored.
(Please replace `your@email.address' in the example above with your
real email address.) For more info, send a line `help' to
<majordomo@gnu.de>.

You can write to the mailing list, e.g., if you have problems
installing GPC or if you found a problem with GPC, please see *Note
Reporting Bugs::. You can also use it to discuss suggestions for
improving GPC and, most welcome, to offer your help or contribute code,
documentation or other work.

The GPC Mailing List Archives
=============================

Perhaps your problem was already discussed on the list. There is a
searchable archive of the mailing list on the WWW. It can be browsed at
`http://www.gnu.de/archive/wilma.cgi/gpc#browse'.

This archive starts in June 1999. For older messages, see:

     `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/misc/gpc-list-1998.gz'
     (513 kB)
     `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/misc/gpc-list-1997.gz'
     (995 kB)
     `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/misc/gpc-list-1996.gz'
     (154 kB)
     `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/misc/gpc-list-1995.gz'
     (42 kB)

There is also a HTML version of these older archives,
     `http://www.iula.upf.es/altres/pub/gpc/list2html/gpclist.htm'.

Newsgroups relevant to GPC
==========================

To get support, you can also ask the Usenet newsgroups for help.  There
is no specialized newsgroup for GNU Pascal, so use the one which is
most appropriate for your problem. When in doubt, we recommend
`news://comp.lang.pascal.misc'.

Don't forget to give back what you have obtained. None of us is getting
money for answering your questions (unless you pay us by yourself).
Please do your part by answering the questions of others, instead.

Where to get individual support for GPC
=======================================

GPC is free software and comes *without any warranty*.

If you want to get professional support, you can hire an individual or
a company for providing such a service.

G-N-U GmbH (http://www.g-n-u.de) is doing large parts of the
development of GNU Pascal. This company offers special support for GPC
and can be contacted at <info@g-n-u.de>.

More generally, to find a company or an individual who offers support
and other consulting services for free software, look into the GNU
Service Directory (http://www.gnu.org/prep/service.html).

How to report GPC bugs
======================

If you encounter a bug with GPC, please note the following points.

   * Please send a description of the problem, with the full text of any
     error messages encountered, or a description of how some output
     varies from the expected output. Always specify the operating
     system type with version and the machine type (try `uname -a' if
     unsure) as well as the version of GPC as printed by `gpc -v'.


If the problem is with the compiler itself, not an installation problem
or something like this, please provide a test program to reproduce the
problem, and note the following hints. You can also contribute test
programs for features that are working in GPC to ensure they will not
break in future releases.

   * The test program should be as short as possible, but *by all
     means*, please send a *complete* program and *make sure* that it
     still reproduces the problem before you send it. Too often, users
     have sent code which contained obvious syntax errors far before
     the actual problem, or just code fragments we could only make wild
     guesses about. This is unproductive for us and doesn't help you
     get your problem solved.


The preferred form for test programs is the form that the automated GPC
Test Suite understands. Please, if at all possible, send your test
programs in this form which should be easy to do, so we won't have to
waste our time to bring them into this form, and can concentrate on
fixing the problem.

   * The file containing the main program must contain the keyword
     `program' (case-insensitively) to be recognized by the testing
     script. Other files, which can contain units or modules or data
     needed by the program, must not contain the word `program'.

   * Since the Test Suite must run under very ... nah ... strange
     operating systems, too, file names must be distinguished in their
     first eight characters (case-insensitively) and should not contain
     anything but letters, numbers, hyphens, underscores and a single
     dot. The extension must be `.pas' to be recognized by the testing
     script. Furthermore, any ancillary files (units, modules,
     includes, data files) should not be longer than "8+3" characters.
     It is often a good idea to use your name, nickname or initials
     followed by a number as the file name.

   * The test program, when run, should produce a line of output
     consisting of the string `OK' (followed by a newline) if
     everything went as expected, and something else (e.g. `failed',
     possibly followed by the reason of failure) if something went
     wrong.

   * However, if the program is intended to check whether GPC catches an
     (intentional) error in the program, place the string `WRONG'
     somewhere in the test program, preferably in a comment in the line
     that contains the intentional error, and make the program output
     `failed' or something like this if it does compile mistakenly.


The following special features of the testing script may be helpful for
constructing tests:

   * If the expected output is something else than `OK', place it in a
     file `<basename>.out' (where `<basename>' is the name of the test
     program without the `.pas' extension).

   * If the test program expects some input, place it in a file
     `<basename>.in'. It will automatically be redirected to the
     program's standard input.

   * If the test needs some special flags to be given to the GPC command
     line, place them in a comment preceded by `FLAG', e.g.:

          (* FLAG --extended-pascal -Werror *)

   * The source file name of the test program will be passed as the
     first command-line argument to the test program run.

   * If a test needs to be run in a special way, you can accompany the
     program with a script `<basename>.run' that will do the actual
     test after the test program was compiled. In order to be portable,
     this script should run `/bin/sh' and only use standard tools.  The
     source file name of the test program will be passed as the first
     command-line argument to the run script in this case. The compiled
     file is always called `a.out'.

   * If a test needs to be compiled in a special way (e.g., to decide
     whether to skip the test), place the commands in a script
     (preferably called `<basename>.cmp'), and put the file name of the
     script (without directory) in a comment preceded by `COMPILE-CMD:'
     into the source of the test program. The compile script will be
     run *instead* of any other action for this test program, so it
     gives you maximum flexibility to do whatever you need to do. In
     order to be portable, this script should run `/bin/sh' and only
     use standard tools. The first command-line argument to the compile
     script will be the compiler to use, including all options. The
     second argument will be the source file name of the test program.
     For some typical tests, there are standard compile scripts, e.g.
     `i386.cmp' which will skip the test unless run on an i386
     compatible processor. This is necessary, e.g., when testing
     assembler code. Of course, it's still better to avoid having to
     use such scripts when possible.


Running the GPC Test Suite
==========================

_Note:_ If you have installed a GPC binary distribution, you usually
won't have the Test Suite installed (you can download the GPC source
distribution to get it, however), so this section does not apply to
you. Still, you can find in the section `Contributing Tests to the Test
Suite' how to report GPC bugs in the form of new test programs so we
can fix them as fast as possible.

The files in the test directory and subdirectories are for testing GPC
only and should not be of any other use.

Note: A few of the tests do not make sense on all systems. They are
equipped with checks and will be skipped if they find the system not
suitable. Skipped tests do *not* indicate a GPC bug, unless you have a
reason to be sure that the particular test should make sense on your
system.

   * To run the whole Test Suite, type `make' in the test directory (or
     `make check' in the `p' object directory after building GPC).

   * The output will show all errors encountered (hopefully none) and
     tests skipped, and finally display a summary giving the number of
     successful, failed and skipped tests. Any failed test indicates a
     bug in GPC which should be reported to the GPC mailing list,
     <gpc@gnu.de>. Don't forget to mention the operating system you ran
     the test on and any other relevant information about what you did.

   * You can also type `make pascal.check-long' to get a long output
     which is a sequence of file names followed by `OK' for successful
     tests, `SKIPPED' for skipped tests (both in capital letters), and
     anything else for failed tests.

   * To run only some of the tests, you can type something like `make
     MASK="foo[1-7]*.pas"' or `make MASK="foo42.pas" pascal.check-long'.

   * To clean up after running the tests, type `make clean'.


