From 487ca4806cc046076293cf6cc5fbba0db282bac7 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 17 Jan 2006 21:41:51 +0000 Subject: texk 1 git-svn-id: svn://tug.org/texlive/trunk@1485 c570f23f-e606-0410-a88d-b1316a301751 --- Build/source/texk/kpathsea/bugs.texi | 900 +++++++++++++++++++++++++++++++++++ 1 file changed, 900 insertions(+) create mode 100644 Build/source/texk/kpathsea/bugs.texi (limited to 'Build/source/texk/kpathsea/bugs.texi') diff --git a/Build/source/texk/kpathsea/bugs.texi b/Build/source/texk/kpathsea/bugs.texi new file mode 100644 index 00000000000..cb0731512d4 --- /dev/null +++ b/Build/source/texk/kpathsea/bugs.texi @@ -0,0 +1,900 @@ +@ifclear version +@defcodeindex fl +@defcodeindex op +@end ifclear + +@node Reporting bugs +@section Reporting bugs + +@cindex reporting bugs +@cindex bugs, reporting + +@ifset version +(A copy of this chapter is in the file @file{kpathsea/BUGS}.) +@end ifset + +@flindex tex-k@@mail.tug.org @r{(bug address)} +@cindex bug address +If you have problems or suggestions, please report them to +@email{tex-k@@mail.tug.org} 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, @dots{} + +@menu +* Bug checklist:: What to include in a good bug report. +* Mailing lists:: Joining the bugs or announcements mailing lists. +* Debugging:: Analyzing runtime problems. +* Logging:: Recording searches. +* Common problems:: When things go wrong. +@end menu + + +@node Bug checklist +@subsection Bug checklist + +@cindex checklist for bug reports +@cindex bug checklist + +Before reporting a bug, please check below to be sure it isn't already +known (@pxref{Common problems}). + +Bug reports should be sent via electronic mail to +@email{tex-k@@mail.tug.org}, 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: + +@itemize @bullet +@item +@cindex version numbers, determining +The version number(s) of the program(s) involved, and of Kpathsea +itself. You can get the former by giving a sole option @samp{--version} +to the program, and the latter by running @samp{kpsewhich --version}. +The @file{NEWS} and @file{ChangeLog} files also contain the version +number. + +@item +@pindex uname +The hardware, operating system (including version number), compiler, and +@code{make} program you are using (the output of @code{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). + +@item +@flindex config.log +Any options you gave to @code{configure}. This is recorded in the +@file{config.status} files. + +@cindex configuration bugs +@flindex config.status +If you are reporting a bug in @samp{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 @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 @samp{configure} bugs do not involve the +compiler; in that case, the only recourse is to inspect the +@code{configure} shell script itself, or the Autoconf macros that +generated @code{configure}. + +@item +The log of all debugging output, if the bug is in path searching. You +can get this by setting the environment variable @code{KPATHSEA_DEBUG} +to @samp{-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. + +@item +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. + +@cindex shar@r{, recommended} +GNU @code{shar}, available from @url{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 @url{ftp://ftp.tug.org/incoming} (that +directory is writable, but not readable). + +@item +@cindex context diff +@cindex sending patches +@flindex ChangeLog @r{entry} +If you are sending a patch (do so if you can!), please do so in the form +of a context diff (@samp{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 @file{ChangeLog} entry. + +@item +@cindex stack trace +@cindex debugger +@cindex crashes, reporting +@cindex core dumps, reporting +@cindex null pointers, dereferencing +@pindex gdb@r{, recommended} +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 @url{ftp://prep.ai.mit.edu/pub/gnu}). If +the cause is apparent (a @code{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 (@pxref{TeX or Metafont failing,, @TeX{} or Metafont +failing}). + +@item +Any additional information that will be helpful in reproducing, +diagnosing, or fixing the bug. +@end itemize + + +@node Mailing lists +@subsection Mailing lists + +@cindex mailing lists +@cindex bug mailing list +@cindex announcement mailing list + +Web2c and Kpathsea in general are discussed on the mailing list +@email{tex-k@@mail.tug.org}. +@flindex tex-k-request@@mail.tug.org +To join, email @email{tex-k-request@@mail.tug.org} with a line +consisting of + +@example +subscribe @var{you}@@@var{your.preferred.email.address} +@end example + +@noindent 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 @samp{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 @url{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. + +@flindex tex-archive@@math.utah.edu +@cindex announcement mailing list +If you only want announcements of new releases, not bug reports and +discussion, join @email{tex-archive@@math.utah.edu} (via mail to +@email{tex-archive-request@@math.utah.edu}). + +@cindex @TeX{} help mailing list +@cindex La@TeX{} help mailing list +@cindex Usenet @TeX{} newsgroup +@cindex newsgroup for @TeX{} +@cindex help, mailing list for general @TeX{} +@flindex info-tex@@shsu.edu +@flindex comp.text.tex +If you are looking for general @TeX{} help, such as how to use La@TeX{}, +please use the mailing list @email{info-tex@@shsu.edu} mailing list, +which is gatewayed to the @samp{comp.text.tex} Usenet newsgroup (or post +to the newsgroup; the gateway is bidirectional). + + +@node Debugging +@subsection Debugging + +@cindex debugging +@cindex runtime debugging +@cindex options for debugging + +@vindex kpathsea_debug +@flindex debug.h +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., @samp{-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 @samp{-d} (or whatever) option +first, for maximal output. Dvipsk and Xdvik have additional +program-specific debugging options as well. + +@vindex KPATHSEA_DEBUG +@vindex kpathsea_debug +You can also set the environment variable @code{KPATHSEA_DEBUG}; in this +case, you should use the numbers below. If you run the program under a +debugger and set the variable @code{kpathsea_debug}, also use the numbers +below. + +@kindex -1 @r{debugging value} +In any case, by far the simplest value to use is @samp{-1}, which will +turn on all debugging output. This is usually better than guessing +which particular values will yield the output you need. + +@cindex debugging output +@cindex standard error and debugging output +Debugging output always goes to standard error, so you can redirect it +easily. For example, in Bourne-compatible shells: +@example +dvips -d -1 @dots{} 2>/tmp/debug +@end example + +@cindex Kpsewhich, and debugging +It is sometimes helpful to run the standalone Kpsewhich utility +(@pxref{Invoking kpsewhich}), instead of the original program. + +@cindex numeric debugging values +In any case, you can @emph{not} use the @emph{names} below; you must +always use somebody's numbers. (Sorry.) To set more than one +option, just sum the corresponding numbers. + +@vtable @code +@item KPSE_DEBUG_STAT @r{(1)} +Report @samp{stat}(2) calls. This is useful for verifying that your +directory structure is not forcing Kpathsea to do many additional file +tests (@pxref{Slow path searching}, and @pxref{Subdirectory +expansion}). If you are using an up-to-date @file{ls-R} database +(@pxref{Filename database}), this should produce no output unless a +nonexistent file that must exist is searched for. + +@item KPSE_DEBUG_HASH @r{(2)} +Report lookups in all hash tables: @file{ls-R} and @file{aliases} +(@pxref{Filename database}); font aliases (@pxref{Fontmap}); and config +file values (@pxref{Config files}). Useful when expected values are not +being found, e.g.., file searches are looking at the disk instead of +using @file{ls-R}. + +@item KPSE_DEBUG_FOPEN @r{(4)} +@findex fopen@r{, redefined} +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 @samp{fopen} (@samp{fclose}) to be @samp{kpse_fopen_trace} +(@samp{kpse_fclose_trace}). + +@item KPSE_DEBUG_PATHS @r{(8)} +@tindex kpse_format_info_type +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 @file{texmf.cnf}, @file{config.ps}, +an environment variable, the compile-time default, etc. This is the +contents of the @code{kpse_format_info_type} structure defined in +@file{tex-file.h}. + +@item KPSE_DEBUG_EXPAND @r{(16)} +Report the directory list corresponding to each path element Kpathsea +searches. This is only relevant when Kpathsea searches the disk, since +@file{ls-R} searches don't look through directory lists in this way. + +@item KPSE_DEBUG_SEARCH @r{(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 +@file{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., +@file{texmf.cnf} and @file{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. + +@item KPSE_DEBUG_VARS @r{(64)} +Report the value of each variable Kpathsea looks up. This is useful for +verifying that variables do indeed obtain their correct values. + +@item GSFTOPK_DEBUG @r{(128)} +Activates debugging printout specific to @code{gsftopk} program. + +@item MAKETEX_DEBUG @r{(512)} +If you use the optional @code{mktex} programs instead of the +traditional shell scripts, this will report the name of the site file +(@file{mktex.cnf} by default) which is read, directories created by +@code{mktexdir}, the full path of the @file{ls-R} database built by +@code{mktexlsr}, font map searches, @code{MT_FEATURES} in effect, +parameters from @code{mktexnam}, filenames added by +@code{mktexupd}, and some subsidiary commands run by the programs. + +@item MAKETEX_FINE_DEBUG @r{(1024)} +When the optional @code{mktex} programs are used, this will print +additional debugging info from functions internal to these programs. +@end vtable + +@cindex @samp{kdebug:} +@vindex hash_summary_only @r{variable for debugging} +@cindex hash table buckets, printing +Debugging output from Kpathsea is always written to standard error, and +begins with the string @samp{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 @code{hash_summary_only} +variable in @file{kpathsea/db.c}.) + + +@node Logging +@subsection Logging + +@cindex log file + +@cindex logging successful searches +@cindex recording successful searches +@cindex usage patterns, finding +@cindex disk usage, reducing +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. + +@vindex TEXMFLOG +To do this, define the environment or config file variable +@code{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. + +@cindex epoch, seconds since +@findex time @r{system call} +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 @code{time} system +call). The second word is the filename. + +For example, after @code{setenv TEXMFLOG /tmp/log}, running Dvips on +@file{story.dvi} appends the following lines: + +@example +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 +@end example + +@cindex privacy, semblance of +@noindent Only filenames that are absolute are recorded, to preserve +some semblance of privacy. + + +@node Common problems +@subsection Common problems + +@cindex common problems +@cindex problems, common +@cindex FAQ, Kpathsea + +Here are some common problems with configuration, compilation, linking, +execution, @dots{} + +@menu +* Unable to find files:: If your program can't find fonts (or whatever). +* Slow path searching:: If it takes forever to find anything. +* Unable to generate fonts:: If mktexpk fails. +* TeX or Metafont failing:: Likely compiler bugs. + +* Empty Makefiles:: When configure produces empty makefiles. +* XtStrings:: When _XtStrings is undefined. +* dlopen:: When dlopen is undefined. +* ShellWidgetClass:: For dynamic linking troubles under OpenWindows. +* Pointer combination warnings:: For old compilers that don't grok char *. +@end menu + +@node Unable to find files +@subsubsection Unable to find files + +@cindex unable to find files +@cindex files, unable to find + +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. @xref{Debugging}. + +@itemize @bullet +@item +Perhaps you simply haven't installed all the necessary files; the basic +fonts and input files are distributed separately from the programs. +@xref{unixtex.ftp}. + +@item +@flindex /etc/profile +@cindex environment variables, old +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 @file{texmf.cnf} (@pxref{Supported file +formats}). System @file{/etc/profile} or other files such may be the +culprit. + +@item +@cindex symbolic links not found +@cindex leaf directories wrongly guessed +Your files reside in a directory that is only pointed to via a symbolic +link, in a leaf directory and is not listed in @file{ls-R}. + +Unfortunately, Kpathsea's subdirectory searching has an irremediable +deficiency: If a directory @var{d} being searched for subdirectories +contains plain files and symbolic links to other directories, but no +true subdirectories, @var{d} will be considered a leaf directory, i.e., +the symbolic links will not be followed. @xref{Subdirectory expansion}. + +You can work around this problem by creating an empty dummy subdirectory +in @var{d}. Then @var{d} will no longer be a leaf, and the symlinks will +be followed. + +The directory immediately followed by the @samp{//} 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. + +@item +If the fonts (or whatever) don't already exist, @code{mktexpk} (or +@code{mktexmf} or @code{mktextfm}) will try to create them. If +these rather complicated shell scripts fail, you'll eventually get an +error message saying something like @samp{Can't find font +@var{fontname}}. The best solution is to fix (or at least report) the +bug in @code{mktexpk}; the workaround is to generate the necessary +fonts by hand with Metafont, or to grab them from a CTAN site +(@pxref{unixtex.ftp}). + +@item +There is a bug in the library. @xref{Reporting bugs}. +@end itemize + + +@node Slow path searching +@subsubsection Slow path searching + +@cindex excessive startup time +@cindex slow startup time +@cindex startup time, excessive + +If your program takes an excessively long time to find fonts or other +input files, but does eventually succeed, here are some possible culprits: + +@itemize @bullet +@item +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 @file{ls-R} file that lists all the files in your main @TeX{} +hierarchy. @xref{Filename database}. Kpathsea always uses @file{ls-R} +if it's present; there's no need to recompile or reconfigure any of the +programs. + +@item +Your recursively-searched directories (e.g., +@file{/usr/local/share/texmf/fonts//}), contain a mixture of files and +directories. This prevents Kpathsea from using a useful optimization +(@pxref{Subdirectory expansion}). + +It is best to have only directories (and perhaps a @file{README}) in the +upper levels of the directory structure, and it's very important to have +@emph{only} files, and no subdirectories, in the leaf directories where +the dozens of TFM, PK, or whatever files reside. +@end itemize + +In any case, you may find the debugging options helpful in determining +precisely when the disk or network is being pounded. @xref{Debugging}. + + +@node Unable to generate fonts +@subsubsection Unable to generate fonts + +@cindex unable to generate fonts +@cindex font generation failures + +Metafont outputs fonts in bitmap format, tuned for a particular +device at a particular resolution, in order to allow for the +highest-possible quality of output. Some DVI-to-whatever programs, +such as Dvips, try to generate these on the fly when they are needed, +but this generation may fail in several cases. + +@cindex @code{mktexpk} can't guess mode +If @code{mktexpk} runs, but fails with this error: +@example +mktexpk: Can't guess mode for @var{nnn} dpi devices. +mktexpk: Use a config file to specify the mode, or update me. +@end example +you need to ensure the resolution and mode match; just +specifying the resolution, as in @code{-D 360}, is not enough. + +You can specify the mode name with the @code{-mode} option on the +Dvips command line, or in a Dvips configuration file (@pxref{Config +files,,, dvips, Dvips}), such as @file{config.ps} in your document +directory, @file{~/.dvipsrc} in your home directory, or in a system +directory (again named @file{config.ps}). (Other drivers use other +files, naturally.) + +For example, if you need 360@dmn{dpi} fonts, you could include this in +a configuration file: +@example +D 360 +M lqmed +@end example + +@cindex Metafont using the wrong device +@cindex device, wrong +If Metafont runs, but generates fonts at the wrong resolution or for +the wrong device, most likely @code{mktexpk}'s built-in guess for the +mode is wrong, and you should override it as above. + +See @url{ftp://ftp.tug.org/tex/modes.mf} for a list of resolutions and +mode names for most devices (additional submissions are welcome). + +@flindex .2602gf +@flindex 2602gf +@cindex Metafont making too-large fonts +@cindex proof mode +@cindex online Metafont display, spurious +If Metafont runs but generates fonts at a resolution of 2602@dmn{dpi} +(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 +@code{proof} mode, instead of an actual device mode.) To make a proper +@file{plain.base}, assuming the local mode definitions are contained in +a file @file{modes.mf}, run the following command (assuming Unix): + +@example +inimf "plain; input modes; dump" +@end example + +@noindent +@flindex plain.base +Then copy the @file{plain.base} file from the current directory to where +the base files are stored on your system +(@file{/usr/local/share/texmf/web2c} by default), and make a link +(either hard or soft) from @file{plain.base} to @file{mf.base} in that +directory. +@xref{inimf invocation,,, web2c, Web2c}. + +@cindex Metafont installation +If @code{mf} is a command not found at all by @code{mktexpk}, then you +need to install Metafont (@pxref{unixtex.ftp}). + + +@node TeX or Metafont failing +@subsubsection @TeX{} or Metafont failing + +@cindex @TeX{} failures +@cindex Metafont failures +@cindex compiler bugs +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. + +@cindex optimization caveat +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. + +@cindex GNU C compiler bugs +@cindex system C compiler bugs +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 @ref{Bugs,,, gcc, +Using and Porting GNU CC}. + +@cindex compiler bugs, finding +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. + +@cindex ANSI C +@cindex HP-UX, compiling on +@cindex compiling on HP-UX +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 @samp{+u} compiler +switch was specified. Using GCC will work on this platform as well. + +@node Empty Makefiles +@subsubsection Empty Makefiles + +@cindex Makefiles, empty +@pindex sed @r{error from @code{configure}} +@pindex configure @r{error from @code{sed}} +@cindex NetBSD @code{configure} error +@cindex FreeBSD @code{configure} error +@cindex Mach10 @code{configure} error +@cindex AIX 4.1 @code{configure} error +@cindex NeXT @code{sed} error + +On some systems (NetBSD, FreeBSD, AIX 4.1, and Mach10), @code{configure} +may fail to properly create the Makefiles. Instead, you get an error +which looks something like this: + +@example +prompt$ ./configure +@dots{} +creating Makefile +sed: 1: "\\@@^ac_include make/pat ...": \ can not be used as a string delimiter +@end example + +So far as I know, the bug here is in @code{/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 @code{ac_include} in the @code{configure} script +to get to the problematic code.) + +It should work to run @code{bash configure}, instead of using +@code{/bin/sh}. You can get Bash from +@url{ftp://prep.ai.mit.edu/pub/gnu} and mirrors. + +Another possible cause (reported for NeXT) is a bug in the @code{sed} +command. In that case the error may look like this: + +@example +Unrecognized command: \@@^ac_include make/paths.make@@r make/paths.make +@end example + +In this case, installing GNU @code{sed} should solve the problem. You +can get GNU @code{sed} from the same places as Bash. + +@ignore +@node wchar_t +@subsubsection @code{wchar_t} + +@vindex FOIL_X_WCHAR_T +@tindex wchar_t + +The upshot of all the following is that if you get error messages +regarding @code{wchar_t}, try defining @code{NO_FOIL_X_WCHAR_T} (for +Web2c) or @code{FOIL_X_WCHAR_T} (for everything else), as in: + +@example +make XCFLAGS=-DNO_FOIL_X_WCHAR_T @var{other-make-options} +@end example + +@flindex Xlib.h +@flindex stddef.h +@code{wchar_t} has caused infinite trouble. None of my code ever uses +@code{wchar_t}; all I want to do is include X header files and various +system header files, possibly compiling with GCC. This seems an +impossible task! The basic problem is that the X11 header +@file{} and GCC's @file{} have conflicting definitions +for @code{wchar_t}. + +The particulars: @file{} from MIT X11R5 defines +@code{wchar_t} if @code{X_WCHAR} is defined, which is defined if +@code{X_NOT_STDC_ENV} is defined, and we define @emph{that} if +@code{STDC_HEADERS} is not defined (@samp{configure} decides if +@code{STDC_HEADERS} gets defined). But when compiling with GCC on SunOS +4.1.x, @code{STDC_HEADERS} is not defined (@file{string.h} doesn't +declare the @samp{mem}* functions), so we do get X's +@code{wchar_t}---and we also get GCC's @code{wchar_t} from its +@file{}. Conflict. + +On the other hand, SunOS 4.1.1 with some other X configurations actually +needs GCC to define @code{wchar_t}, and fails otherwise. + +My current theory is to define @code{wchar_t} to a nonsense symbol +before the X include files are read; that way its definition (if any) +will be ignored by other system include files. Going along with that, +define @code{X_WCHAR} to tell X not to use @file{}, that we've +already included, but instead to make its own definition. + +But this is not the end of the story. The X11 include files distributed +with DG/UX 5.4.2 for the Aviion have been modified to include +@file{<_int_wchar_t.h>} if @code{X_WCHAR}, so our @code{#define} will +not have any typedef to change---but the uses of @code{wchar_t} in the X +include files will be changed to reference this undefined symbol. So +there's nothing to foil in this case. I don't know how to detect this +automatically, so it's up to you to define @code{NO_FOIL_X_WCHAR_T} +yourself. +@end ignore + +@node XtStrings +@subsubsection @code{XtStrings} + +@findex XtStrings +You may find that linking X programs results in an error from the linker +that @samp{XtStrings} is undefined, something like this: + +@example +gcc -o virmf @dots{} +@dots{}/x11.c:130: undefined reference to `XtStrings' +@end example + +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 @samp{configure} was unable to guess the proper +directories from your installation. You can use the @code{configure} +options @samp{--x-includes=@var{path}} and +@samp{--x-libraries=@var{path}} to explicitly specify them. + + +@node dlopen +@subsubsection @code{dlopen} + +@cindex static linking and @code{dlsym} +@flindex dlopen +@flindex dlsym +@flindex dlclose +@flindex wcstombs +@flindex libdl.a +(This section adapted from the file @file{dlsym.c} in the X distribution.) + +The @code{Xlib} library uses the standard C function @code{wcstombs}. +Under SunOS 4.1, @code{wcstombs} uses the @samp{dlsym} interface defined +in @file{libdl.so}. Unfortunately, the SunOS 4.1 distribution does not +include a static @samp{libdl.a} library. + +As a result, if you try to link an X program statically under SunOS, you +may get undefined references to @code{dlopen}, @code{dlsym}, and +@code{dlclose}. One workaround is to include these definitions +when you link: + +@example +void *dlopen() @{ return 0; @} +void *dlsym() @{ return 0; @} +int dlclose() @{ return -1; @} +@end example + +@flindex dlsym.c +@noindent These are contained in the @file{dlsym.c} file in the MIT X +distribution. + + +@node ShellWidgetClass +@subsubsection @code{ShellWidgetClass} + +@cindex dynamic linking problems with OpenWin libraries +@cindex OpenWin libraries, dynamic linking problems +@findex get_wmShellWidgetClass +@findex get_applicationShellWidgetClass + +@flindex comp.sys.sun.admin @r{FAQ} +@cindex FAQ, @t{comp.sys.sun.admin} +(This section adapted from the @t{comp.sys.sun.admin} FAQ.) + +If you are linking with Sun's OpenWindows libraries in SunOS 4.1.x, you +may get undefined symbols @code{_get_wmShellWidgetClass} and +@code{_get_applicationShellWidgetClass} when linking. This problem does +not arise using the standard MIT X libraries under SunOS. + +@findex Xmu @r{library problems} +The cause is bugs in the @code{Xmu} shared library as shipped from Sun. +There are several fixes: + +@itemize @bullet + +@item Install the free MIT distribution from @samp{ftp.x.org} and mirrors. + +@item Get the OpenWindows patches listed below. + +@item Statically link the @code{Xmu} library into the executable. + +@item Avoid using @code{Xmu} at all. If you are compiling +Metafont, see @ref{Online Metafont graphics,,, web2c, Web2c}. If you are +compiling Xdvi, see the @code{-DNOTOOL} option in @file{xdvik/INSTALL}. + +@item Ignore the errors. The binary runs fine regardless. + +@end itemize + +@cindex Sun OpenWin patches +@cindex patches, Sun OpenWin +Here is the information for getting the two patches: + +@display +Patch ID: 100512-02 +Bug ID's: 1086793, 1086912, 1074766 +Description: 4.1.x OpenWindows 3.0 @code{libXt} jumbo patch + +Patch ID: 100573-03 +Bug ID: 1087332 +Description: 4.1.x OpenWindows 3.0 undefined symbols when using shared @code{libXmu}. +@end display + +@cindex static linking +The way to statically link with @code{libXmu} depends on whether you are +using a Sun compiler (e.g., @code{cc}) or @code{gcc}. If the latter, +alter the @code{x_libs} Make variable to include + +@opindex -static +@opindex -dynamic +@example +-static -lXmu -dynamic +@end example + +@opindex -Bstatic +@opindex -Bdynamic +If you are using the Sun compiler, use @samp{-Bstatic} and @samp{-Bdynamic}. + + +@node Pointer combination warnings +@subsubsection Pointer combination warnings + +@cindex warnings, pointer combinations +@cindex pointer combination warnings +@cindex illegal pointer combination warnings +@pindex cc @r{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. + +@c This isn't worth including any more, OSF 1.x is too old. +@c The other XtInherit problem (R4 Xlib on Suns) should never come up, +@c but the answer from the X faq is included anyway. +@c +@c @node XtInherit +@c @subsubsection @code{XtInherit} +@c +@c @findex XtInherit @r{bug on OSF/1} +@c @cindex OSF/1 loader bug and @code{XtInherit} +@c @cindex Alpha OSF/1 loader bug and @code{XtInherit} +@c +@c On DEC OSF/1 1.x systems, the loader has a bug that manifests itself in +@c the following error (all on one line, but for the sake of the paper +@c width it's broken here): +@c +@c @example +@c xdvik/xdvi: /sbin/loader: Fatal Error: search_for_undefineds: +@c symbol _XtInherit should not have any relocation entry +@c @end example +@c +@c @noindent According to Michael Rickabaugh @code{}: +@c +@c @quotation +@c This is a bug fixed in DEC OSF/1 2.0. +@c +@c If you know how, installing @file{/sbin/loader} from a 2.0 system onto a +@c 1.3 system will work. Make sure that @file{/usr} is @emph{not} mounted +@c when you do this. (If you forget about umounting @code{/usr}, it is +@c possible most of your filesystems will become corrupted.) +@c +@c Otherwise, I suggest getting a later CD and running +@c @file{/usr/sbin/installupdate}. +@c @end quotation +@c +@c Alternatively, you may be able to use the freely available X11 libraries +@c that come with the MIT distribution (on @file{ftp.x.org}, for example). +@c +@c Linking statically, perhaps only with some of the X libraries, may also +@c work. +@c +@c The Sun XtInherit weirdness, from the comp.windows.x FAQ: +@c Subject: 126)! What are these problems with "*_XtInherit* not found" on the Sun? +@c When I link a X program that I wrote on a SunOS 4.0.3 or 4.1 machine I get the +@c error "ld.so: symbol not found *_XtInherit*". +@c +@c What you are seeing is a side-effect of a kludge in the R4 libXt.a to +@c get Sun shared libraries working. Apparently, you can't share a function that +@c is both called and compared, as *_XtInherit* is. This was handled by putting +@c *_XtInherit* in the same file as a function that is always used, thereby +@c guaranteeing that it would be loaded -- that is, in Initialize.c, where +@c XtToolkitInitialize() and XtInitialize() reside. These routines would normally +@c be called. +@c +@c You are probably seeing this error because your program is not a normal +@c Xt-based program and does not call XtToolkitInitialize() anywhere. +@c 1) it may be a program that uses Xt functions but never opens a +@c connection to the X server. [OSF/Motif's 1.1.0 UIL had this problem; it called +@c XtMalloc() and other Xt functions.] The solution is to add the call to your +@c program; the function does not have to be executed, just linked in. +@c 2) alternatively, your program doesn't need any Xt functions and is +@c correct in not calling XtToolkitInitialize() -- it may be an Xlib or XView +@c program. In this case, you can remove -lXt from your link command. +@c +@c It should not be necessary to link the shared libraries statically, +@c although this will certainly solve the problem. + +@c * Empty Makefiles:: If configure gives you sed errors. +@c * wchar_t:: For wchar_t difficulties. -- cgit v1.2.3