Contents: Reporting bugs Bug checklist Mailing lists Debugging Logging Common problems Unable to find files Slow path searching Unable to generate fonts TeX or Metafont failing Empty Makefiles `XtStrings' `dlopen' `ShellWidgetClass' Pointer combination warnings Reporting bugs ============== If you have problems or suggestions, please report them to using the bug checklist below. Please report bugs in the documentation; not only factual errors or inconsistent behavior, but unclear or incomplete explanations, typos, wrong fonts, ... Bug checklist ------------- Before reporting a bug, please check below to be sure it isn't already known (*note Common problems::.). Bug reports should be sent via electronic mail to , or by postal mail to 135 Center Hill Road / Plymouth, MA 02360 / USA. The general principle is that a good bug report includes all the information necessary for reproduction. Therefore, to enable investigation, your report should include the following: * The version number(s) of the program(s) involved, and of Kpathsea itself. You can get the former by giving a sole option `--version' to the program, and the latter by running `kpsewhich --version'. The `NEWS' and `ChangeLog' files also contain the version number. * The hardware, operating system (including version number), compiler, and `make' program you are using (the output of `uname -a' is a start on the first two, though often incomplete). If the bug involves the X window system, include X version and supplier information as well (examples: X11R6 from MIT; X11R4 from HP; OpenWindows 3.3 bundled with SunOS 4.1.4). * Any options you gave to `configure'. This is recorded in the `config.status' files. If you are reporting a bug in `configure' itself, it's probably system-dependent, and it will be unlikely the maintainers can do anything useful if you merely report that thus-and-such is broken. Therefore, you need to do some additional work: for some bugs, you can look in the file `config.log' where the test that failed should appear, along with the compiler invocation and source program in question. You can then compile it yourself by hand, and discover why the test failed. Other `configure' bugs do not involve the compiler; in that case, the only recourse is to inspect the `configure' shell script itself, or the Autoconf macros that generated `configure'. * The log of all debugging output, if the bug is in path searching. You can get this by setting the environment variable `KPATHSEA_DEBUG' to `-1' before running the program. Please look at the log yourself to make sure the behavior is really a bug before reporting it; perhaps "old" environment variable settings are causing files not to be found, for example. * The contents of any input files necessary to reproduce the bug. For bugs in DVI-reading programs, for example, this generally means a DVI file (and any EPS or other files it uses)--TeX source files are helpful, but the DVI file is necessary, because that's the actual program input. GNU `shar', available from `ftp://prep.ai.mit.edu/pub/gnu' is a convenient way of packaging multiple (possibly binary) files for electronic mail. If you feel your input files are too big to send by email, you can ftp them to `ftp://ftp.tug.org/incoming' (that directory is writable, but not readable). * If you are sending a patch (do so if you can!), please do so in the form of a context diff (`diff -c') against the original distribution source. Any other form of diff is either not as complete or harder for me to understand. Please also include a `ChangeLog' entry. * If the bug involved is an actual crash (i.e., core dump), it is easy and useful to include a stack trace from a debugger (I recommend the GNU debugger GDB, available from `ftp://prep.ai.mit.edu/pub/gnu'). If the cause is apparent (a `NULL' value being dereferenced, for example), please send the details along. If the program involved is TeX or Metafont, and the crash is happening at apparently-sound code, however, the bug may well be in the compiler, rather than in the program or the library (*note TeX or Metafont failing: TeX or Metafont failing.). * Any additional information that will be helpful in reproducing, diagnosing, or fixing the bug. Mailing lists ------------- Web2c and Kpathsea in general are discussed on the mailing list . To join, email with a line consisting of subscribe YOU@YOUR.PREFERRED.EMAIL.ADDRESS in the body of the message. You do not need to join to submit a report, nor will it affect whether you get a response. There is no Usenet newsgroup equivalent (if you can be the one to set this up, email `tex-k-request'). Traffic on the list is fairly light, and is mainly bug reports and enhancement requests to the software. The best way to decide if you want to join or not is read some of the archives from `ftp://ftp.tug.org/mail/archives/tex-k/'. Be aware that large data files are sometimes included in bug reports. If this is a problem for you, do not join the list. If you only want announcements of new releases, not bug reports and discussion, join (via mail to ). If you are looking for general TeX help, such as how to use LaTeX, please use the mailing list mailing list, which is gatewayed to the `comp.text.tex' Usenet newsgroup (or post to the newsgroup; the gateway is bidirectional). Debugging --------- Kpathsea provides a number of runtime debugging options, detailed below by their names and corresponding numeric values. When the files you expect aren't being found, the thing to do is enable these options and examine the output. You can set these with some runtime argument (e.g., `-d') to the program; in that case, you should use the numeric values described in the program's documentation (which, for Dvipsk and Xdvik, are different than those below). It's best to give the `-d' (or whatever) option first, for maximal output. Dvipsk and Xdvik have additional program-specific debugging options as well. You can also set the environment variable `KPATHSEA_DEBUG'; in this case, you should use the numbers below. If you run the program under a debugger and set the variable `kpathsea_debug', also use the numbers below. In any case, by far the simplest value to use is `-1', which will turn on all debugging output. This is usually better than guessing which particular values will yield the output you need. Debugging output always goes to standard error, so you can redirect it easily. For example, in Bourne-compatible shells: dvips -d -1 ... 2>/tmp/debug It is sometimes helpful to run the standalone Kpsewhich utility (*note Invoking kpsewhich::.), instead of the original program. In any case, you can *not* use the *names* below; you must always use somebody's numbers. (Sorry.) To set more than one option, just sum the corresponding numbers. `KPSE_DEBUG_STAT (1)' Report `stat'(2) calls. This is useful for verifying that your directory structure is not forcing Kpathsea to do many additional file tests (*note Slow path searching::., and *note Subdirectory expansion::.). If you are using an up-to-date `ls-R' database (*note Filename database::.), this should produce no output unless a nonexistent file that must exist is searched for. `KPSE_DEBUG_HASH (2)' Report lookups in all hash tables: `ls-R' and `aliases' (*note Filename database::.); font aliases (*note Fontmap::.); and config file values (*note Config files::.). Useful when expected values are not being found, e.g.., file searches are looking at the disk instead of using `ls-R'. `KPSE_DEBUG_FOPEN (4)' Report file openings and closings. Especially useful when your system's file table is full, for seeing which files have been opened but never closed. In case you want to set breakpoints in a debugger: this works by redefining `fopen' (`fclose') to be `kpse_fopen_trace' (`kpse_fclose_trace'). `KPSE_DEBUG_PATHS (8)' Report general path information for each file type Kpathsea is asked to search. This is useful when you are trying to track down how a particular path got defined--from `texmf.cnf', `config.ps', an environment variable, the compile-time default, etc. This is the contents of the `kpse_format_info_type' structure defined in `tex-file.h'. `KPSE_DEBUG_EXPAND (16)' Report the directory list corresponding to each path element Kpathsea searches. This is only relevant when Kpathsea searches the disk, since `ls-R' searches don't look through directory lists in this way. `KPSE_DEBUG_SEARCH (32)' Report on each file search: the name of the file searched for, the path searched in, whether or not the file must exist (when drivers search for `cmr10.vf', it need not exist), and whether or not we are collecting all occurrences of the file in the path (as with, e.g., `texmf.cnf' and `texfonts.map'), or just the first (as with most lookups). This can help you correlate what Kpathsea is doing with what is in your input file. `KPSE_DEBUG_VARS (64)' Report the value of each variable Kpathsea looks up. This is useful for verifying that variables do indeed obtain their correct values. `GSFTOPK_DEBUG (128)' Activates debugging printout specific to `gsftopk' program. `MAKETEX_DEBUG (512)' If you use the optional `mktex' programs instead of the traditional shell scripts, this will report the name of the site file (`mktex.cnf' by default) which is read, directories created by `mktexdir', the full path of the `ls-R' database built by `mktexlsr', font map searches, `MT_FEATURES' in effect, parameters from `mktexnam', filenames added by `mktexupd', and some subsidiary commands run by the programs. `MAKETEX_FINE_DEBUG (1024)' When the optional `mktex' programs are used, this will print additional debugging info from functions internal to these programs. Debugging output from Kpathsea is always written to standard error, and begins with the string `kdebug:'. (Except for hash table buckets, which just start with the number, but you can only get that output running under a debugger. See comments at the `hash_summary_only' variable in `kpathsea/db.c'.) Logging ------- Kpathsea can record the time and filename found for each successful search. This may be useful in finding good candidates for deletion when your filesystem is full, or in discovering usage patterns at your site. To do this, define the environment or config file variable `TEXMFLOG'. The value is the name of the file to append the information to. The file is created if it doesn't exist, and appended to if it does. Each successful search turns into one line in the log file: two words separated by a space. The first word is the time of the search, as the integer number of seconds since "the epoch", i.e., UTC midnight 1 January 1970 (more precisely, the result of the `time' system call). The second word is the filename. For example, after `setenv TEXMFLOG /tmp/log', running Dvips on `story.dvi' appends the following lines: 774455887 /usr/local/share/texmf/dvips/config.ps 774455887 /usr/local/share/texmf/dvips/psfonts.map 774455888 /usr/local/share/texmf/dvips/texc.pro 774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk 774455889 /usr/local/share/texmf/dvips/texc.pro Only filenames that are absolute are recorded, to preserve some semblance of privacy. Common problems --------------- Here are some common problems with configuration, compilation, linking, execution, ... Unable to find files .................... If a program complains it cannot find fonts (or other input files), any of several things might be wrong. In any case, you may find the debugging options helpful. *Note Debugging::. * Perhaps you simply haven't installed all the necessary files; the basic fonts and input files are distributed separately from the programs. *Note unixtex.ftp::. * You have (perhaps unknowingly) told Kpathsea to use search paths that don't reflect where the files actually are. One common cause is having environment variables set from a previous installation, thus overriding what you carefully set in `texmf.cnf' (*note Supported file formats::.). System `/etc/profile' or other files such may be the culprit. * Your files reside in a directory that is only pointed to via a symbolic link, in a leaf directory and is not listed in `ls-R'. Unfortunately, Kpathsea's subdirectory searching has an irremediable deficiency: If a directory D being searched for subdirectories contains plain files and symbolic links to other directories, but no true subdirectories, D will be considered a leaf directory, i.e., the symbolic links will not be followed. *Note Subdirectory expansion::. You can work around this problem by creating an empty dummy subdirectory in D. Then D will no longer be a leaf, and the symlinks will be followed. The directory immediately followed by the `//' in the path specification, however, is always searched for subdirectories, even if it is a leaf. Presumably you would not have asked for the directory to be searched for subdirectories if you didn't want it to be. * If the fonts (or whatever) don't already exist, `mktexpk' (or `mktexmf' or `mktextfm') will try to create them. If these rather complicated shell scripts fail, you'll eventually get an error message saying something like `Can't find font FONTNAME'. The best solution is to fix (or at least report) the bug in `mktexpk'; the workaround is to generate the necessary fonts by hand with Metafont, or to grab them from a CTAN site (*note unixtex.ftp::.). * There is a bug in the library. *Note Reporting bugs::. Slow path searching ................... If your program takes an excessively long time to find fonts or other input files, but does eventually succeed, here are some possible culprits: * Most likely, you just have a lot of directories to search, and that takes a noticeable time. The solution is to create and maintain a separate `ls-R' file that lists all the files in your main TeX hierarchy. *Note Filename database::. Kpathsea always uses `ls-R' if it's present; there's no need to recompile or reconfigure any of the programs. * Your recursively-searched directories (e.g., `/usr/local/share/texmf/fonts//'), contain a mixture of files and directories. This prevents Kpathsea from using a useful optimization (*note Subdirectory expansion::.). It is best to have only directories (and perhaps a `README') in the upper levels of the directory structure, and it's very important to have *only* files, and no subdirectories, in the leaf directories where the dozens of TFM, PK, or whatever files reside. In any case, you may find the debugging options helpful in determining precisely when the disk or network is being pounded. *Note Debugging::. Unable to generate fonts ........................ This can happen if either `mktexpk' hasn't been installed properly, or if the local installation of Metafont isn't correct. If `mf' is a command not found by `mktexpk', then you need to install Metafont (*note unixtex.ftp::.). If Metafont runs, but generates fonts at the wrong resolution, you need to be sure the `M' and `D' lines in your Dvips configuration file match (*note Config files: (dvips)Config files.). For example, if `mktexpk' is generating 300dpi fonts, but you need 600dpi fonts, you should have: M ljfour D 600 If Metafont runs but generates fonts at a resolution of 2602dpi (and prints out the name of each character as well as just a character number, and maybe tries to display the characters), then your Metafont base file probably hasn't been made properly. (It's using the default `proof' mode, instead of an actual device mode.) To make a proper `plain.base', assuming the local mode definitions are contained in a file `modes.mf', run the following command (assuming Unix): inimf "plain; input modes; dump" Then copy the `plain.base' file from the current directory to where the base files are stored on your system (`/usr/local/share/texmf/web2c' by default), and make a link (either hard or soft) from `plain.base' to `mf.base' in that directory. *Note inimf invocation: (web2c)inimf invocation. TeX or Metafont failing ....................... If TeX or Metafont get a segmentation fault or otherwise fail while running a normal input file, the problem is usually a compiler bug (unlikely as that may sound). Even if the trip and trap tests are passed, problems may lurk. Optimization occasionally causes trouble in programs other than TeX and Metafont themselves, too. Insufficient swap space may also cause core dumps or other erratic behavior. For a workaround, if you enabled any optimization flags, it's best to omit optimization entirely. In any case, the way to find the facts is to run the program under the debugger and see where it's failing. Also, if you have trouble with a system C compiler, I advise trying the GNU C compiler. And vice versa, unfortunately; but in that case I also recommend reporting a bug to the GCC mailing list; see *Note Bugs: (gcc)Bugs. To report compiler bugs effectively requires perseverance and perspicacity: you must find the miscompiled line, and that usually involves delving backwards in time from the point of error, checking through TeX's (or whatever program's) data structures. Things are not helped by all-too-common bugs in the debugger itself. Good luck. One known cause of trouble is the way arrays are handled. Some of the Pascal arrays have a lower index other than 0, and the C code will take the pointer to the allocated memory, subtract the lower index, and use the resulting pointer for the array. While this trick often works, ANSI C doesn't guarantee that it will. It it known to fail on HP-UX 10 mchines when the native compiler is used, unless the `+u' compiler switch was specified. Using GCC will work on this platform as well. Empty Makefiles ............... On some systems (NetBSD, FreeBSD, AIX 4.1, and Mach10), `configure' may fail to properly create the Makefiles. Instead, you get an error which looks something like this: prompt$ ./configure ... creating Makefile sed: 1: "\\@^ac_include make/pat ...": \ can not be used as a string delimiter So far as I know, the bug here is in `/bin/sh' on these systems. I don't have access to a machine running any of them, so if someone can find a workaround that avoids the quoting bug, I'd be most grateful. (Search for `ac_include' in the `configure' script to get to the problematic code.) It should work to run `bash configure', instead of using `/bin/sh'. You can get Bash from `ftp://prep.ai.mit.edu/pub/gnu' and mirrors. Another possible cause (reported for NeXT) is a bug in the `sed' command. In that case the error may look like this: Unrecognized command: \@^ac_include make/paths.make@r make/paths.make In this case, installing GNU `sed' should solve the problem. You can get GNU `sed' from the same places as Bash. `XtStrings' ........... You may find that linking X programs results in an error from the linker that `XtStrings' is undefined, something like this: gcc -o virmf ... .../x11.c:130: undefined reference to `XtStrings' This generally happens because of a mismatch between the X include files with which you compiled and the X libraries with which you linked; often, the include files are from MIT and the libraries from Sun. The solution is to use the same X distribution for compilation and linking. Probably `configure' was unable to guess the proper directories from your installation. You can use the `configure' options `--x-includes=PATH' and `--x-libraries=PATH' to explicitly specify them. `dlopen' ........ (This section adapted from the file `dlsym.c' in the X distribution.) The `Xlib' library uses the standard C function `wcstombs'. Under SunOS 4.1, `wcstombs' uses the `dlsym' interface defined in `libdl.so'. Unfortunately, the SunOS 4.1 distribution does not include a static `libdl.a' library. As a result, if you try to link an X program statically under SunOS, you may get undefined references to `dlopen', `dlsym', and `dlclose'. One workaround is to include these definitions when you link: void *dlopen() { return 0; } void *dlsym() { return 0; } int dlclose() { return -1; } These are contained in the `dlsym.c' file in the MIT X distribution. `ShellWidgetClass' .................. (This section adapted from the comp.sys.sun.admin FAQ.) If you are linking with Sun's OpenWindows libraries in SunOS 4.1.x, you may get undefined symbols `_get_wmShellWidgetClass' and `_get_applicationShellWidgetClass' when linking. This problem does not arise using the standard MIT X libraries under SunOS. The cause is bugs in the `Xmu' shared library as shipped from Sun. There are several fixes: * Install the free MIT distribution from `ftp.x.org' and mirrors. * Get the OpenWindows patches listed below. * Statically link the `Xmu' library into the executable. * Avoid using `Xmu' at all. If you are compiling Metafont, see *Note Online Metafont graphics: (web2c)Online Metafont graphics. If you are compiling Xdvi, see the `-DNOTOOL' option in `xdvik/INSTALL'. * Ignore the errors. The binary runs fine regardless. Here is the information for getting the two patches: Patch ID: 100512-02 Bug ID's: 1086793, 1086912, 1074766 Description: 4.1.x OpenWindows 3.0 `libXt' jumbo patch Patch ID: 100573-03 Bug ID: 1087332 Description: 4.1.x OpenWindows 3.0 undefined symbols when using shared `libXmu'. The way to statically link with `libXmu' depends on whether you are using a Sun compiler (e.g., `cc') or `gcc'. If the latter, alter the `x_libs' Make variable to include -static -lXmu -dynamic If you are using the Sun compiler, use `-Bstatic' and `-Bdynamic'. Pointer combination warnings ............................ When compiling with old C compilers, you may get some warnings about "illegal pointer combinations". These are spurious; just ignore them. I decline to clutter up the source with casts to get rid of them.