XCircuit Troubleshooting Page

General

1. Problem: I have a valid problem but it is not listed here.
   Solution 1: Be sure to check the mailing list archive in case your problem has already been discussed. Solution 2: Send me (or the xcircuit mailing list) email describing the problem. I will include it in this list at my discretion.
2. Problem: XCircuit has a bug or is missing a feature that I would really like it to have.
   Solution: Send me email describing the bug or missing feature as precisely as possible. I am updating XCircuit all the time and have been known to add features requested by users. If you have access to the xcircuit source code, be sure to first look in the TODO file for a list of known bugs and new features which are already on the "to-do" list. You may also enter a bug report or feature request on the SourceForge project page. But be warned that sometimes I do not check this page for long periods of time, so an additional email telling me to go check the SourceForge site would be a good idea.
3. Gripe: XCircuit has a behavior that I find really annoying.
   Solution: XCircuit is not built on an "API". XCircuit is therefore partly an experiment in alternate user interfaces not necessarily following the usual standards. Sometimes this is for the best, and, admittedly, sometimes it can be pretty lousy. As an open-source enterprise, the xcircuit user interface should not be determined solely by the author, and will be changed due to popular demand when necessary. Please send on your comments, gripes, and suggestions on the user interface. No offense will be taken. Nevertheless, use of expletives is frowned upon.

Compile-time Problems

1. Problem: Xcircuit won't compile using GNU make (i.e., ./configure).
   Solution: Check the options of "configure" using
   ./configure --help
   Common problems include:
   1. General: XCircuit does not clean up well after itself, so if you change the configuration between compiles, be sure to do "make veryclean" first. Otherwise you can get two sets of incompatible compiled object files that can't be linked into the final executable.
   2. OS-specific: XCircuit is developed on a Linux platform. Support for other platforms varies; most problems are taken care of by the GNU "configure" script. But some operating systems need special flags or compile options. Mac OS X, Cygwin, and Solaris are the most problematic systems.
   3. Tcl/Tk: The most common compile problem with XCircuit is that the Tcl libraries cannot be found. Most OS distributions come with Tcl/Tk in a normal place, but not always. Also, some systems like Mac OS X and Cygwin come with versions of "wish" (the Tk shell) that use the system's native graphics instead of X11. These are incompatible with xcircuit! I have found that it usually works best to compile a new version of Tcl and Tk from source, where by default it goes in /usr/local, and does not conflict with any pre-existing distribution version. To get xcircuit to link to a specific set of Tcl/Tk libraries, use the configure options --with-tcl=path_to_tclConfig.sh and --with-tk=path_to_tkConfig.sh.
   4. X11: Occasionally systems will be set up incorrectly with respect to X11. This tends to show up early in the output from "./configure" with
      checking for X... no
      If this is the case, X11 directories can be supplied explicitly using something like this:
      ./configure --x-include=/usr/X11R6/include/X11 --x-libraries=/usr/X11R6/lib
      
   5. Xpm: Configure should handle this correctly, but sometimes the xpm include files and/or library file are in an unexpected place. If so, XPM can either be disabled with
      ./configure --without-xpm
      or the path to XPM explicitly using something like this:
      ./configure --with-xpm=/usr/X11R6/include/xpm
      

Fatal Run-time Problems (e.g., segmentation violations)

1. Tcl/Tk: Sometimes systems cough up on startup due to incompatibilities with Tcl. Such problems can cause Tcl/Tk to Unfortunately, this usually shows up as a cryptic message to the effect that the linked library file "xcircuit.so" cannot be found. This annoyance has been removed in version 3.2.13; any error messages seen on startup refer to the actual error. Check the install instructions page for information on how to run xcircuit under the debugger.
2. Tcl/Tk: One typical problem is that "wish" does not exist on the system. Often this is because the program has been installed as "wish8.4" or some similar name. This does not affect the running of XCircuit with the "-noconsole" option. But the console expects an executable named "wish". This is found in the script tkcon.tcl in the install directory (by default, /usr/local/lib/xcircuit-version/tkcon.tcl), on line 3:

   exec wish "$0" ${1+"$@"}

   where you will want to change the word "wish" to the correct name for the Tk shell executable.

   Note that the above problem/solution also applies to the case where the command-line name "wish" points to a version of "wish" that is not the one xcircuit was linked to, including, for example, the case where the version wanted is also named "wish" but the search path encounters the other one first. This is solved by specifying the entire path in the "exec wish" line in tkcon.tcl.

