XCircuit Troubleshooting Page

General

Problem: I have a valid problem but it is not listed here.
Solution: Send me email describing the problem. I will include it in this list at my discretion.
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 Manifest file for a list of known bugs and new features which are already on the "to-do" list.
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.

Compile-time Problems

Problem: The Linux compiler returns the error ``ClearmakeOSName: Command not found''
Solution: This is a rarely-occurring error and has something to do with incorrect information in the default def files used by imake, that is to say, it is a system problem and should be fixed at the source. However, it can be worked around by adding these lines to the top of the Imakefile before running xmkmf:
#define HasClearmake NO
#define ClearmakeOSName /**/

Thanks to Allen Rees for this bug fix.
Problem: Xcircuit won't compile using GNU make (i.e., ./configure).
Solution: Because the GNU make was introduced around the same time as the Python interpreter, most problems arise from this source. Most of these can be fixed by hand-editing the Makefile that results from running the "configure" script. For instance, some versions of Python require "-ldb" to be passed to the linker but don't declare it directly in the Makefile from which xcircuit determines the libraries to link. This may need to be fixed in the "configure.in" file, with "autoconf" re-run to rebuild the "configure" script.
Problem: Xcircuit won't compile using imake (i.e., xmkmf).
Solution 1: Did you uncomment the CFLAGS= line in the Imakefile for your system? Did you do this for both the top-level Imakefile and also for Xw/Imakefile?
Solution 2: If your system is not listed in the README file as having been successfully tested with Xcircuit, you may need to play around with options for CFLAGS to get it to work right. Some useful debugging information can be found in the Imakefile. Consider it a bug and follow the instructions below.

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

Problem: XCircuit crashes with a segmentation violation immediately upon startup.
Solution: The introduction of the Python interface has caused some problems; before revision 10 of version 2.3.3, the "configure" script would define the PYTHON definition if it found the Python executable, leading to an inconsistency in the build if the Python library did not exist. The solution is to run the GNU make using "configure --with-python=no", which will manually disable the use of the Python interpreter. The other solution is to download the latest version of Python and compile and install from source, which will build the library (.a) file and install it where the xcircuit configure script can find it.
All recent (version 2.3.3 rev. 10 to 12) errors with Python trace back to Python version 1.5, which (unfortunately) comes installed on certain operating systems such as RedHat 7.1 (and others). Python version 1.5 has a known fatal bug. It is outlined in the python bugs list. Revision 14 of xcircuit 2.3.3 avoids the problem by refusing to use the embedded interpreter if it claims to be version 1.5. The solution is to update Python; if you're wary of replacing the version your OS depends on, it can be compiled in a separate directory, and xcircuit can be linked to that version by giving the switch "--with-python=DIR" to the "configure" script, substituting the proper directory for "DIR".
I'm running xcircuit on a DEC Alpha or other 64-bit processor, and the program crashes whenever a menu button is pressed.
Solution: You need to have CCOPTIONS set to -taso in the Imakefile; this switch makes programs designed for 32-bit memory addresses compile cleanly for 64-bit systems. Compilers for machines other than the DEC probably have a different compiler switch to do this. Check your C-compiler manpage. The GNU make ("./configure") script, introduced in xcircuit version 2.3, should take care of this automatically. Avoid use of the "imake" style build.
Problem: Xcircuit crashes with an X11-generated error ``Actions not found: PopupMenu.''
Solution: This problem was finally solved in May 1999. It is an extremely subtle problem. It stems from the fact that Xw gives several of its Widget classes the same name as Xaw (and possibly some other Widget sets). Window managers need to know information about the widget hierarchy of all the applications running, (which makes possible, among other things, interclient communication and Drag-and-Drop protocols), but the same X11 server model that gives the window manager control over its applications also allows applications to confuse each other. In this case, when assigning actions from the translation table, the Xw widget is assumed to be the Xaw widget of the same name, and the server reads the wrong translation list. The solution is to give all of Xw's widgets class names beginning with "Xw" to identify them uniquely with the Xw widget set. This has been done beginning with version 2.0a9 from 5/20/99.
Problem: Xcircuit crashed and burned for an unknown reason.
Solution:Make sure that you have the latest version of xcircuit (currently 2.3.3) and that the bug is not mentioned in the Manifest file of the current source distribution.
Problem: I'm running the latest version of XCircuit, and it crashed and burned for an unknown reason.
Solution: Send me email immediately (tim@bach.ece.jhu.edu). Try to explain the problem precisely. The bug will be easier to track down if it is repeatable.
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.
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

