This is Info file ../../info/gnats.info, produced by Makeinfo version 1.68 from the input file gnats.texi. START-INFO-DIR-ENTRY * Keeping Track: (gnats). GNU Problem Report Management System END-INFO-DIR-ENTRY Copyright (C) 1993, 1995 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.  File: gnats.info, Node: rmcat, Next: gen-index, Prev: mkcat, Up: Admin utils Removing a problem category --------------------------- To remove a category from the database: 1. Remove the Problem Reports from the subdirectories corresponding to the categories you wish to remove, or assign the PRs to new categories. All PRs for a given category reside in `GNATS_ROOT/CATEGORY'. Make sure you do this for each category you wish to remove. 2. Run `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' (*note Where GNATS lives: Locations.). *Note:* `rmcat' does not update the categories list for other machines on your network which have `send-pr' installed. *Note Managing GNATS over a network: Networked management. 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 (*note Configuring `send-pr' for the outside world: mkdist.).  File: gnats.info, Node: gen-index, Next: mkdist, Prev: rmcat, Up: Admin utils Regenerating the index ---------------------- 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 ] [ -c FILENAME | --catfile=FILENAME ] [ -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' Sorts index entries numerically. `-d DIRECTORY' `--directory=DIRECTORY' Uses DIRECTORY as the directory containing the database, by default GNATS_ROOT (*note Where GNATS lives: Locations.). `-o FILENAME' `--outfile=FILENAME' Places output in FILENAME rather than sending it to standard output. `-c FILENAME' `--catfile=FILENAME' Point to FILENAME, the file listing the valid categories. `-h' `--help' Prints the usage for `gen-index'. `-V' `--version' Prints the version number for `gen-index'.  File: gnats.info, Node: mkdist, Prev: gen-index, Up: Admin utils Configuring `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 --release=RELEASE DIST-DIRECTORY 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 --release=tools-1.2 new-dist 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'. If you only have one submitter, you can set the Submitter ID in the send-pr script by specifying the -submitter option to mkdist. If you do this, the submitter will not have to run install-sid.  File: gnats.info, Node: Internal utils, Prev: Admin utils, Up: Management Internal utilities ================== 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. * Menu: * queue-pr:: Handling incoming traffic * file-pr:: Processing incoming traffic * at-pr:: Timely reminders * pr-edit:: The edit-pr driver * pr-addr:: Address retrieval  File: gnats.info, Node: queue-pr, Next: file-pr, Up: Internal utils Handling incoming traffic ------------------------- 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. *Note Installing GNATS: Installation. 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' Accepts standard input as an incoming mail message, placing this message in an incrementally numbered file in the `gnats-queue' directory under `GNATS_ROOT' (*note Where GNATS lives: Locations.). `-r' `--run' Redirects files in the `gnats-queue' directory into the program `file-pr' one by one. `-f FILENAME' `--file=FILENAME' Used with `-q' (or `--queue'), accepts the file denoted by FILENAME as input rather than reading from standard input. `-d DIRECTORY' `--directory=DIRECTORY' Resets the default DIRECTORY value, which is by default `GNATS_ROOT/gnats-queue'. When `-d DIRECTORY' is used in conjunction with the `-q' (or `--queue') option, `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.  File: gnats.info, Node: file-pr, Next: at-pr, Prev: queue-pr, Up: Internal utils Processing incoming traffic --------------------------- `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; *note The `categories' file: categories.), 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 (*note The `categories' file: categories.) and the person responsible for the submitter site where the PR originated (*note The `submitters' file: submitters.) 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 (*note Changing your local configuration: Local configuration.). The usage for `file-pr' is as follows: file-pr [ -f FILENAME | --file=FILENAME ] [ -d DIRECTORY | --directory=DIRECTORYb ] [ -D | --debug ] [ -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' Uses FILENAME as input rather than standard input. `-d DIRECTORY' `--directory=DIRECTORY' Performs refiling operations in DIRECTORY rather than in `GNATS_ROOT'. `-D' `--debug' Give debugging output while `file-pr' is running. `-h' `--help' Prints the usage for `file-pr'. `-V' `--version' Prints the version number for `file-pr'.  File: gnats.info, Node: at-pr, Next: pr-edit, Prev: file-pr, Up: Internal utils Timely reminders ---------------- `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:' (*note The `submitters' file: submitters.). 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 (*note The `config' file: config.). 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)  File: gnats.info, Node: pr-edit, Next: pr-addr, Prev: at-pr, Up: Internal utils The `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 ] [ -L | --lockdb ] [ -U | --unlockdb ] [ -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(1). 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' Locks Problem Report GNATS-ID, failing (and returning an error message) if GNATS-ID is already locked, or if GNATS-ID does not exist. `pr-edit' requires that you specify GNATS-ID when using this option. `-u' `--unlock' Unlocks Problem Report GNATS-ID. `pr-edit' requires that you specify GNATS-ID when using this option. You must own a file lock to remove it. `-L' `--lockdb' Locks the GNATS database as a whole. This will prevent any modification to any part of the system while it's locked. `-U' `--unlockdb' Unlocks the GNATS database as a whole, allowing modification of its files. `-c' `--check' Checks the Problem Report in GNATS-ID (or standard input, if GNATS-ID is not present) for correct information in its ENUMERATED fields. `pr-edit' complains about any bogus information in the Problem Report. `-F' Forces the PR to be submitted to the database, even if there is no current index entry for it (i.e., even if the PR did not exist in the database previously). *Warning: using this option may corrupt your index.* If you use it, be sure you know what you are doing. `-f FILENAME' `--filename=FILENAME' Reads FILENAME rather than standard input. `-d DIRECTORY' `--directory=DIRECTORY' Resets the operating directory (`GNATS_ROOT'). `-h' `--help' Prints the usage for `pr-edit'. `-V' `--version' Prints the version number for `pr-edit'. ---------- Footnotes ---------- (1) This approach may seem heavy-handed, but it ensures that changes are not overwritten.  File: gnats.info, Node: pr-addr, Prev: pr-edit, Up: Internal utils Address retrieval ----------------- Returns an electronic mail address when given a valid "nametag", as it appears in the `responsible' file (*note The `responsible' file: responsible.). If NAMETAG is not valid, `pr-addr' will tell the user that it could not find the requested address. Usage is simply: pr-addr NAME  File: gnats.info, Node: Installation, Next: Locations, Prev: Management, Up: Top Installing GNATS **************** *Note Where the tools and utilities reside: Locations. 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 *Note Upgrading from older versions: Upgrading. To build GNATS, you must: * Run `configure', with correct options if the defaults are unsuitable for your site. *Note Configuring and compiling the software: Configure and make. Default installation locations are in *Note Where GNATS lives: Locations. * Compile the GNATS programs on your system. *Note Configuring and compiling the software: Configure and make. * Install the GNATS tools and utilities locally, and install the user tools on every machine in your local network. *Note Installing the utilities: Installing utils. * Set up mail aliases for GNATS. *Note Setting up mail aliases: Aliases. * Install the GNATS user tools (`query-pr', `nquery-pr', `edit-pr', `send-pr') around your network. *Note Installing the user tools: Installing tools. * Install the GNATS daemon `gnatsd'. * Update the local configuration files config categories submitters responsible gnatsd.conf in `GNATS_ROOT/gnats-adm'. *Note Changing your local configuration: Local configuration. * Create a distribution of `send-pr' for submitters outside your organization. *Note Configuring `send-pr' for the outside world: mkdist. * Menu: * Configure and make:: Configuring and compiling the software * Installing utils:: Installing the utilities * Aliases:: Setting up mail aliases * Installing the daemon:: Installing the daemon * Installing tools:: Installing the user tools * Upgrading:: Upgrading from older versions  File: gnats.info, Node: Configure and make, Next: Installing utils, Up: Installation Configuring and compiling the software ====================================== 1. First, unpack your distribution. We provide source code in a `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.101.tar.z The sources reside in a directory called `gnats-3.101' 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.101/gnats/*'. Lists of files included in the distribution are in each directory in the file `MANIFEST'. 2. You may wish to alter the installation directory for the Emacs lisp files. If your Emacs lisp library is not in `PREFIX/lib/emacs/lisp', edit the files SRCDIR/gnats/Makefile.in *and* SRCDIR/send-pr/Makefile.in Change the variable `lispdir' from `$(datadir)/emacs/lisp' to the directory containing your Emacs lisp library. For information on PREFIX, see *Note PREFIX: prefix. 3. Run `configure'. You can nearly always run `configure' with the command ./configure --with-full-gnats and the "Right Thing" happens: * GNATS is configured in the same directory you unpacked it in; * when built, GNATS runs on the machine you're building it on; * when installed, files are installed under `/usr/local' (*note Where GNATS lives: Locations.). * GNATS operates by default behavior (*note Default behavior: default behavior.). The full usage for `configure' is: configure [ --with-full-gnats ] [ --prefix=PREFIX ] [ --exec-prefix=EXEC-PREFIX ] [ --with-gnats-root=GNATS_ROOT ] [ --with-gnats-server=HOSTNAME ] [ --with-gnats-service=SERVICE-NAME ] [ --with-gnats-user=USERNAME ] [ --with-gnats-port=PORT-NUMBER ] [ --verbose ] `--with-full-gnats' All programs are to be built; this includes the user utilities, the administrative utilities, and the internal utilities. Use this when configuring the utilities for the machine where GNATS is to run. Omit it when building only the user utilities for other machines on your network; see *Note Installing the user tools: Installing tools. `--prefix=PREFIX' All host-independent programs and files are to be installed under PREFIX. (Host-dependent programs and files are also installed in PREFIX by default.) The default for PREFIX is `/usr/local'. *Note Where GNATS lives: Locations. `--exec-prefix=EXEC-PREFIX' All host-dependent programs and files are to be installed under EXEC-PREFIX. The default for EXEC-PREFIX is PREFIX. *Note Where GNATS lives: Locations. `--with-gnats-root=GNATS_ROOT' The database and its data files are to be installed into GNATS_ROOT. The default for GNATS_ROOT is `PREFIX/lib/gnats/gnats-db'. *Note Where GNATS lives: Locations. `--with-gnats-root=hostname' FIXME `--with-gnats-root=SERVICE-NAME' FIXME `--with-gnats-user=USERNAME' FIXME `--with-gnats-port=PORT-NUMBER' FIXME `--verbose' Give verbose output while `configure' runs. *Note Using `configure': (configure)Using 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 all By 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. 4. Run make all info from the directory where `configure' created a `Makefile'. (This may not be the same directory as the source directory.) These targets indicate: `all' Compile all programs `info' Create `info' files using `makeinfo'.  File: gnats.info, Node: Installing utils, Next: Aliases, Prev: Configure and make, Up: Installation Installing the utilities ======================== The following steps are necessary for a complete installation. You may need `root' access for these. 1. Install the utilities by invoking make install install-info These targets indicate: `install' Installs all programs into their configured locations (*note Where GNATS lives: Locations.). `install-info' Installs `info' files into their configured locations (*note Where GNATS lives: Locations.). After you have installed GNATS, you can remove the object files with make clean 2. Place the following lines in the file `default.el' in your Emacs lisp library, or instruct your local responsible parties to place the lines in their local editions of `.emacs': (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. 3. Create an account for a user named GNATS. This user must have an entry in the file `/etc/passwd'. The home directory for this account should be the same directory you specified for GNATS_ROOT in the file `Makefile.in'. Also, the default `PATH' for this user should contain `EXEC-PREFIX/bin' and `EXEC-PREFIX/lib/gnats'. 4. Allow the new user `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'. * Edit the files `categories', `responsible', and `submitters' in the directory `GNATS_ROOT/gnats-adm' (*note Changing your local configuration: Local configuration.) to reflect your local needs. Be sure to run `mkcat' after you update the `categories' file (*note Adding a new problem category: mkcat.). *Note:* these templates are not installed if they already exist, i.e. if you are upgrading. *Note Upgrading from older versions: Upgrading. * If you wish to install the GNATS user tools on other machines on your network, see *Note Installing the user tools: Installing tools. 5. Create a `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 .mycron See the `man' pages for `cron' and `crontab' for details on using `cron'.  File: gnats.info, Node: Aliases, Next: Installing the daemon, Prev: Installing utils, Up: Installation Setting up mail aliases ======================= 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. * Create an alias for the GNATS administrator. This address should point to the address of the person in charge of administrating GNATS: gnats-admin: ADDRESS * Create an alias to redirect incoming Problem Reports. This alias should redirect incoming mail via a "pipe" to the program `queue-pr -q'. For example, if Problem Reports coming to your site are to arrive at the address `bugs@your.company.com', create an alias to the effect of: bugs: "| EXEC-PREFIX/lib/gnats/queue-pr -q" This places incoming Problem Reports in `GNATS_ROOT/gnats-queue'. * Create an alias for your site. This alias should be the same nametag indicated by the variable `GNATS_SITE' in the file `GNATS_ROOT/gnats-adm/config' (*note The `config' file: config.), 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: bugs The report submission utility `send-pr' automatically appends the `-gnats' to any arguments you specify (*note Submitting Problem Reports: send-pr.). 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 * You may also wish to forward a copy of each incoming Problem Report to a log. This can be accomplished with something like: bug-q: "| EXEC-PREFIX/lib/gnats/queue-pr -q" bug-log: GNATS_ROOT/gnats-adm/bugs.log bugs: bug-q, bug-log This 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; *note GNATS Administration: Management..) * If you want your users to be able to query the database by mail, use the following alias: query-pr: "| EXEC-PREFIX/lib/gnats/mail-query" The `mail-query' program uses `--restricted' to search on the database, and by default only searches for PRs that aren't closed (*note Querying the database: query-pr.).  File: gnats.info, Node: Installing the daemon, Next: Installing tools, Prev: Aliases, Up: Installation Installing the daemon ===================== By default, the daemon and clients are set to use port 1529. Add the line support 1529/tcp # GNATS to your `/etc/services' file. If you want a different port, or a different service name or port, configure GNATS with --with-gnats-service=SERVICENAME --with-gnats-port=PORTNUMBER In your `inetd.conf' file, add the line support stream tcp nowait gnats /usr/local/lib/gnats/gnatsd gnatsd adjusting the path accordingly. To make inetd start spawning the GNATS daemon when connected on that port, send it a hangup signal (`HUP'). By default, the server for the GNATS daemon is assumed to be one with the name of `gnats'. If you'd like something else, use --with-gnats-server=HOSTNAME In the `gnats-adm' directory, you'll want to edit `gnatsd.conf'. It lists the hosts allowed to access your server. Or, if you're using Kerberos, it shows the sites that don't require Kerberos authentication. The format is reserved for future revision; only the first field is actually used: site.com:: The second field may be used for things like controlling what categories, submitter-id'd PRs, etc., can be accessed from that site. In the file that logs syslog messages (`/var/adm/messages', for example) you'll find the notification of denied access.  File: gnats.info, Node: Installing tools, Next: Upgrading, Prev: Installing the daemon, Up: Installation Installing the user tools ========================= 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. 1. Make sure that the directory where GNATS resides is mounted to each system that will need access to it, so GNATS_ROOT will be the same for each host. (You can do this with symbolic links as well.) 2. Either mount the disk which contains your source directory, or make a copy of the GNATS source code tree in a separate directory on each system you wish to build on. 3. Run `configure', *without* specifying `--with-full-gnats', and using the same argument (if any) for the option --with-gnats-root=GNATS_ROOT that you specified when building the GNATS utilites (*note Configuring and compiling the software: Configure and make.). 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.* 4. Create an account for a user named GNATS on the new host. This user must have an entry in the file `/etc/passwd'. The user ID for `gnats' must be the same as on the main GNATS host. 5. Run make all info install install-info This 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; *note EXEC-PREFIX: 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' 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' (*note Configuring and compiling the software: Configure and make.). 6. Add the following lines to the file `default.el' in the Emacs lisp repository on the new host, or instruct your responsible parties who use these hosts to add them to their `.emacs' files: (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) 7. Copy the file `PREFIX/lib/gnats/SITE' from the original host to the new host (which may have a different value for PREFIX). This is the list of valid categories that `send-pr' uses (*note Where GNATS lives: Locations.). SITE is your local site, the value of `GNATS_SITE' in the `config' file (*note The `config' file: config.).  File: gnats.info, Node: Upgrading, Prev: Installing tools, Up: Installation Upgrading from older versions ============================= 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: * Specify your current GNATS_ROOT on the command line to `configure' when you build the new tools, with configure --with-full-gnats --with-gnats-root=GNATS_ROOT (*Note Configuring and compiling the software: Configure and make.) * Remove the directory `gnats-bin' from GNATS_ROOT; it is no longer used. * Update your current mail aliases to reflect that `queue-pr' now resides in `EXEC-PREFIX/lib/gnats' rather than `GNATS_ROOT/gnats-bin' (*note Where GNATS lives: Locations.). * Change the default `PATH' for the `gnats' user to search the directories `EXEC-PREFIX/bin' and `EXEC-PREFIX/lib/gnats'. * Reinstall the GNATS user tools on all other hosts on your network (*note Installing the user tools: Installing tools.). * Redistribute `send-pr' to your Submitter Sites (*note Configuring `send-pr' for the outside world: mkdist.). 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.  File: gnats.info, Node: Locations, Next: Regexps, Prev: Installation, Up: Top Where GNATS lives ***************** We use a few conventions when referring to the installation structure GNATS uses. These values are adjustable when you build and install GNATS (*note Installing GNATS: Installation.). * Menu: * prefix:: * exec-prefix:: * GNATS_ROOT:: * defaults:: Default installation locations  File: gnats.info, Node: prefix, Next: exec-prefix, Up: Locations PREFIX ====== 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: libraries `PREFIX/lib' `man' pages `PREFIX/man' `info' documents `PREFIX/info' `include' files `PREFIX/include' *etc...* The default value for PREFIX is `/usr/local', which can be changed on the command line to `configure' using configure --prefix=PREFIX ... *Note Configuring and compiling the software: Configure and make.  File: gnats.info, Node: exec-prefix, Next: GNATS_ROOT, Prev: prefix, Up: Locations EXEC-PREFIX =========== 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: binary tools `EXEC-PREFIX/bin' binary support utilities `EXEC-PREFIX/lib/gnats' compiled libraries `EXEC-PREFIX/lib' *etc...* 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*. *Note Configuring and compiling the software: Configure and make. 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 *Note Using `configure': (configure)Using configure, before attempting this. Again, *it is not necessary to use this paradigm when building the GNATS tools*.  File: gnats.info, Node: GNATS_ROOT, Next: defaults, Prev: exec-prefix, Up: Locations GNATS_ROOT ========== 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'. *Note Changing your local configuration: Local configuration, and *Note Administrative data files: Admin files.  File: gnats.info, Node: defaults, Prev: GNATS_ROOT, Up: Locations Default installation locations ============================== PREFIX defaults to `/usr/local'; change using `configure' (*note Configuring and compiling the software: Configure and make.). EXEC-PREFIX defaults to PREFIX; change using `configure' (*note Configuring and compiling the software: Configure and make.). GNATS_ROOT defaults to `PREFIX/lib/gnats/gnats-db'; change using `configure' (*note Configuring and compiling the software: Configure and make.). GNATS installs tools, utilities, and files into the following locations. `EXEC-PREFIX/bin' `send-pr' *Note Submitting Problem Reports: send-pr. `edit-pr' *Note Editing existing Problem Reports: edit-pr. `query-pr' *Note Querying the database: query-pr. `nquery-pr' *Note Querying the database over the network: query-pr. `EXEC-PREFIX/lib/gnats' `mkcat' *Note Adding a problem category: mkcat. `rmcat' *Note Removing a problem category: rmcat. `mkdist' *Note Configuring `send-pr' for the outside world: mkdist. `gen-index' *Note Regenerating the index: gen-index. `queue-pr' *Note Handling incoming traffic: queue-pr. `file-pr' *Note Processing incoming traffic: file-pr. `at-pr' *Note Timely reminders: at-pr. `pr-edit' *Note The `edit-pr' driver: pr-edit. `pr-addr' *Note Address retrieval: pr-addr. `libiberty.a' The GNU `libiberty' library. `PREFIX/lib/gnats/dist' A packageable distribution of `send-pr'. *Note Configuring `send-pr' for the outside world: mkdist. `PREFIX/lib/gnats' SITE The local list of valid categories, used by `send-pr'; SITE is the value of `GNATS_SITE' (*note The `config' file: config.). `PREFIX/lib/emacs/lisp' `gnats.el' `gnats.elc' The Emacs versions of the programs `query-pr', `edit-pr', and `view-pr'. *Note Invoking the GNATS tools: Invoking the tools. To change this directory you must alter `Makefile.in'; see *Note Configuring and compiling the software: Configure and make. `send-pr.el' The Emacs version of the program `send-pr'. *Note Submitting Problem Reports: send-pr. `PREFIX/info' `gnats.info' `send-pr.info' The GNATS manuals, in a form readable by `info' (the GNU hypertext browser). *Note Reading GNU Online Documentation: (infoman)Info. `PREFIX/man/man1' `PREFIX/man/man8' `man' pages for all the GNATS tools and utilities. *Note Invoking the GNATS tools: Invoking the tools. `PREFIX/src' Source code for GNATS. `PREFIX/sample' Example administrative files, including `categories', `submitters', `responsible', and `config'. *Note Changing your local configuration: Local configuration. `GNATS_ROOT' `gnats-adm' Administration and configuration data files. The files `config' `categories' `submitters' `responsible' `gnatsd.conf' `index' (*This file is created by GNATS.*) `current' (*This file is created by GNATS.*) exist here. *Note Changing your local configuration: Local configuration, and *Note Administrative data files: Admin files. `gnats-queue' Incoming Problem Reports are queued here until the next iteration of `queue-pr -r' (*note Handling incoming traffic: queue-pr.). `pending' Problem Reports which arrive without a valid category value are reassigned to the category `pending' and placed here pending intervention by the GNATS administrator. *Note GNATS administration: Management. `CATEGORY' Each valid category has a corresponding subdirectory in the database. All Problem Reports associated with that category are kept in that subdirectory, along with lock files for PRs which are being edited.  File: gnats.info, Node: Regexps, Next: Index, Prev: Locations, Up: Top Querying using regular expressions ********************************** 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. *Note Regular Expression Syntax: (regex)Regular Expression Syntax, for details on regular expression syntax. Also see *Note Syntax of Regular Expressions: (emacs)Regexps, 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,(1) 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' `*control*-V *control*-M' `tcsh' `*control*-V *control*-J' `sh (*or* bash)' Use the key, as in (.| ) Again, see *Note Regular Expression Syntax: (regex)Regular Expression Syntax, for a much more complete discussion on regular expression syntax. ---------- Footnotes ---------- (1) No pun intended.