3. Shell: Another typical problem is that a needed shell does not exist on the system. The script xcircuit expects to see /bin/sh. I have actually encountered systems that do not define this---when this happens, the best course is to make a symbolic link called /bin/sh that points to the default shell (nowadays, more likely to be "bash" than "sh").
4. Problem: Xcircuit crashed and burned for an unknown reason.
   Solution:Make sure that you have the latest version of xcircuit and that the bug is not mentioned in the TODO file of the current source distribution.
5. Problem: I am running the latest version of XCircuit, and it still crashed and burned for an unknown reason.
   Solution: Send me email immediately (see bottom of page for my email address). Try to explain the problem precisely. The bug will be easier to track down if it is repeatable.

   You may find it preferable to email to the xcircuit mailing list, in which case you may be able to get help sooner from other users who subscribe to the list (I try to be on top of problems within a day or two, but it is not always possible).

   A bug report is always appreciated, and if you provide a soution, you will be acknowledged for your help.

   If you're familiar with the "gdb" debugger, please send along a stack trace (if there is one) showing the source file and line where the error occurred and a listing of the subroutine calling hierarchy up to the top level. See the install page for information on running the Tcl-based version of XCircuit under a debugger.

   I usually post a fix for fatal errors within one working day (or less) of receiving a fatal-bug report. Depending on the complexity of the problem and how busy I am, some fixes happen within minutes. So don't hesitate to report a problem.

Non-Fatal Run-time Problems

Menu Problems

1. Problem: I can't get any menus!
   Solution: This seems to be a perennial bugaboo with the Xw widget set. The menu buttons won't respond when Num Lock is on. Fortunately, this can be cured by turning Num Lock off. One permanent solution is to use the Tcl version of xcircuit (available in stable form since xcircuit version 3.1 revision 3, February 10, 2003), which does not use the Xw widget set.

Keyboard/Mouse (including "Input Focus") Problems

1. Problem: The main window won't accept keyboard input even though the buttons and menus all work.
   Solution This bug generally affects the WindowMaker window manager, which appears reluctant to give up keyboard focus unless it's forced away. Other newer window managers may show similar or related behavior. The old standbys (twm, mwm, etc.) always work correctly without special effort. The problem is really in WindowMaker, but fortunately can be worked around by applying XSetInputFocus() on receiving EnterNotify events. Thanks to Raymond Burns for help with solving this problem, and all the others who reported problems and suggested solutions.
2. Problem: I can't enter any text, and xcircuit complains that there aren't any fonts available.
   Solution: The font files (and possibly the library files) have not been installed. See the entry below.
3. Problem: Pressing Button 1 in the drawing window has no effect.
   Solution: Xcircuit has been known to get into rare incorrect states. Pressing Button 3 or the Escape key should return XCircuit to a normal state.
4. Problem: I don't have a three-button mouse! Solution: People were probably confused for a long time by my insistance that Shift-Button-1 is equivalent to Button-2, which was, in fact, broken for many versions. But, in version 3.4, this is really fixed. So there are now two solutions for users with 2-button mice:
   • Use Shift-Left-Button as a substitute for the mouse middle button.
   • Run XCircuit with the option "-2". This shifts all middle-button bindings to the right mouse button, and moves the right mouse button bindings to the "backspace" key. This puts all start/continue/finish functions on mouse buttons and all cancel functions on the keyboard.
   Users with 1-button mice are on their own. It is actually possible to set up such an interface using Tk bindings, which include double- and triple- mouse clicks, but I'm not going to be the one to do it.

   Likewise, users with 2-button mice are free to create their own (re)bindings. I am not a 2-button mouse user, never have been, and always throw away any 2-button mice that come with any computers I buy (fortunately the advent of scroll wheels has mostly made the problem disappear). Anyone who has a custom set of bindings that they think is more "natural" than the one I came up with should forward it to me so I can incorporate it into the distribution.

5. Problem: Keys do not function.
   Solution: Some window managers do not accept keyboard events until the title bar has been clicked on. In particular, the TCL version has some problems in some window managers determining whether or not it has keyboard focus on startup. Depending on the focus model of the window manager, you can get focus by clicking on the title bar, or by moving the mouse out of the window and back in.

Startup Problems

