From 581d69c2dc64b04ac6532de6bbfb0c2d01643704 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 5 May 2014 18:09:26 +0000 Subject: revise manual, deleting obsolete build/install info git-svn-id: svn://tug.org/texlive/trunk@33850 c570f23f-e606-0410-a88d-b1316a301751 --- Build/source/texk/kpathsea/doc/bugs.texi | 897 ------------------------------- 1 file changed, 897 deletions(-) delete mode 100644 Build/source/texk/kpathsea/doc/bugs.texi (limited to 'Build/source/texk/kpathsea/doc/bugs.texi') diff --git a/Build/source/texk/kpathsea/doc/bugs.texi b/Build/source/texk/kpathsea/doc/bugs.texi deleted file mode 100644 index 43460f9d57b..00000000000 --- a/Build/source/texk/kpathsea/doc/bugs.texi +++ /dev/null @@ -1,897 +0,0 @@ -@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@@tug.org @r{(bug address)} -@cindex bug address -If you have problems or suggestions, please report them to -@email{tex-k@@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@@tug.org}. - -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. - -@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@@tug.org}. -@flindex tex-k-request@@tug.org -To join, email @email{tex-k-request@@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. - -@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 -@LaTeX{}, please use the mailing list @email{texhax@@tug.org} mailing -list (@url{http://lists.tug.org/texhax}) 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 kpse->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 kpse->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 instance variable @code{kpse->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. - -In addition to this Kpathsea-specific logging, @command{pdftex} -provides an option @option{-recorder} to write the names of all files -accessed during a run to the file @file{@var{basefile}.fls}. - -Finally, most systems provide a general tool to output each system -call, thus including opening and closing files. It might be named -@command{strace}, @command{truss}, @command{struss}, or something -else. - - -@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 -machines 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