Keyboard/Mouse ("Input Focus") Problems

Problem: The main window won't accept keyboard input even though the buttons and menus all work.
Solution Use version 2.0a11 or later (from 10/26/99).
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 (rayburns@eskimo.com) for help with solving this problem, and all the others who reported problems and suggested solutions.
Problem: The menu buttons will accept pointer focus but they don't generate pulldown menus.
Solution: Probably you have Num Lock on. Unfortunately the Xw widget set buttons don't respond to keyboard events with key modifiers.
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.
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 should get it back to normal.
Problem: Keys do not function.
Solution: Some window managers do not accept keyboard events until the title bar has been clicked on.

Startup Problems

Problem: Xcircuit complains that the prolog file xcircps2.pro cannot be found. Solution Apparently on some systems the Makefile script doesn't finish the install process properly. However, doing a ``make install'' a second time works.
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-*
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.
Problem: No text shows up in the text-input areas of the popup windows.
Explanation: This problem is known to show up on DEC Alphas (sometimes along with the problem of the cursor position and drawing coordinates being half a screen-width off).
Solution: Get the latest version of XCircuit, which now has fixes to the Xw routines which solve the problem.
Problem: Xcircuit comes up but the colors in the drawing window are all wrong.
Solution 1: With some display visuals, it is possible that the colormap may be filled, with no values close to those xcircuit tries to allocate (xcircuit does it's best to find the closest-matching colors in the colormap rather than install its own map). Be sure to get the latest version of xcircuit (at least dating to March 3, 1998), which has a fix to this problem.
Solution 2: 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.
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. Solution 3: Look at the definition of XCIRCUIT_LIB_DIR in the Imakefile (usually /usr/local/lib/xcircuit), then check if that directory is actually a directory. If it is a regular file, then you have an older Imakefile with a bug. You can either delete the erroneous /usr/local/lib/xcircuit file, generate the directory by hand, and rerun "make install" from the Xcircuit source directory, or else delete the file, get the new Imakefile and run "xmkmf" and "make install" again.

Printing/PostScript Problems

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.
Solution: 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.
Problem: Xcircuit won't load a file I just created and saved; it says ``Error in scale/rotate constructs.''
Solution: This was a bug introduced into xcircuit-2.0a7, and occurs whenever a file is saved in landscape orientation. It was fixed in the source code on 1/26/99. To get the PostScript file to load into xcircuit again, you will need to get and compile the new source for xcircuit-2.0a7 or later.
Problem: I used a stipple pattern (from Options->Elements->Fill) in a drawing and int the PostScript output, the stipple pattern didn't completely fill the object as expected.
Solution: This is a bug which was fixed in versions beginning with the one dated 3/16/98. This bug is in the PostScript prologue, so you don't need to recompile; just replace the prologue with this corrected xcircps2.pro file.

Miscellaneous Run-Time Problems

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.
Problem: The simple help window stretches beyond the borders of my screen and can't be moved (and thus can't be canceled). Solution: This problem was fixed in version 2.0a6.
Problem: Some object or objects disappeared from the screen.
Solution: There is a program bug in which an object simply disappeared after dragging it from one page to another. The object, though, is still there, and will appear again after changing to another page and returning. This error was fixed sometime around version 2.2.

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

XCircuit is not entirely self-explanatory, but it is meant to be easy enough to grasp the concepts of the user interface that you should not be stigmatized by finding yourself reading this section, as you are not expected to have read the instructions thoroughly.

Problem: How can I undo a command?
Solution: If the command was a delete, then you can undelete with the "u" key or from the menu. Otherwise, you will have to reverse the procedure you just did, by hand.
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.
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".
Problem: There's no user library.
Explanation: The user library does not exist until at least one user object has been made either by 1) loading a file with user objects, 2) making a user object with the "m" key or from the "Edit->Make User Object" menu item, or 3) Making a copy of a built-in library object with the "C" key macro.

Back to the xcircuit home page. . .

email: tim@bach.ece.jhu.edu