1. Problem: Xcircuit delivers some warning like ``Warning: Cannot convert string *helvetica-medium-r-normal--12* to type FontStruct''.
   Solution: While Xcircuit attempts to use fairly normal X11 fonts like the Adobe fonts, not all X11 implementations may have them (this was pointed out as a problem with Solaris 2.6, at least in Japan). X11 should select some default font instead. However, if you want to play with the fonts, the Xdefaults for fonts are listed in the man page and are as follows:
   xcircuit*helpfont: -*-helvetica-medium-r-normal--10-*
   xcircuit*filelistfont: -*-helvetica-medium-r-normal--14-*
   xcircuit*textfont: -*-courier-medium-r-normal--14-*
   xcircuit*titlefont: -*-times-bold-i-normal--14-*
   xcircuit*font: -*-times-bold-r-normal--14-*
   
2. Problem: Xcircuit comes up but the buttons and popup windows are all blank.
   Solution 1: Make sure you have installed xcircuit. If you have compiled xcircuit but not installed it, it may not know where to find the X application resources file. Around version 2.3, the application defaults file was moved to the xcircuit library directory, to prevent problems caused by not being able to write the X defaults file into the system directory (e.g., when a user without root access compiles xcircuit into a local directory). One result is that every time a minor version number changes, a new library directory is created, and xcircuit will not know where to find the files until they have been installed. The solution is to rename your current xcircuit executable to keep it from being overwritten, and do a "make install". Because this problem will only crop up when a new library directory is needed, old library files will not be affected. Solution 2: Values in your home-directory .Xdefaults file may be conflicting with color values set by xcircuit on startup. A setting like "*.foreground: black" could be the culprit. This is such a common problem that I have since put explicit defaults for button and popup windows into the XCircuit.ad application-defaults file. You can replace your app-defaults file (usually installed as /usr/lib/X11/app-defaults/XCircuit) with this corrected one, or edit the existing one (the only change is the first four defaults). The first two defaults (xcircuit*foreground and xcircuit*background) specify the color of the buttons and popup windows; the next two (xcircuit.foreground and xcircuit.background) set the colors for the main drawing window.
   At worst, if you have installed Xcircuit locally and don't have root access to put XCircuit.ad into the proper directory, then you can append the contents of XCircuit.ad to your home directory .Xdefaults, or load the defaults using the command xrdb -merge XCircuit.ad.
3. Problem: Xcircuit comes up but the colors in the drawing window are all wrong.
   Solution: It is possible that if the colormap is nearly but not completely filled up when xcircuit starts, that xcircuit might end up with very strange colors as it creates its own colormap and frees up the default, with some xcircuit windows accepting the new colormap and others still using the old one. If this happens, you can fix the problem by exiting color-hogging programs like Netscape to free up the default colormap, and then run xcircuit. This can only happen in 8-bit pseudocolor visuals, which are rarely used any more.
4. Problem: There's no built-in library.
   Solution 1: The library files have not been installed. If you are compiling xcircuit, make sure that you have done a "make install" and that the installation procedure has succeeded.
   Solution 2: A ".xcircuitrc" file exists in the current directory or home directory which is overriding the default library but failing to install a new one. Change or move the .xcircuitrc file.

Python Interpreter Problems

1. Apparently some staticly-linked python (.a) libraries will generate error messages on startup. The error messages are nonsensical (to me, at least) and as they have nothing to do with routines called by xcircuit, there is apparently no problem running xcircuit. Linking to the dynamic python (.so) library appears to cure this problem. See the xcircuit python reference page for details. Recent versions of python are now available with dynamic libraries.
2. There are a few commands in Python which are not complete and/or will crash the progam. One is
   newelement("Object Instance"). I will try to fix these as I encounter them, but as Tcl is the primary development platform, fixes and (especially) enhancements to the Python interface are a lower priority.

Tcl Interpreter Problems

1. A few commands in Tcl have (still) not been completed. A flurry of activity that resulted in version 3.4 included finishing off most of these commands. But then, I introduced hierarchical element naming, which is incomplete in that point positions will be reported relative to the top-most window for some commands but not others.

   There are a few other inconsistencies between the Tcl command-line reference page and the program. Given that I usually fix them when I know about them, any inconsistencies found should be reported to me, on the assumption that I don't know about them.

Printing/PostScript Problems

1. Problem: I use alternate encodings like ISO8859-5 (Cyrillic), but nothing appears in XCircuit.
   Solution: Use the Cairo graphics version of XCircuit (version 3.10 and higher), which does not rely on vector-drawn font characters but uses Cairo's font rendering engine.
