Any support organization realizes that a large amount of data flows back and forth between the maintainers and the users of their products. This data often takes the form of problem reports and communication via electronic mail. GNATS addresses the problem of organizing this communication by defining a database made up of archived and indexed electronic mail messages.
GNATS was designed as a tool for software maintainers. It consists of several utilities which, when used in concert, formulate and administer a database of Problem Reports grouped by site-defined problem categories. It allows a support organization to keep track of problems (hence the term Problem Report) in an organized fashion. Essentially, GNATS acts as an active archive for field-separated textual data submitted through electronic mail.
It is in your best interest as the maintainer of a body of work to organize the feedback you receive on that work, and to make it easy for users of your work to report problems and suggestions.
GNATS makes this easy by automatically filing incoming problem reports into appropriate places, by notifying responsible parties of the existence of the problem and (optionally) sending an acknowledgement to the submitter that the report was received, and by making these Problem Reports accessible to queries and easily editable. GNATS is a database specialized for a specific task.
GNATS was designed for use at a Support Site that handles a high level of problem-related traffic though electronic mail. It maintains Problem Reports in the form of text files with defined fields (see section Problem Report format). The location of the database, as well as the categories it accepts as valid, the maintainers for whom it provides service, and the submitters from whom it accepts Problem Reports, are all definable by the Support Site. See section GNATS Administration.
Each PR is a separate file within a main repository
(see section Where GNATS lives). Editing access to the
database is regulated to maintain consistency, but anyone with
electronic mail access may submit Problem Reports. To make queries on
the database faster, an index is kept automatically (see section The index file).
We provide several software tools so that users may submit new Problem Reports, edit existing Problem Reports, and query the database.
send-pr is used by both product maintainers and the end users
of the products they support to submit PRs to the database.
edit-pr is used by maintainers to use when editing problem
reports in the database.
query-pr to
make inquiries about indidvidual PRs or groups of PRs.
send-pr can also be packaged by itself and distributed to anyone
you wish to receive Problem Reports from; see section Configuring send-pr for the outside world.
At the Support Site, a GNATS administrator is charged with the
duty of maintaining GNATS. These duties are discussed in detail in
section GNATS Administration, and generally include
configuring GNATS for the Support Site, editing PRs that GNATS
cannot process, pruning log files, setting up new problem categories,
backing up the database, and distributing send-pr so that others
may submit Problem Reports.
Responsibility for a given Problem Report depends on the category of the problem. Optionally, an automated reminder can be sent to the responsible person if a problem report is neglected for a requisite time period. See section Changing your local configuration.
GNATS does not have the ability to decipher random text, so any problem reports which arrive in a format GNATS does not recognize are placed in a separate directory pending investigation by the GNATS administrator (see section GNATS Administration).
Once a problem is recorded in the database, work can begin toward a solution. A problem's initial state is `open' (see section States of Problem Reports). An acknowledgement is sent to the originator of the bug report (if that feature of GNATS is activated). GNATS forwards copies of the report to the party responsible for that problem category and to the person responsible for problems arriving from that Submitter Site.
When a problem has been identified, the maintainer can change its state to `analyzed', and then to `feedback' when a solution is found. Each time the state of a PR changes, the submitter of the problem report is notified of the reason for the change. If the party responsible for the PR changes, the previous responsible party and the new responsible party receive notice of the change. The change and reason are also recorded in the `>Audit-Trail:' field of the Problem Report. (See section Editing existing Problem Reports. For information on the `>Audit-Trail:' field, see section Problem Report format.)
When the originator of the Problem Report confirms that the solution works, the maintainer can change the state to closed. If the PR cannot be closed, the maintainer can change its state to suspended as a last resort. (For a more detailed description of these states, see section States of Problem Reports.)
This informal flowchart shows the relationships of the GNATS tools to each other and to the files with which they interoperate.
Each PR goes through a defined series of states between origination and closure. The originator of a PR receives notification automatically of any state changes.
The format of a PR is designed to reflect the nature of GNATS as a database. Information is arranged into fields, and kept in individual records (Problem Reports).
Problem Report fields are denoted by a keyword which begins with `>' and ends with `:', as in `>Confidential:'. Fields belong to one of three data types:
>Confidential: >Severity: >Priority: >Class: >State: >Number:
>Submitter-Id: >Originator: >Synopsis: >Category: >Release: >Responsible: >Arrival-Date:
>Organization: >Environment: >Description: >How-To-Repeat: >Fix: >Audit-Trail: >Unformatted:
A Problem Report contains two different types of fields: Mail Header fields, which are used by the mail handler for delivery, and Problem Report fields, which contain information relevant to the Problem Report and its submitter. A Problem Report is essentially a specially formatted electronic mail message.
The following is an example Problem Report. Mail headers are at the top, followed by GNATS fields, which begin with `>' and end with `:'. The `Subject:' line in the mail header and the `>Synopsis:' field are usually duplicates of each other.
Message-Id: message-id Date: date From: address Reply-To: address To: bug-address Subject: subject >Number: gnats-id >Category: category >Synopsis: synopsis >Confidential: yes or no >Severity: critical, serious, or non-critical >Priority: high, medium or low >Responsible: responsible >State: open, analyzed, suspended, feedback, or closed >Class: sw-bug, doc-bug, change-request, support, duplicate, or mistaken >Submitter-Id: submitter-id >Arrival-Date: date >Originator: name >Organization: organization >Release: release >Environment: environment >Description: description >How-To-Repeat: how-to-repeat >Fix: fix >Audit-Trail: appended-messages... State-Changed-From-To: from-to State-Changed-When: date State-Changed-Why: reason Responsible-Changed-From-To: from-to Responsible-Changed-When: date Responsible-Changed-Why: reason >Unformatted: miscellaneous
A Problem Report may contain any mail header field described in the
Internet standard RFC-822. However, only the fields which identify the
sender and the subject are required by send-pr:
To:
send-pr.
Subject:
From:
Reply-To:
From: field.
One of the configurable options for GNATS is whether or not to retain `Received-By:' headers, which often consume a lot of space and are not often used. See section Changing your local configuration.
The following fields are present whenever a PR is submitted via the
program send-pr. GNATS adds additional fields when the PR
arrives at the Support Site; explanations of these follow this list.
>Submitter-Id:
send-pr with the `--request-id' option to apply for one from
the support organization. Problem Reports from those not affiliated
with the support organization should use the default value of `net'
for this field.)
>Originator:
NAME.
>Organization:
DEFAULT_ORGANIZATION in the
`config' file (see section The config file).
>Confidential:
>Synopsis:
send-pr copies
this information to the `Subject:' line when you submit a Problem
Report.
>Severity:
critical
serious
non-critical
>Priority:
high
medium
low
>Category:
categories file, for details.
>Class:
sw-bug
doc-bug
change-request
support
duplicate (pr-number)
mistaken
>Release:
>Environment:
>Description:
>How-To-Repeat:
>Fix:
GNATS adds the following fields when the PR arrives at the Support Site:
>Number:
category/numberin subsequent email messages. This is for historical reasons, as well as because Problem Reports are stored in subdirectories which are named by category.
>State:
open
analyzed
feedback
closed
suspended
>Responsible:
categories file).
>Arrival-Date:
>Audit-Trail:
State-Changed-<From>-<To>: oldstate>-<newstate
Responsible-Changed-<From>-<To>: oldresp>-<newresp
State-Changed-By: name
Responsible-Changed-By: name
State-Changed-When: timestamp
Responsible-Changed-When: timestamp
State-Changed-Why: reason...
Responsible-Changed-Why: reason...
>Unformatted:
The following programs comprise GNATS:
These tools are used by the maintainers of a body of work
(send-pr is also used by the end users of the product).
send-pr
query-pr
edit-pr
view-pr
These tools are used by the GNATS administrator; see also section GNATS Administration. For complete explanations of these utilities, see section Administrative utilities.
mkcat
rmcat
gen-index
query-pr and
edit-pr (see section The index file). Use
gen-index to rebuild the index if it becomes corrupted, or if you
need a copy of the current index for some reason
(see section Regenerating the index).
mkdist
send-pr for offsite
submitters of PRs (see section Configuring send-pr for the outside world).
These tools are used internally by GNATS. You should not need to run these by hand. For complete explanations of these utilities, see section Internal utilities.
queue-pr
file-pr
at-pr
pr-edit
edit-pr to error-check and submit edited Problem Reports
(also see section Editing existing Problem Reports).
pr-addr
edit-pr script to retrieve correct addresses from the
`responsible' file.
See section Where GNATS lives.
Use send-pr to submit Problem Reports to the database.
send-pr is both a shell script and a Lisp program for GNU
Emacs; both implementations provide a template for submitters to
complete. In most cases, send-pr can determine intelligent
default values for several fields, partially automating the
bug-reporting process.
See section Configuring send-pr for the outside world, for
information on distributing a version of send-pr customized with
your site's configuration.
@lowersections
You can invoke send-pr from a shell prompt or from within
GNU Emacs using `M-x send-pr'.
Invoking send-pr presents a PR template with a number of
fields already filled in. Complete the template as thoroughly as
possible to make a useful bug report. Submit only one bug with each PR.
A template consists of three sections:
send-pr creates a standard mail header. send-pr completes
all fields except the `Subject:' line with default values.
(See section Problem Report format.)
The default template contains your preconfigured `>Submitter-Id:'.
send-pr attempts to determine values for the `>Originator:'
and `>Organization:' fields (see section Problem Report format). send-pr also attempts to find out some information
about your system and architecture, and places this information in the
`>Environment:' field if it finds any.
You may submit problem reports to different Support Sites from the
default site by specifying the alternate site when you invoke
send-pr. Each site has its own list of categories for
which it accepts Problem Reports.
send-pr also provides the mail header section of the template
with default values in the `To:', `From:', and
`Reply-To:' fields. The `Subject:' field is empty.
The template begins with a comment section:
SEND-PR: -*- send-pr -*- SEND-PR: Lines starting with `SEND-PR' will be removed SEND-PR: automatically as well as all comments (the text SEND-PR: below enclosed in `<' and `>'). SEND-PR: SEND-PR: Please consult the document `Reporting Problems SEND-PR: Using send-pr' if you are not sure how to fill out SEND-PR: a problem report. SEND-PR: SEND-PR: Choose from the following categories:
and also contains a list of valid >Category: values for the
Support Site to whom you are submitting this Problem Report. One (and
only one) of these values should be placed in the >Category:
field.
The mail header is just below the comment section. Fill out the `Subject:' field, if it is not already completed using the value of `>Synopsis:'. The other mail header fields contain default values.
To: support-site Subject: complete this field From: your-login@your-site Reply-To: your-login@your-site X-send-pr-version: send-pr 3.2
where support-site is an alias for the Support Site you wish to submit this PR to.
The rest of the template contains GNATS fields. Each field is either automatically completed with valid information (such as your `>Submitter-Id:') or contains a one-line instruction specifying the information that field requires in order to be correct. For example, the `>Confidential:' field expects a value of `yes' or `no', and the answer must fit on one line; similarly, the `>Synopsis:' field expects a short synopsis of the problem, which must also fit on one line. Fill out the fields as completely as possible. See section Helpful hints, for suggestions as to what kinds of information to include.
In this example, words in italics are filled in with pre-configured information:
>Submitter-Id: your submitter-id
>Originator: your name here
>Organization:
your organization
>Confidential:<[ yes | no ] (one line)>
>Synopsis: <synopsis of the problem (one line)>
>Severity: <[non-critical | serious | critical](one line)>
>Priority: <[ low | medium | high ] (one line)>
>Category: <name of the product (one line)>
>Class: <[sw-bug | doc-bug | change-request | support]>
>Release: <release number or tag (one line)>
>Environment:
<machine, os, target, libraries (multiple lines)>
>Description:
<precise description of the problem (multiple lines)>
>How-To-Repeat:
<code/input/activities to reproduce (multiple lines)>
>Fix:
<how to correct or work around the problem, if known
(multiple lines)>
When you finish editing the Problem Report, send-pr mails it to
the address named in the `To:' field in the mail header.
send-pr checks that the complete form contains a valid
`>Category:'.
If your PR has an invalid value in one of the ENUMERATED fields
(see section Problem Report format), send-pr places the PR in
a temporary file named `/tmp/pbadnnnn' on your machine.
nnnn is the process identification number given to your current
send-pr session. If you are running send-pr from the
shell, you are prompted as to whether or not you wish to try editing the
same Problem Report again. If you are running send-pr from
Emacs, the Problem Report is placed in the buffer
`*send-pr-error*'; you can edit this file and then submit it
with
M-x gnats-submit-pr
Any further mail concerning this Problem Report should be carbon-copied to the GNATS mailing address as well, with the category and identification number in the `Subject:' line of the message.
Subject: Re: PR category/gnats-id: original message subject
Messages which arrive with `Subject:' lines of this form are automatically appended to the Problem Report in the `>Audit-Trail:' field in the order received.
send-pr from within Emacs
You can use an interactive send-pr interface from within GNU
Emacs to fill out your Problem Report. We recommend that you
familiarize yourself with Emacs before using this feature
(see section `Introduction' in GNU Emacs).
Call send-pr with `M-x send-pr'.(1) send-pr responds with a
Problem Report template preconfigured for the Support Site from which
you received send-pr. (If you use send-pr locally, the
default Support Site is probably your local site.)
You may also submit problem reports to different Support Sites from the
default site. To use this feature, invoke send-pr with
C-u M-x send-pr
send-pr prompts you for the name of a site. site is
an alias on your local machine which points to an alternate Support
Site.
send-pr displays the template and prompts you in the minibuffer
with the line:
>Category: other
Delete the default value `other' in the minibuffer and
replace it with the keyword corresponding to your problem (the list of
valid categories is in the topmost section of the PR template). For
example, if the problem you wish to report has to do with the GNU C
compiler, and your support organization accepts bugs submitted for this
program under the category `gcc', delete `other' and then type
`gcc[RET]'. send-pr replaces the line
>Category: <name of the product (one line)>
in the template with
>Category: gcc
and moves on to another field.
send-pr provides name completion in the minibuffer. For
instance, you can also type `gc[TAB]', and send-pr
attempts to complete the entry for you. Typing `g[TAB]'
may not have the same effect if several possible entries begin with
`g'. In that case send-pr cannot complete the entry because
it cannot determine whether you mean `gcc' or, for example,
`gdb', if both of those are possible categories.
send-pr continues to prompt you for a valid entry until you
enter one.
send-pr prompts you interactively to enter each field for
which there is a range of specific choices. If you attempt to enter a
value which is not in the range of acceptable entries, send-pr
responds with `[No match]' and allows you to change the entry
until it contains an acceptable value. This avoids unusable information
(at least in these fields) and also avoids typographical errors which
could cause problems later.
send-pr prompts you for the following fields:
>Category:
>Confidential: (default: no)
>Severity: (default: serious)
>Priority: (default: medium)
>Class: (default: sw-bug)
>Release:
>Synopsis: (this value is copied to Subject:)
After you complete these fields, send-pr places the cursor in
the `>Description:' field and displays the message
To send the problem report use: C-c C-c
in the minibuffer. At this point, edit the file in the main buffer to reflect your specific problem, putting relevant information in the proper fields.
`send-pr' provides a few key bindings to make moving around in a template buffer more simple:
C-c C-f
M-x change-field
edit-pr prompts you for a
new value.
M-C-b
M-x gnats-backward-field
M-C-f
M-x gnats-forward-field
M-p
M-x gnats-previous-field
M-n
M-x gnats-next-field
send-pr takes over again when you type `C-c C-c' to send the
message. send-pr reports any errors in a separate buffer, which
remains in existence until you send the PR properly (or, of course,
until you explicitly kill the buffer).
For detailed instructions on using Emacs, see section `Introduction' in GNU Emacs.
send-pr from the shell
send-pr [ site ]
[ -f problem-report | --file problem-report ]
[ -t mail-address | --to mail-address ]
[ --request-id ]
[ -L | --list ] [ -P | --print ]
[ -V | --version] [ -h | --help ]
site is an alias on your local machine which points to an address
used by a Support Site. If this argument is not present, the default
site is usually the site which you received send-pr from,
or your local site if you use GNATS locally.
Invoking send-pr with no options calls the editor named in your
environment variable EDITOR on a default PR template. If the
environment variable PR_FORM is set, its value is used as a file
name which contains a valid template. If PR_FORM points to a
missing or unreadable file, or if the file is empty, send-pr
generates an error message and opens the editor on a default template.
-f problem-report
--file problem-report
send-pr sends the contents of the file without
invoking an editor. If problem-report is `-',
send-pr reads from standard input.
-t mail-address
--to mail-address
send-pr is configured. This option is not recommended;
instead, use the argument site on the command line.
--request-id
>Submitter-Id: to the Support Site.
-L
--list
>Category: values on standard output.
No mail is sent.
-P
--print
PR_FORM is set in your
environment, the file it specifies is printed. If PR_FORM is not
set, send-pr prints the standard blank form. If the file
specified by PR_FORM doesn't exist, send-pr displays an
error message. No mail is sent.
-V
--version
send-pr version number and a usage summary. No mail
is sent.
-h
--help
send-pr. No mail is sent.
There is no orthodox standard for submitting effective bug reports,
though you might do well to consult the section on submitting bugs for
GNU gcc in section `Reporting Bugs' in Using and Porting GNU CC, by Richard Stallman. This section contains
instructions on what kinds of information to include and what kinds of
mistakes to avoid.
In general, common sense (assuming such an animal exists) dictates the kind of information that would be most helpful in tracking down and resolving problems in software.
Use edit-pr to make changes to existing PRs in the database.
edit-pr is both a shell script and a Lisp program for GNU
Emacs. Both implementations are essentially identical, though the Emacs
interface provides interactive prompting for some of the fields.
edit-pr first examines the PR you wish to edit and locks it if it
is not already locked. This is to prevent you from editing a PR at the
same time as another user. If the PR you wish to edit is already in the
process of being edited, edit-pr tells you the name of the person
who owns the lock.
You may edit any field in the database that you wish. We recommend that you avoid deleting any information in the TEXT and MULTITEXT fields (such as `>Description:' and `>How-To-Repeat:' (see section Problem Report format). We also recommend that you record the final solution to the problem in the `>Fix:' field for future reference.
If you change the `>Responsible:' field, edit-pr prompts you
to supply a reason for the change. edit-pr then mails copies of
the change message to the previous responsible party, and to the new
responsible party. The change is then recorded in the
`>Audit-Trail:' section of the PR as follows:
Responsible-Changed-<From>-<To>: The value change, supplied
edit-pr.
Responsible-Changed-By: Your name here, supplied
edit-pr.
Responsible-Changed-When: The current date, supplied
edit-pr.
Responsible-Changed-Why: Your reason for the change; you
If you change the `>State:' field, you are prompted to supply a reason for the change. Copies of the change message are then mailed to the responsible party, and to the original submitter of the Problem Report. The change is then recorded in the `Audit-Trail' section of the PR as follows:
State-Changed-<From>-<To>: The value change, supplied
edit-pr.
State-Changed-By: Your name here, supplied
edit-pr.
State-Changed-When: The current date, supplied
edit-pr.
State-Changed-Why: Your reason for the change; you are
The PR is then resubmitted to the database, and the index is updated
(see section The index file). For information on
pr-edit, the main driver for edit-pr, see section Internal utilities.
edit-pr from within Emacs
Call edit-pr from within Emacs with M-x
edit-pr(2).
When edit-pr prompts you for a PR identification number, type the
number of the PR you wish to edit.
If the PR is locked, Emacs announces the login name of the person who
has locked the file. If not, M-x edit-pr locks the PR, loads
it into a buffer named `*edit-pr*', and places the cursor in the
`>Number:' field. (Do not change this field.)
Edit the PR to reflect correct information. Resubmit the PR to the database using `C-c C-c' (see below).
The easiest way to edit a PR from Emacs is to use the special key bindings provided. These are:
C-c C-c
M-x gnats-submit-pr
C-x C-s
M-x save-buffer
C-x k
M-x gnats:kill-buffer (use this only with Emacs 18)
M-x kill-buffer
C-c C-u
M-x unlock-pr
C-c C-q
M-x unlock-buffer
C-c C-e
M-x edit-pr
edit-pr in a new buffer.
C-c C-f
M-x change-field
edit-pr prompts you for a
new value. If you use
C-u C-c C-f or C-u M-x change-fieldyou are prompted for a field to change.
C-c C-a
M-x gnats-mail-reply
C-c RET
C-c C-m
M-x gnats-mail-other-window
C-c C-r
M-x gnats-responsible-change-from-to
edit-pr prompts you for
the new responsible person, and for a message describing the reason for
the change. When you type `C-c C-c' to resubmit the PR, the
cursor is placed in a mail buffer containing a copy of the change. You
can then edit this buffer and type `C-c C-c' again to send the
mail.
C-c C-s
M-x gnats-state-change-from-to
edit-pr prompts you for the
new state, and for a message describing the reason for the change. When
you type `C-c C-c' to resubmit the PR, the cursor is placed in
a mail buffer containing a copy of the change. You can then edit this
buffer and type `C-c C-c' again to send the mail.
C-c C-t
M-x category-change-from-to
edit-pr prompts
you for the new category. edit-pr also prompts you with the
question
Update the >Responsible field?Type `y' to change the value of the `>Responsible:' field to the name of the party responsible for the new category. Type `n' to keep the current value of `>Responsible:'.
M-C-b
M-x gnats-backward-field
M-C-f
M-x gnats-forward-field
M-p
M-x gnats-previous-field
M-n
M-x gnats-next-field
edit-pr from the shell
The usage for the edit-pr shell script is:
edit-pr gnats-id [ -V | --version ] [ -h | --help ]
You must first determine which PR you want to edit. The options are:
-V or --version
edit-pr.
-h or --help
edit-pr.
edit-pr calls the editor specified in your environment
variable EDITOR on a temporary copy of that PR. (If you don't
have the variable EDITOR defined in your environment, the default
editor vi is used.)
Edit the PR, changing any relevant fields or adding to existing
information. When you exit the editor, edit-pr prompts you on
standard input for a reason if you've changed either the
`>Responsible:' field or the `>State:' field. edit-pr
tracks the information you provide when changing either of these two
fields, along with the change that occurred, your name, and the time of
change in the `>Audit-Trail:' field.
Obtain information from the database by using the program
query-pr. query-pr uses search parameters you provide
to find matching Problem Reports in the database. You can invoke
query-pr from the shell or from within Emacs. query-pr
uses the same arguments whether it is invoked from the shell or from
Emacs.
All arguments and options to query-pr are optional. If you do
not specify a PR identification number and do not give any search
parameters, query-pr displays the entire database. All arguments
are considered identification numbers of Problem Reports to display.
Any number of options can be given (though some make no sense when
specified on the same command line); all are connected with a logical
AND.
query-pr
From the shell, simply type query-pr, followed by any search
parameters you wish to exercise. From Emacs, type M-x
query-pr. query-pr prompts you for search parameters in the
minibuffer.
query-pr can also be accessed by electronic mail, if your version
of GNATS is configured for this. To use this feature, simply send
mail to the address `query-pr@your-site' with command
line arguments or options in the `Subject:' line of the mail
header. GNATS replies to your mail with the results of your query.
The default settings for the query-pr mail server are
--restricted --state="open|analyzed|feedback|suspended"
To override the `--state' parameter, specify
`--state=state' in the Subject: line of the mail
header. You can not query on confidential Problem Reports by mail.
The usage for query-pr is:
query-pr [ gnats-id ]
[ -c category | --category=category ]
[ -s state | --state=state ]
[ -r responsible | --responsible=responsible ]
[ -S submitter | --submitter=submitter ]
[ -C [ yes | no ] | --confidential=[ yes | no ] ]
[ -e severity | --severity=severity ]
[ -p priority | --priority=priority ]
[ -O originator | --originator=originator ]
[ -t text | --text=text ]
[ -m text | --multitext=text ]
[ -R | --restricted ]
[ -F | --full ] [ -q | --summary ] [ -i | --sql ]
[ -P | --print-path ]
[ -d directory | --directory=directory ]
[ -o outfile | --output=outfile ]
[ -V | --version ] [ -h | --help ]
If you run query-pr from within Emacs, you can use
C-x ` or M-x next-error
to scroll through Problem Reports one by one after the search is finished.
The following arguments and options specify search criteria. The lack of a criterion indicates that all values for the corresponding field are valid for the search. Regular expressions may be used as arguments to search criteria options; see section Querying using regular expressions.
Using an argument to query-pr specifies the most stringent search
criteria, that of a single PR.
gnats-id
-c category
--category=category
-s state
--state=state
-r responsible
--responsible=responsible
-S submitter
--submitter=submitter
-C [yes | no]
--confidential=[yes | no]
-e severity
--severity=severity
-p priority
--priority=priority
-O originator
--originator=originator
index file).
-t text
--text=text
Submitter-Id Originator Synopsis Category Release Responsible Arrival-DateSee section Querying using regular expressions. Queries using this option can be slow. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that is part of the index (see section The
index file).
-m text
--multitext=text
Organization Environment Description How-To-Repeat Fix Audit-Trail UnformattedSee section Querying using regular expressions. Queries using this option can be very slow. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that is part of the index (see section The
index file).
-R
--restricted
query-pr --confidential=noand also disallows the use of the options `--outfile=outfile' and `--directory=directory'. This option is used with the
mail-query tool.
-x
--skip-closed
Use the following options to select the format in which the Problem Report is printed. Use only one of these options for a given search. If you do not specify one of these options, a header(3) for the Problem Reports meeting the search criteria is printed.
-F
--full
-q
--summary
Number Responsible Category State Severity Priority Submitter-Id Synopsis
-i
--sql
query-pr outputs ENUMERATED fields
numerically rather than textually; see section Reporting on groups of Problem Reports.
`query-pr -i' outputs the following fields, in order (again, the
fieldname delimiters `>' and `:' have been omitted):
Number Category Synopsis Confidential Severity Priority Responsible State Class Submitter-Id Arrival-Date Originator ReleaseWhen you use the `-i' option, `query-pr' outputs the ENUMERATED fields in the database, namely `>Severity:', `>Priority:', `>State:', and `>Class:', as numbers rather than text. See section Reporting on groups of Problem Reports, for details.
query-pr also accepts the following options:
-P
--print-path
query-pr used to find the current PR. A
line of the form `directory/number:number' is
printed before each PR. This option is automatically used from within
Emacs to facilitate scrolling through groups of PRs with C-x `.
-d directory
--directory=directory
-o outfile
--output=outfile
-V
--version
query-pr.
-h
--help
query-pr.
The following simple query:
query-pr --category=rats --responsible=fred --state=analyzed
yields all PRs in the database which contain the field values:
>Category: rats and >Responsible: fred and >State: analyzed
The following query:
query-pr --state="o|a"
yields all PRs in the database whose `>State:' values match either `open' or `analyzed' (see section Querying using regular expressions. This search is useful as a daily report that lists all Problem Reports which require attention.
The report can be further altered using an alternate output format for
query-pr; see section Reporting on groups of Problem Reports. A more fine-grained report may be obtained by specifying more
search parameters, e.g. narrowing the search down by
`>Submitter:' or by `>Responsible:'.
The following query:
query-pr --text="The quick.*brown fox"
yields all PRs whose TEXT fields contain the text `The quick' followed by `brown fox' within the same field. See section Querying using regular expressions.
There currently exists no separate reporting mechanism in GNATS from
query-pr. However, the `-q' and `-i' options to
query-pr allow for easy reporting.
For example, a report on the current open Problem Reports in the
database can be obtained using awk with
query-pr -q | awk '{print $3 "/" $1 ": " $4}'
which yields a list of the form
category/gnats-id: state etc...
For example:
sprockets/123: open widgets/456: analyzed etc...
The `-i' option to query-pr yields output delimited by pipes
(`|'). This results in the following:
gnats-id|category|synopsis|confidential|\ severity|priority|responsible|state|class|\ submitter-id|arrival-date|originator|release
A report on Problem Reports in the database that are currently `open' or `analyzed' might resemble the following (the example is split into two lines in order to fit onto the page; it is intended to be typed on one command line):
query-pr -i -s "o|a" | \
awk -F\| '{print $1 " " $2 " " $8 " " $3}'
which yields
gnats-id category state responsible synopsis etc...
For example:
123 sprockets 1 fred The sprockets program gives bad output 456 widgets 2 barney The foo widget doesn't work with 'bar' 789 widgets 1 wilma The 'baz' widget is broken
When you use the `-i' option, `query-pr' outputs the ENUMERATED fields in the database, namely `>Severity:', `>Priority:', `>State:', and `>Class:', as numbers rather than text. In the example above, a `>State:' value of `1' means `open', `2' means `analyzed', and so forth. ENUMERATED fields are output according to the following paradigm:
>Severity: >Priority:
critical 1 high 1
serious 2 medium 2
non-critical 3 low 3
>State: >Class:
open 1 sw-bug 1
analyzed 2 doc-bug 2
suspended 3 support 3
feedback 4 change-request 4
closed 5 mistaken 5
duplicate 6
This makes sorting on these values easy, when combined with sort.
It is left as an exercise for the reader to figure out how to do this.
Use view-pr from within Emacs to view individual Problem Reports.
Invoke view-pr with
M-x view-pr
You are prompted to enter a Problem Report identification number
(gnats-id). You can also invoke view-pr with
C-u gnats-id M-x view-pr
view-pr allows you to view gnats-id. This is identical to
using
C-u gnats-id M-x query-pr
except that you may choose to edit the PR at any time by pressing `e'.
In daily usage, GNATS is self-maintaining. However, there are various administrative duties which need to be performed periodically:
pending directory
gnats-admin and to the party
responsible for that submitter (as listed in the `submitters' file)
when this occurs.
To file these PRs, simply use edit-pr to repair the problematic
fields in each file in the `pending' directory. Be sure to change
the `>Category:' field of the PR from `pending' to an
appropriate category. In many cases the culprit is simply a
typographical error, although it may be necessary sometimes to contact
the submitter of the PR to decipher her or his intentions.
mkcat.
Note: this causes all category lists for send-pr (except
the one on the local machine) to become outdated. Copy the new list on
to every machine on your network that has send-pr installed, and
make sure you advise remote submitters that the category list has
changed. See section Adding a problem category. Also
section The categories file.
rmcat category...to remove category (any number of categories may be specified on the command line to
rmcat, so long as they abide by the above
constraints).
Note: this causes all category lists for send-pr (except
the one on the local machine) to become outdated. Copy the new list on
to every machine on your network that has send-pr installed, and
make sure you advise remote submitters that the category list has
changed. See section Removing a problem category. Also
section The categories file.
responsible file.
send-pr
send-pr which contains valid
information for your site by invoking the command mkdist.
See section Configuring send-pr for the outside world. You
can then distribute your customized send-pr to your
customers, friends, relatives, etc., so that they can submit Problem
Reports to your database.
gen-index
(see section Regenerating the index).
See section Where GNATS lives.
If you have installed the GNATS user tools on machines around your local network, there are a few things you need to remember.
mkcat and rmcat do not update the categories list for
other machines on your network which have send-pr installed,
unless those machines share prefix with the host machine). To
update these lists, copy the send-pr categories list to each of
the other hosts. This categories list is
`prefix/lib/gnats/site', where site is the
name tag for your local site, as specified in the `config' file as
`GNATS_SITE' (see section The config file).
It is also important to note that only your local send-pr has
access to this new information; any copies of send-pr which you
have distributed to outside submitters now have outdated category lists.
You must either contact your submitters and instruct them to update
their copy of the categories list, which they installed in
`prefix/lib/gnats/support-site' from the
distribution you provided, or you must build another distribution of
send-pr with this new information and redistribute it.
If you need to use GNATS utilities, like query-pr and
edit-pr, on other systems besides the one where GNATS itself
resides, see section Installing the user tools.
See section Where GNATS lives.
Your local configuration is determined by the data files in the directory `GNATS_ROOT/gnats-adm'. These can be altered at any time by editing the pertinent file.
config
config file. Behaviors you can change here include
send-pr).
submitters file, and section Timely reminders.
categories
categories file. Also
see section Adding a problem category, and section Removing a problem category.
responsible
responsible file.
submitters
submitters file.
The default behavior for GNATS is as follows:
send-pr) is the nametag for your Support
Site.
config fileMuch of the behavior GNATS exhibits depends on the values of fields in the file `GNATS_ROOT/gnats-adm/config'. The `config' file contains a list of varibles (using Bourne-shell syntax) which control the following behavior. These values can be changed at any time; the new values take effect for all subsequent iterations of the tools.
GNATS_ADDR="address"
queue-pr (see section Installing the utilities).
The default is `bugs' (a local address).
GNATS_ADMIN="address"
GNATS_SITE="site"
SUBMITTER="submitter-id"
send-pr).
Even though you are a Support Site, if you submit Problem Reports to
your own organization you become a Submitter Site. The value
submitter-id is the default value for the `>Submitter-Id:'
field that your maintainers see when they submit Problem Reports
locally.
The default is the value of `GNATS_SITE'.
DEFAULT_RELEASE="release"
send-pr).
The default is `unknown-1.0'.
DEFAULT_ORGANIZATION="text"
send-pr).
The default is the value of `GNATS_SITE'.
NOTIFY=boolean
at-pr; see
section Timely reminders.
This requisite time is determined for each submitter individually; see
section The submitters file. The time is measured in
business hours, which by default are 8:00am to 5:00pm, Monday
through Friday. Business hours can be redefined by changing the
variables BDAY_START, BDAY_END, BWEEK_START, and
BWEEK_END in the `config' file (see below).
If boolean is `1', this feature is active. If boolean
is `0', the feature is turned off. The default value for
`NOTIFY' is `1'.
ACKNOWLEDGE=boolean
To: your-address
From: gnats
Subject: Re: category/gnats-id:Synopsis
In-Reply-To: Your message of date
Thank you very much for your problem report.
It has the internal identification: category/gnats-id
The individual assigned to look at your bug is:
responsible
Category: category of the PR
Responsible: responsible
Synopsis: Synopsis from submitted PR
Arrival-Date: arrival date
DEFAULT_SUBMITTER="submitter-id"
submitters file.
To disable the feature of GNATS which tracks the
`>Submitter-Id:', simply alter the `submitters' file to only
contain the submitter-id value which appears in
DEFAULT_SUBMITTER, and and instruct your submitters to ignore
the field.
The default value for `DEFAULT_SUBMITTER' is `unknown'.
KEEP_RECEIVED_HEADERS=boolean
DEBUG=boolean
gnats-admin.
BDAY_START=integer
BDAY_END=integer
BWEEK_START=integer
BWEEK_END=integer
NOTIFY is set to `1' in the `config' file (see above).
By default, business hours are 8:00am to 5:00pm Monday through Friday,
local time.
BDAY_START=integer
BDAY_END=integer
BWEEK_START=integer
BWEEK_END=integer
categories file
The `categories' file contains a list of problem categories,
specific to your site, which GNATS tracks. This file also matches
responsible people with these categories. You must edit this file
initially, creating valid categories and then running mkcat to
create the corresponding subdirectories of GNATS_ROOT
and update the valid categories list for send-pr. For
instructions on running mkcat, see section Adding a problem category.
To create a new category, log in as GNATS, add a line to this file,
and run mkcat. Lines beginning with `#' are ignored.
A line in the `categories' file consists of four fields delimited by colons, as follows:
category:description:responsible:notify
! $ & * ( ) { } [ ] ` ' " ; : < > ~
Ideally, category names should not contain commas or begin with periods.
Each line has a corresponding subdirectory in the main GNATS
directory (GNATS_ROOT).
responsible file).
A good strategy for configuring this file is to have a different category for each product your organization supports or wishes to track information for, or perhaps with sub-categories within each category. For instance, if you wish to track documentation problems in a variety of areas, you could have entries such as
doc:General Doc Questions:myboss:me,barney doc-rock:Doc for ROCK program:me:myboss doc-stone:Docs for STONE utils:barney:fred doc-local:in-house documentation:me:doc-local-log
In the above example, the nametags `myboss', `me',
`fred', and `barney' must be defined in the `responsible'
file (see section The responsible file).
Problem Reports with a category of `doc' are sent to the local mail
address (or alias) `myboss', and also sent to the addresses
`me' and `barney'. PRs with a category of `doc-rock' are
sent to the local addresses `me' and `myboss' only, while PRs
with the category `doc-stone' are sent to `fred' as well as to
`barney'. PRs with a category of `doc-local' are sent only to
`me', and are also filed in doc-local-log (in this case, an
alias should be set up in `/etc/aliases' to reflect a location for
the log file, such as `doc-local-log: /users/me/local-log').
Whenever you add a new category, be sure to run mkcat to create a
subdirectory for it and update the local categories list.
Only one category must be present for GNATS to function:
pending:Category for faulty PRs: gnats-admin:
The `pending' directory is created automatically when you run `make install' (see section Configuring and compiling the software).
responsible fileThis file contains a list of the responsible parties. Lines beginning with `#' are ignored. Each entry contains three fields, separated by colons:
responsible:full-name:mail-address
A sample `responsible' listing might be:
ren:Ren Hoek: stimpy:Stimpson J. Cat:stimpy@lederhosen.org
Here, ren is a local user. stimpy is remote, so his full
address must be specified.
The following entry must be present for GNATS to function:
gnats-admin: GNATS administrator:
(gnats-admin is a mail alias, so for this purpose
gnats-admin is a local address.)
submitters fileThis is a database of sites which submit bugs to your support site. It contains six fields delineated by colons. Lines beginning with `#' will be ignored.
Entries are of the format:
submitter-id:name:type:resp-time:contact:notify
NOTIFY field is defined as
`1' in the `config' file (see section Changing your local configuration). If NOTIFY is `0', this field is
ignored. For information on at-pr, the program which sends out
this reminder, see section Timely reminders.
responsible file). Incoming bugs from
submitter are sent to this contact. Optionally, this field can be
left blank.
A few example entries in the `submitters' file:
univ-hell: University of Hades:eternal:3:beelzebub:lucifer tta: Telephones and Telegraphs of America:support:720:dave:
In this example, when a PR comes in from the University of Hades (who
has an eternal contract), it should have `univ-hell' in its
`Submitter-Id' field. This Problem Report goes to beelzebub
(who should be in the `responsible' file), and if it is not
analyzed within three business hours a reminder message is sent.
lucifer also receives a copy of the bug, and a copy of the
reminder message as well (if it is sent). When Telephones and
Telegraphs of America utilizes their support contract and submits a bug,
a copy is sent only to dave, who has 720 business hours to return
an analysis before a reminder is sent.
To disable the feature of GNATS which tracks the
`>Submitter-Id:', simply alter the `submitters' file to only
contain the submitter-id value which appears as the
`DEFAULT_SUBMITTER' value in the `config' file
(see section The config file), and instruct your submitters
to ignore the field.
The following files are located in `GNATS_ROOT/gnats-adm', where GNATS_ROOT is the resident directory of GNATS. These files are maintained by GNATS; you should never touch them.
index file
The index is used to accelerate searches on the database by
query-pr and edit-pr. This file is not created until the
first PR comes in. It is then kept up to date by GNATS; you should
never touch this file.
Any searches on subjects contained in the index are much faster than searches which depend on data not in the index. The index contains single-line entries for the following fields, in order, separated by colons (`:') except for `>Category:' and `>Number:', which are separated by a slash (`/') (the `>' and `:' Problem Report fieldname delimiters have been removed for the sake of brevity and readability)::
Category Number Submitter-Id Responsible State Confidential Severity Priority
To see an example index, run gen-index without any options
(see section Regenerating the index).
current fileThis file contains the last serial number assigned to an incoming PR. It is used internally by GNATS; you need never touch this file.
These tools are used by the GNATS administrator as part of the periodic maintenance and configuration of GNATS. See section GNATS Administration.
To add new categories to the database:
categories file.
mkcat. mkcat creates a directory under
GNATS_ROOT for any new categories which appear in the
`categories' file. mkcat also recreates the list of valid
categories for both your locally installed send-pr and for the
send-pr distribution template in
`prefix/lib/gnats/dist' (see section Where GNATS lives.
Note: mkcat does not update the categories list for other
machines on your network which have send-pr installed (unless
the two machines share the directory prefix).
See section Managing GNATS over a network.
It is also important to note that only your local send-pr has
access to this new information; any copies of send-pr which you
have distributed to outside submitters now have outdated category lists.
You must either contact your submitters and instruct them to update
their copy of the categories list, which they installed in
`prefix/lib/gnats/support-site' (Note: the
value for prefix may be different from yours) from the
distribution you provided, or you must build another distribution of
send-pr with this new information and redistribute it
(see section Configuring send-pr for the outside world).
To remove a category from the database:
rmcat using
rmcat category [ category... ]where category is the category you wish to remove. You can specify as many categories as you wish as long as each category has no PRs associated with it.
rmcat removes the directory under
GNATS_ROOT where the Problem Reports for that category had been
stored. rmcat also deletes the category from the list of valid
categories for both your locally installed send-pr and for the
send-pr distribution template in
`prefix/lib/gnats/dist' (see section Where GNATS lives).
Note: rmcat does not update the categories list for other
machines on your network which have send-pr installed.
See section Managing GNATS over a network.
It is also important to note that only your local send-pr has
access to this new information; any copies of send-pr which you
have distributed to outside submitters now have outdated category lists.
You must either contact your submitters and instruct them to update
their copy of the categories list, which they installed in
`prefix/lib/gnats/support-site' (Note: the
value for prefix may be different from yours) from the
distribution you provided, or you must build another distribution of
send-pr with this new information and redistribute it
(see section Configuring send-pr for the outside world).
If your `index' file becomes corrupted, or if you need a copy of the current index for some reason, use
gen-index [ -n | --numeric ]
[ -d directory | --directory=directory ]
[ -o filename | --outfile=filename ]
[ -h | --help] [ -V | --version ]
With no options, gen-index generates an index that is ordered the
same as the order of the categories as they appear in the
`categories' file, and prints it to standard output. The options
are:
-n
--numeric
-d directory
--directory=directory
-o filename
--outfile=filename
-h
--help
gen-index.
-V
--version
gen-index.
send-pr for the outside world
Now that GNATS is up and running on your system, you probably want
to distribute send-pr to all your friends, relatives, enemies,
etc. so they can more easily submit bugs to your organization. To do
this, create a new directory dist-directory to hold the
distribution. Then run the program
mkdist dist-directory release
This populates dist-directory with a full distribution of the
program send-pr, including a `Makefile' and all the
send-pr documentation. You can then simply package up this
directory and send it to your bug report submitters. For example,
when logged in as gnats you can do the following:
mkdir new-dist mkdist new-dist tools-1.2 tar cvf send-pr.tar new-dist
This creates a file called `send-pr.tar' which contains a full
distribution of send-pr customized for your site, with a default
release number of `tools-1.2'. You can then place this onto a disk
or tape and send it to your submitters, or instruct your submitters to
download it using ftp.
These tools are used internally by GNATS. You should never need to run these by hand; however, a complete understanding may help you locate problems with the GNATS tools or with your local implementation.
The program queue-pr handles traffic coming into GNATS.
queue-pr queues incoming Problem Reports in the directory
`GNATS_ROOT/gnats-queue', and then periodically (via
cron) passes them on to file-pr to be filed in the
GNATS database. See section Installing GNATS.
The usage for queue-pr is as follows:
queue-pr [ -q | --queue ] [ -r | --run ]
[ -f filename | --file=filename ]
[ -d directory | --directory=directory ]
One of `-q' or `-r' (or their longer-named counterparts) must
be present upon each call to queue-pr. These options provide
different functions, as described below.
-q
--queue
GNATS_ROOT (see section Where GNATS lives).
-r
--run
file-pr one by one.
-f filename
--file=filename
-d directory
--directory=directory
queue-pr files incoming messages into
directory rather than the `gnats-queue' directory. When
`-d directory' is used in conjunction with the `-r'
(or `--run') option, queue-pr redirects into
file-pr files from directory rather than from the
`gnats-queue' directory.
queue-pr hands off queued Problem Reports to file-pr one
at a time. file-pr checks each Problem Report for correct
information in its fields (particularly a correct `>Category:'),
assigns it an identification number, and files it in the database under
the appropriate category.
If the `>Category:' field does not contain a valid category value
(i.e., matching a line in the categories file;
see section The categories file), the PR is given a
`>Category:' value of `pending' and is placed in the
`pending' directory. The GNATS administrator is notified of
the unplaceable PR.
file-pr assigns the Problem Report an identification number,
files it in the GNATS database (under `pending', if the
`>Category:' field contains an invalid category), and sends
acknowledgements to appropriate parties. The person responsible for
that category of problem (see section The categories file) and the person responsible for the submitter site where the PR
originated (see section The submitters file) receive a
copy of the PR in its entirety. Optionally, the originator of the PR
receives an acknowledgement that the PR arrived and was filed
(see section Changing your local configuration).
The usage for file-pr is as follows:
file-pr [ -f filename | --file=filename ]
[ -d directory | --directory=directory ]
[ -h | --help ] [ -V | --version ]
file-pr requires no options in order to operate, and takes input
from standard input (normally, the output of `queue-pr -r')
unless otherwise specified. The options include:
-f filename
--filename=filename
-d directory
--directory=directory
GNATS_ROOT.
-h
--help
file-pr.
-V
--version
file-pr.
at-pr creates a queued job using at which, after an
allotted response time is past, checks the PR to see if its state
has changed from `open'.
The `submitters' file contains the response time for each
>Submitter-Id: (see section The submitters file).
The time is determined in business hours, which are defined by
default as 8:00am to 5:00pm Monday through Friday, local time. These
hours are defined in the `config' file (see section The config file).
If the PR is still open after the requisite time period has passed,
at-pr sends a reminder to the GNATS administrator, to the
maintainer responsible for that submitter, and to the maintainer
responsible for the PR with the following message:
To: submitter-contact responsible gnats-admin Subject: PR gnats-id not analyzed in #hours hours PR gnats-id was not analyzed within the acknowledgment period of #hours business hours. The pertinent information is: Submitter-Id: submitter Originator: full name of the submitter Synopsis: synopsis Person responsible for the PR: responsible -- The GNU Problem Report Management System (GNATS)
edit-pr driver
pr-edit does the background work for edit-pr, including
error-checking and refiling newly edited Problem Reports and handling
file locks. It can be called interactively, though it has no useable
editing interface.
The usage for pr-edit is:
pr-edit [ -l maintainer --lock=maintainer ]
[ -u | --unlock ] [ -c | --check ] [ -F ]
[ -f filename | --filename=filename ]
[ -d directory | --directory=directory ]
[ -h | --help ] [ -V | --version ]
[ gnats-id ]
A lock is placed on a Problem Report while the PR is being edited.
The lock is simply a file in the same directory as the PR, with the name
`gnats-id.lock', which contains the name of the maintainer
who created the lock. maintainer then "owns" the lock, and must
remove it before the PR can be locked again, even by the same
maintainer(4). If a PR is already locked
when you attempt to edit it, pr-edit prints an error message
giving the name of the maintainer who is currently editing the PR.
If you do not specify gnats-id, pr-edit reads from
standard input. You must specify gnats-id for the functions
which affect PR locks, `--lock=maintainer' and
`--unlock'.
-l maintainer
--lock=maintainer
pr-edit requires that you specify
gnats-id when using this option.
-u
--unlock
pr-edit requires that
you specify gnats-id when using this option. You must own a
file lock to remove it.
-c
--check
pr-edit complains about any bogus
information in the Problem Report.
-F
-f filename
--filename=filename
-d directory
--directory=directory
GNATS_ROOT).
-h
--help
pr-edit.
-V
--version
pr-edit.
Returns an electronic mail address when given a valid nametag, as
it appears in the `responsible' file (see section The responsible file).
pr-addr name
See section Where GNATS lives.
There are several steps you need to follow to fully configure and
install GNATS on your system. You need root access in order
to create a new account for gnats and to install the GNATS
utilities. You may need root access on some systems in order to
set mail aliases in place and to allow this new account access to
cron and at.
If you are updating an older version of GNATS rather than installing from scratch, see section Upgrading from older versions.
To build GNATS, you must:
configure, with correct options if the defaults are
unsuitable for your site. See section Configuring and compiling the software. Default installation locations are in
section Where GNATS lives.
query-pr, edit-pr,
send-pr) around your network. See section Installing the user tools.
config categories submitters responsiblein `GNATS_ROOT/gnats-adm'. See section Changing your local configuration.
send-pr for submitters outside your
organization. See section Configuring send-pr for the outside world.
tar
file which was compressed using gzip. The code can be extracted
into a directory unpackdir using
mkdir unpackdir cd unpackdir tar zxvf gnats-3.2.tar.zThe sources reside in a directory called `gnats-3.2' when unpacked. We call this the top level of the source directory, or srcdir. The sources for the GNATS tools are in the subdirectory `gnats-3.2/gnats/*'. Lists of files included in the distribution are in each directory in the file `MANIFEST'.
srcdir/gnats/Makefile.in and srcdir/send-pr/Makefile.inChange the variable `lispdir' from `$(datadir)/emacs/lisp' to the directory containing your Emacs lisp library. For information on prefix, see section prefix.
configure. You can nearly always run configure with
the command
./configure --with-full-gnatsand the "Right Thing" happens:
configure is:
configure [ --with-full-gnats ]
[ --prefix=prefix ]
[ --exec-prefix=exec-prefix ]
[ --with-gnats-root=GNATS_ROOT ]
[ --verbose ]
--with-full-gnats
--prefix=prefix
--exec-prefix=exec-prefix
--with-gnats-root=GNATS_ROOT
--verbose
configure runs.
configure' in Cygnus configure.
You can build GNATS in a different directory (objdir) from the
source code by calling the configure program from the new
directory, as in
mkdir objdir cd objdir srcdir/configure ... make allBy default,
configure compiles the programs in the same directory
as the sources (srcdir). Emacs lisp files are byte-compiled if
make can find Emacs on your local system.
make all infofrom the directory where
configure created a `Makefile'.
(This may not be the same directory as the source directory.) These
targets indicate:
all
info
makeinfo.
The following steps are necessary for a complete installation. You may
need root access for these.
make install install-infoThese targets indicate:
install
install-info
make clean
(autoload 'edit-pr "gnats" "Command to edit a problem report." t) (autoload 'view-pr "gnats" "Command to view a problem report." t) (autoload 'unlock-pr "gnats" "Unlock a problem report." t) (autoload 'query-pr "gnats" "Command to query information about problem reports." t) (autoload 'send-pr-mode "send-pr" "Major mode for sending problem reports." t) (autoload 'send-pr "send-pr" "Command to create and send a problem report." t)Emacs lisp files are byte-compiled if
make can find Emacs on your
local system.
PATH for this
user should contain `exec-prefix/bin' and
`exec-prefix/lib/gnats'.
gnats access to cron and at. To
do this, add the name gnats to the files `cron.allow' and
`at.allow', which normally reside in the directory
`/var/spool/cron'. If these files do not exist, make sure
gnats does not appear in either of the files `cron.deny'
and `at.deny' (in the same directory).
For the following steps, log in as gnats.
mkcat after you update
the `categories' file (see section Adding a problem category). Note: these templates are not installed if they
already exist, i.e. if you are upgrading. See section Upgrading from older versions.
crontab entry that periodically runs the program
queue-pr with the `--run' option. For example, to run
`queue-pr --run' every ten minutes, create a file called
`.mycron' in the home directory of the user gnats which
contains the line:
0,10,20,30,40,50 * * * * exec-prefix/lib/gnats/queue-pr --run(Specify the full path name for
queue-pr.) Then run
crontab -r .mycronSee the
man pages for cron and crontab for details
on using cron.
The following mail aliases must be placed in the file
`/etc/aliases' on the same machine where the GNATS tools
are installed. You may need root access to add these aliases.
gnats-admin: address
bugs: "| exec-prefix/lib/gnats/queue-pr -qThis places incoming Problem Reports in `GNATS_ROOT/gnats-queue'.
config file), with an added suffix `-gnats'. This alias,
`GNATS_SITE-gnats', should point toward the local
submission address. For instance, if your site is Tofu Technologies,
the presence of GNATS on your site would be aliased as the
following (the previous example is also shown):
bugs: "| exec-prefix/lib/gnats/queue-pr -q tofu-gnats: bugsThe report submission utility
send-pr automatically appends the
`-gnats' to any arguments you specify (see section Submitting Problem Reports). The send-pr which was installed when you
typed make install has a default argument of GNATS_SITE,
your site, so that when your local users simply type send-pr mail
is sent to your local GNATS. Part of the installation process a
Submitter Site follows when installing send-pr is to set up an
alias for the Support Site from whom this submitter received
send-pr. In other words, anyone you distribute send-pr to
is instructed to make an alias
tofu-gnats: bugs@tofu.com
bug-q: "| exec-prefix/lib/gnats/queue-pr -q bug-log: GNATS_ROOT/gnats-adm/bugs.log bugs: bug-q, bug-logThis configuration archives incoming Problem Reports in the file `GNATS_ROOT/gnats-adm/bug.log', and also feeds them to the program
queue-pr. (Remember, `bug.log' needs to be
world-writable, and should be pruned regularly; see section GNATS Administration.)
query-pr: "| exec-prefix/lib/gnats/mail-queryThe
mail-query program uses `--restricted' to search on the
database, and by default only searches for PRs that aren't closed
(see section Querying the database).
When you install the GNATS utilities, the user tools are installed by default on the host machine. If your machine is part of a network, however, you may wish to install the user tools on each machine in the network so that responsible parties on those machines can submit new Problem Reports, query the database, and edit existing PRs. To do this, follow these steps on each new host. You may need root access on each machine.
configure, without specifying
`--with-full-gnats', and using the same argument (if any) for
the option
--with-gnats-root=GNATS_ROOTthat you specified when building the GNATS utilites (see section Configuring and compiling the software). You may use different values for the other options to
configure.
Again, do not use `--with-full-gnats' at this point, as
that creates all the GNATS programs. Without this option,
configure only instructs the resulting `Makefile' to create
the user utilities.
You may need root access on each host for the following steps.
gnats must be the same as on the main GNATS host.
make all info install install-infoThis builds and installs the
gnats user tools query-pr,
edit-pr, and send-pr on the new host, and installs
them in `exec-prefix/bin' on the new host (Note:
the value for exec-prefix on the new host may be different from
the value you used when building the GNATS utilities;
see section exec-prefix). The programs pr-edit
and pr-addr are installed into
`exec-prefix/lib/gnats'.
info files are created as well, and are installed into
`prefix/info'. The Elisp files `gnats.el' and
`send-pr.el' (and possibly `gnats.elc' and `send-pr.elc',
if make was able to compile them using Emacs) are installed into
`prefix/lib/emacs/lisp' unless you change the
`lispdir' variable in `Makefile.in' (see section Configuring and compiling the software).
(autoload 'edit-pr "gnats" "Command to edit a problem report." t) (autoload 'view-pr "gnats" "Command to view a problem report." t) (autoload 'unlock-pr "gnats" "Unlock a problem report." t) (autoload 'query-pr "gnats" "Command to query information about problem reports." t) (autoload 'send-pr-mode "send-pr" "Major mode for sending problem reports." t) (autoload 'send-pr "send-pr" "Command to create and send a problem report." t)
send-pr uses (see section Where GNATS lives).
site is your local site, the value of `GNATS_SITE' in the
`config' file (see section The config file).
If you are upgrading from a previous release of GNATS, you probably do not want to delete your current configuration files or your current database. The new GNATS can be installed around the older version.
You need to:
configure when you build the new tools, with
configure --with-full-gnats --with-gnats-root=GNATS_ROOT(See section Configuring and compiling the software.)
queue-pr now
resides in `exec-prefix/lib/gnats' rather than
`GNATS_ROOT/gnats-bin' (see section Where GNATS lives).
PATH for the gnats user to search the
directories `exec-prefix/bin' and
`exec-prefix/lib/gnats'.
send-pr to your Submitter Sites
(see section Configuring send-pr for the outside world).
This is not absolutely necessary, as GNATS can read Problem Reports
generated by older versions of send-pr. It should be done
eventually, however, as send-pr is improved over older
verisons.
We use a few conventions when referring to the installation structure GNATS uses. These values are adjustable when you build and install GNATS (see section Installing GNATS).
prefix corresponds to the variable `prefix' for
configure, which passes it on to the `Makefile' it creates.
prefix sets the root installation directory for
host-independent files as follows:
man pages
info documents
include files
The default value for prefix is `/usr/local', which can
be changed on the command line to configure using
configure --prefix=prefix ...
See section Configuring and compiling the software.
exec-prefix corresponds to the variable `exec_prefix' for
configure, which passes it on to the `Makefile' it creates.
exec-prefix sets the root installation for
host-dependent files as follows:
Since most installations are not intended to be distributed around a network, the default value for exec-prefix is the value of `prefix', i.e., `/usr/local'. However, using exec-prefix saves space when you are installing a package on several different platforms for which many files are identical; rather than duplicate them for each host, these files can be shared in a common repository, and you can use symbolic links on each host to find the host-dependent files. It is not necessary to use this paradigm when building the GNATS tools. See section Configuring and compiling the software.
Use exec-prefix in conjunction with prefix to share
host-independent files, like libraries and info documents. For
example:
for each host: configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-host make all install ...
Using this paradigm, all host-dependent binary files are installed into `/usr/gnu/H-host/bin', while files which do not depend on the host type for which they were configured are installed into `/usr/gnu'.
You can then use a different symbolic link for `/usr/gnu' on each host (`/usr' is usually specific to a particular machine; it is always specific to a particular architecture).
on host-1: ln -s /usr/gnu/H-host-1 /usr/gnu on host-2: ln -s /usr/gnu/H-host-2 /usr/gnu
To the end user, then, placing `/usr/gnu/bin' in her or his
PATH simply works transparently for each host type.
You can change exec-prefix on the command line to
configure using
configure --exec-prefix=exec-prefix ...
We recommend that you consult section `Using configure' in Cygnus configure, before attempting this.
Again, it is not necessary to use this paradigm when building the
GNATS tools.
The location of the database and the administrative data files, by
default `prefix/lib/gnats/gnats-db'. You can change this
value on the command line to configure using
configure --with-gnats-root=GNATS_ROOT
Administrative data files reside in `GNATS_ROOT/gnats-adm'. These include `categories', `submitters', `responsible', and `config', as well as two files generated and maintained by GNATS, `index' and `current'. See section Changing your local configuration, and section Administrative data files.
configure
(see section Configuring and compiling the software).
configure
(see section Configuring and compiling the software).
configure (see section Configuring and compiling the software).
GNATS installs tools, utilities, and files into the following locations.
exec-prefix/bin
send-pr
edit-pr
query-pr
exec-prefix/lib/gnats
mkcat
rmcat
mkdist
send-pr for the outside world.
gen-index
queue-pr
file-pr
at-pr
pr-edit
edit-pr driver.
pr-addr
libiberty.a
libiberty library.
prefix/lib/gnats/dist
send-pr.
send-pr for the outside world.
prefix/lib/gnats
send-pr; site
is the value of `GNATS_SITE' (see section The config file).
prefix/lib/emacs/lisp
gnats.el
gnats.elc
query-pr, edit-pr, and
view-pr. See section Invoking the GNATS tools. To change this directory you must alter `Makefile.in'; see
section Configuring and compiling the software.
send-pr.el
send-pr.elc
send-pr.
See section Submitting Problem Reports.
prefix/info
gnats.info
send-pr.info
info (the GNU
hypertext browser). See section `Reading GNU Online Documentation' in GNU Online Documentation.
prefix/man/man1
prefix/man/man8
man pages for all the GNATS tools and utilities.
prefix/src
prefix/sample
GNATS_ROOT
gnats-adm
config
categories
submitters
responsible
index
current
gnats-queue
pending
category
GNATS uses GNU regular expression syntax with these settings:
RE_SYNTAX_POSIX_EXTENDED | RE_BK_PLUS_QM & RE_DOT_NEWLINE
This means that parentheses (`(' and `)') and pipe symbols (`|') do not need to be used with the escape symbol `\'. The tokens `+' and `?' do need the escape symbol, however.
Unfortunately, we do not have room in this manual for an adequate tutorial on regular expressions. The following is a basic summary of some regular expressions you might wish to use.
See section `Regular Expression Syntax' in Regex, for details on regular expression syntax. Also see section `Syntax of Regular Expressions' in GNU Emacs Manual, but beware that the syntax for regular expressions in Emacs is slightly different.
All search criteria options to query-pr rely on regular
expression syntax to construct their search patterns. For example,
query-pr --state=open
matches all PRs whose `>State:' values match with the regular expression `open'.
We can substitute the expression `o' for `open', according to GNU regular expression syntax. This matches all values of `>State:' which begin with the letter `o'.
query-pr --state=o
is equivalent to
query-pr --state=open
in this case, since the only value for `>State:' which matches the expression `o' is `open'. (Double quotes (") are used to protect the asterix (*) from the shell.) `--state=o' also matches `o', `oswald', and even `oooooo', but none of those values are valid states for a Problem Report.
Regular expression syntax considers a regexp token surrounded with parentheses, as in `(regexp)', to be a group. This means that `(ab)*' matches any number of contiguous instances of `ab', including zero. Matches include `', `ab', and `ababab'.
Regular expression syntax considers a regexp token surrounded with square brackets, as in `[regexp]', to be a list. This means that `Char[(ley)(lene)(broiled)' matches any of the words `Charley', `Charlene', or `Charbroiled' (case is significant; `charbroiled' is not matched).
Using groups and lists, we see that
query-pr --category="gcc|gdb|gas"
is equivalent to
query-pr --category="g(cc|db|as)"
and is also very similar to
query-pr --category="g[cda]"
with the exception that this last search matches any values which begin with `gc', `gd', or `ga'.
The `.' character is known as a wildcard. `.' matches on any single character. `*' matches the previous character (except newlines), list, or group any number of times, including zero. Therefore, we can understand `.*' to mean "match zero or more instances of any character." For this reason, we never specify it at the end of a regular expression, as that would be redundant. The expression `o' matches any instance of the letter `o' (followed by anything) at the beginning of a line, while the expression `o.*' matches any instance of the letter `o' at the beginning of a line followed by any number (including zero) of any characters.
We can also use the expression operator `|' to signify a logical
OR, such that
query-pr --state="o|a"
matches all `open' or `analyzed' Problem Reports. (Double quotes (") are used to protect the pipe symbol (|) from the shell.)
By the same token,(5) using
query-pr --state=".*a"
matches all values for `>State:' which contain an `a'. (These include `analyzed' and `feedback'.)
Another way to understand what wildcards do is to follow them on their search for matching text. By our syntax, `.*' matches any character any number of times, including zero. Therefore, `.*a' searches for any group of characters which end with `a', ignoring the rest of the field. `.*a' matches `analyzed' (stopping at the first `a') as well as `feedback'.
Note: When using `--text' or `--multitext', you do not have to specify the token `.*' at the beginning of text to match the entire field. For the technically minded, this is because `--text' and `--multitext' use `re_search' rather than `re_match'. `re_match' anchors the search at the beginning of the field, while `re_search' does not anchor the search.
For example, to search in the >Description: field for the text
The defrobulator component returns a nil value.
we can use
query-pr --multitext="defrobulator.*nil"
To also match newlines, we have to include the expression `(.|^M)' instead of just a dot (`.'). `(.|^M)' matches "any single character except a newline (`.') or (`|') any newline (`^M')." This means that to search for the text
The defrobulator component enters the bifrabulator routine and returns a nil value.
we must use
query-pr --multitext="defrobulator(.|^M)*nil"
To generate the newline character `^M', type the following depending on your shell:
csh
tcsh
sh (or bash)
(.| )
Again, see section `Regular Expression Syntax' in Regex, for a much more complete discussion on regular expression syntax.
>Arrival-Date:
>Audit-Trail:
>Category:
>Class:
>Confidential:
>Description:
>Environment:
>Fix:
>How-To-Repeat:
>Number:
>Organization:
>Originator:
>Priority:
>Release:
>Responsible:
>Severity:
>State:
>Submitter-Id:
>Synopsis:
>Unformatted:
ACKNOWLEDGE
Arrival-Date field
at
at-pr
Audit-Trail field
autoload commands
send-pr
categories file
Category field
Class field
Confidential field
config file
configure
send-pr for the outside world
cron
crontab
current file
DEFAULT_ORGANIZATION
DEFAULT_RELEASE
DEFAULT_SUBMITTER
Description field
edit-pr
gnats-admin
edit-pr
edit-pr driver
edit-pr from the shell
edit-pr in Emacs
pending directory
Environment field
file-pr
Fix field
From: header
gen-index
gnats-admin alias
GNATS_ADDR
GNATS_ADMIN
GNATS_SITE
How-To-Repeat field
index file
edit-pr
mkdist
query-pr
send-pr
send-pr from Emacs
send-pr from the shell
KEEP_RECEIVED_HEADERS
.el files
make
mkcat
mkdist
NOTIFY
Number field
Organization field
Originator field
pending directory
pending file
pr-addr
pr-edit
Priority field
query-pr
query-pr by mail
queue-pr
queue-pr -q
Received-By: headers
Release field
Reply-To: header
send-pr
Responsible field
responsible file
Responsible-Changed-<From>-<To>: in >Audit-Trail:
Responsible-Changed-By: in >Audit-Trail:
Responsible-Changed-When: in >Audit-Trail:
Responsible-Changed-Why: in >Audit-Trail:
rmcat
send-pr
send-pr fields
send-pr within Emacs
Severity field
State field
State-Changed-<From>-<To>: in >Audit-Trail:
State-Changed-By: in >Audit-Trail:
State-Changed-When: in >Audit-Trail:
State-Changed-Why: in >Audit-Trail:
Subject: header
SUBMITTER
Submitter-Id field
submitters file
Synopsis field
To: header
Unformatted field
edit-pr
mkdist
query-pr
send-pr
send-pr from within Emacs
view-pr in Emacs
with-full-gnats