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:

   * Check the GPC FAQ (see the file `FAQ' or the GPC Manual)

   * Join the GPC Mailing List

   * Look in the Mailing List Archives

   * Ask in a newsgroup

   * Get individual support for GPC

   * Find out how to report GPC bugs

   * If you have GPC sources, learn how to run the Test Suite to test
     your bugs reported

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

There is a mailing list devoted to GNU Pascal. 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. Mails
to the list should be in English.

To subscribe to the mailing list, send the command
     subscribe gpc your@email.address
in the body of a mail to <majordomo@gnu.de> (*not* to `gpc@gnu.de'!).
The subject is ignored. (Please replace `your@email.address' with your
real email address.) For more info, send a line `help' to
<majordomo@gnu.de>.

You can send a message to the mailing list by sending email to the list
address <gpc@gnu.de> as if it were a person.

To leave the mailing list, send the command
     unsubscribe gpc your@email.address
to <majordomo@gnu.de>.

There is also a (low-traffic) announce list, <gpc-announce@gnu.de> that
you can subscribe to stay up-to-date. To subscribe to the list, write
an email with
     subscribe gpc-announce your@email.address
in the body to <majordomo@gnu.de>. If you like to announce a
contribution, a service or an event related to GPC, you are invited to
post to this list rather than `gpc@gnu.de', but please don't use the
announce list for questions or discussions. Please note that all mail
sent to the announce list is forwarded to the regular list, so you
won't have to subscribe to both lists if you don't want to miss
anything.

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 or
searched at `http://www.gnu.de/archive/wilma.cgi/gpc'.

The archive of the GPC announcement list is at
`http://www.gnu.de/archive/wilma.cgi/gpc-announce'.

_Note:_ Currently, the search option is working fine. If you find it
broken, please email me at <anja@drewitz.de>. Please don't mail a copy
to the GPC list because I let procmail move all mails with `To: gpc...'
and `Cc: gpc...' to a separate folder and would not see your mail for a
long time. -- Anja

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 at
`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
are several Pascal related newsgroups, but none is dedicated just to
GNU Pascal, so use the one which is most appropriate for your problem.
For general Pascal questions, we recommend the following one:

`news://comp.lang.pascal.misc'       Pascal in general and ungrouped
                                     Pascals.

Pascal syntax related questions may be appropriate in:

`news://comp.lang.pascal.ansi-iso'   Pascal according to ANSI and ISO
                                     standards.

The next newsgroup is a haven for beginners, answering questions that
would apply to almost any Pascal. However, if you have a GPC-specific
question don't post there - use the GPC mailing list.  And when in
doubt use the GPC mailing list.

`news://comp.lang.pascal.borland'    Borland Pascal questions.

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).

If the compiler crashes...
==========================

If the compiler crashes, you have discovered a bug. A reliable compiler
never crashes. To help the maintainers fix this bug, it is important
that you send us a problem report.

If you're on Unix, you can find out where the compiler crashed if you
enable coredumps, then load the compiler (`gpc1') plus the core file in
the debugger (`gdb /your_path_here/gpc1 core'), then type `backtrace'
to get a stacktrace. Include this stacktrace in your bug report.

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

If you encounter a bug with GPC, please check whether it is one of the
known bugs. If not, please report it to the GNU Pascal mailing list.
That way, they always reach the maintainers. Please note the following
points.

   * Please send a description of the problem. Try to give as much
     information as possible, 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'.

   * A good article on submitting bug reports can be found at either
     `http://www.chiark.greenend.org.uk/~sgtatham/bugs.html' or
     `http://freshmeat.net/news/2000/02/26/951627540.html'


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. This script will be run
     by `sh' (regardless of its first line). In order to be portable,
     it should 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. This
     script will be run by `sh' (regardless of its first line). In
     order to be portable, it should 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
don'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'.