2. Problem: I use alternate encodings like ISO8859-5 (Cyrillic), and it looks great in XCircuit, but it doesn't show up (or doesn't show up correctly) in xpdf (or okular, or evince, ...) after converting with "ps2pdf".
   Solution: If you can get the output to look correct using ghostview (gv) or ghostscript (gs), then what you need to do is to embed the fonts that ghostscript is seeing into the PDF document. You can do this using:

   ps2pdf -dEmbedAllFonts=true -dSubsetFonts=true -dPDFSETTINGS=/prepress

   If it does not show up even in ghostscript or ghostview, then you may need to install Type1 fonts. On my Fedora Core system, I have fonts in /usr/share/fonts/default/Type1/. Ghostscript has no direct mapping from standard Adobe font names like "Helvetica" to these fonts, but apparently the X11 font rendering engine (which I think is xft) does, and ghostscript can query the X11 font renderer for the correct mapping. That is to say, I installed these Type1 fonts for X11, not specifically for ghostscript.
3. Problem: The printer won't print the xcircuit output, although both xcircuit and ghostscript display it without problems.
   Explanation: Printer PostScript interpreters have a built-in stack size limit which prevents huge objects from being placed on the stack, regardless of the amount of free memory available. Library objects in xcircuit are defined and interpreted as single PostScript objects, so library objects with too many components can overflow the stack size limit.

   While I had not seen this problem for a long time, it showed up again with the introduction of the "graphic" element (loaded from a PPM format file). It seems that some printers don't allocate much virtual memory for buffering images.

   Solution 1: Normally, don't worry about this problem until you encounter it; you may never see it occur under normal circumstances. If it does happen, you will need to make your library objects more hierarchical so that no single object contains a large number of elements, or when practical (such as if the object occurs only once on the page), you can place the object contents on the top level page, where they are loaded and executed one at a time by the PostScript interpreter, avoiding the error condition altogether.
   Solution 2: The graphic image problem, and possibly other printing problems, can be worked around by converting the xcircuit output to PDF and then printing from a PDF document viewer such as xpdf or Adobe's acroread. The conversion moves buffered graphics to the end of the file, so they are no longer buffered. The positive effect of this is that printers don't have problems with the file. The negative effect is that one loses the benefits of the reusable stream; that is, a large graphic used multiple times will be written to the file as many times as it is called, making the PDF file much larger than the original XCircuit PostScript file.

Miscellaneous Run-Time Problems

1. Problem: When trying to load a file I got the error "filename.ps.ps not found".
   Explanation: The filename is a symbolic link to a file which does not exist or cannot be read.

Usage Problems (or, "I didn't read the instructions")

1. Problem: How can I undo an action?
   Solution: undo with the "u" key or from the menu. This works for most actions. A few actions that alter many elements at one time cannot be undone, such as file loads or page clears, and a few minor actions have not been incorporated into the undo mechanism.
2. Problem: Some object or objects disappeared from the screen.
   Solution: If there is an opaque polygon lying about, it may be that the object in question has been placed underneath where it cannot be seen. Select the polygon and use the key "X" (you may need to do it twice) to shuffle the polygon to the bottom.
   
3. Problem: I tried to change the color of an object but nothing happened.
   Explanation: None of the elements inside the object has color value "Inherit".
   Solution: Edit the object (">" key) and change the color of all its components to "Inherit".
4. Problem: XCircuit started with no libraries loaded.
   Explanation: Assuming that XCircuit has been installed properly and the environtment variable XCIRCUIT_LIB_DIR is not set, if a startup .xcircuitrc file contains an error, Tcl will not read the file further after the error, and the startup will not complete properly. Generally, the error in the file will not be reported.
5. Problem: I get "bit trash" all over the screen. Solution: Press the "space" bar to refresh the screen. Hopefully I'll get around to addressing this properly in the source code.
6. Problem: Objects get unselected after a rotation, making it difficult to rotate a group of objects.
   Solution: At some point I will get all of the actions consistent. For the moment, however, note that what you want to do here is to select all the elements you want to rotate, grab with "Hold-Button-1", then, while the elements are grabbed, rotate them with the "r" and "R" keys.

Back to the xcircuit home page. . .

email:

Last updated: June 26, 2018 at 11:17pm