XCircuit v2.3.3
-----------------------------------------------------------------------------
An X11 drawing program [especially for circuit schematics]
(c) 2001 Tim Edwards (see copyright notice in ./COPYRIGHT)
August 1993 -- July 2001
-----------------------------------------------------------------------------
Compilation/Installation notes:
1) All compile-time features are set during the ./configure process.
Run "./configure --help" for a list of configure options. For most
users, the relevant options are the following:
--prefix=PREFIX Location to install xcircuit. Defaults to
/usr/local/. The executable goes to /usr/local/bin/,
man pages to /usr/local/man/man1/, and everything
else to /usr/local/share/xcircuit-VERSION/. Defaults
can be separated by explicitly declaring
--exec-prefix=DIR, --mandir=DIR, and --libdir=DIR.
--disable-lgf Save space by not compiling the compatibility with
"analog" and "diglog" .lgf-format files.
--disable-schema Don't compile the schematic capture system. This
is a major feature of xcircuit, so disabling it is
not recommended. However, you may do so if you
anticipate having no need for circuit netlists.
--with-python=DIR If the configure step cannot find a Python
interpreter, it can be explicitly referenced.
Requires the Python library (libpythonVERSION.a
or libpythonVERSION.so) and the python include
file Python.h. The Python option uses the Python
language as an interpreter for xcircuit.
--with-xpm=DIR If the configure step cannot find the XPM package,
it can be explicitly referenced. The XPM package
enables the toolbar and an icon when xcircuit is
iconified.
--with-gs=DIR If the configure step cannot find ghostscript,
it can be explicitly referenced. The Ghostscript
option allows any PostScript file to be rendered
on the xcircuit background and saved with the
xcircuit file.
--disable-double-buffer
This option is almost wholly deprecated due to the
speed of modern processors. However, if you have
problems with slow rendering, you might find it
useful.
2) Compile with the usual GNU-compile steps:
./configure
make
make install
3) NOTE: The GNU configure put xcircuit run-time stuff into /usr/local/share
instead of /usr/local/lib, which was the default for the "imake" process.
If you have built xcircuit before using imake, and you test-run the xcircuit
executable before doing the install step, you may get strange behavior like
no text (missing fonts). A symbolic link between
/usr/local/lib/xcircuit-VERSION and /usr/local/shar/xcircuit-VERSION will
cover all cases.
-------------------------------------------------------------------------------
Alternative Imake Compilation Instructions:
GNU make is set up to be compatible with as many systems as possible. However,
because the GNU make scripts were introduced in version 2.3.2, we are leaving
in the original Imakefile as a backup. If GNU make does not work, I want to
know about it, because I want to move this platform away from Imakefile due to
the dependence of the compilation on system-dependent stuff, such as the
presence/location of XPM, Python, and GhostScript.
If the GNU configure and make does not work, follow these backup instructions:
1) All compile-time features are set from within Imakefile. Be sure to
reference Imakefile first if you have difficulties compiling.
2) Decide where you want xcircuit and its library files to reside, and
set XCIRCUIT_LIB_DIR, XCIRCUIT_MAN_DIR, and XCIRCUIT_BIN_DIR accordingly.
The default path is "/usr/local/lib/xcircuit-2.2/".
3) It should not be necessary to change CC, CCOPTIONS, or CDEBUGFLAGS for
Linux systems, unless you encounter problems during compiling.
4) DEC Alpha systems:
Add "-taso" to CCOPTIONS to get the compiler to make necessary changes
to deal with 64-bit addressing. It may also be necessary to add the
"-D" flag.
5) The XCircuit Imakefile defaults to defining "HAVE_PYTHON". However,
this assumes several things: That Python 2.1 is installed on the
system, that it is installed in /usr/local/, and that the Python
include files have been installed. This is all true for a standard
installation from Python source, but not necessarily for a
pre-installed Python. If you don't want to use the Python interpreter,
you can undefine HAVE_PYTHON in the Imakefile. If you have Python,
but it's a different version or installed in a different place, make
appropriate changes to the definitions
PYTHON_VERSION=2.1
PYTHON_LIB_DIR=/usr/local/lib
PYTHON_INCLUDE_DIR=/usr/local/include/python${PYTHON_VERSION}
in the Imakefile. PYTHON_LIB_DIR is the directory where the library
file "libpython2.1.a" (or equivalent, depending on the version) has
been installed. PYTHON_INCLUDE_DIR is the directory containing all
of Python's .h files, but must at least contain "Python.h".
The Python library preferably should be built as a shared (.so) library.
See the section "Shared Python Library" below.
6) Anyone using xcircuit for drawing purposes only (no schematic capture
wanted) may undefine SCHEMA in the Imakefile. If you're not sure,
leave it alone.
7) By default, the Imakefile assumes that your system has xpm (pixmaps); if
you don't, or you get error messages about no include file "xpm.h" found,
then delete the line "#define HAVE_XPM" from the Imakefile and recompile.
The only thing you will be missing is the color icon.
Xcircuit should be made using the following commands:
xmkmf
make
make install
make install.man
The makefile should automatically install the application defaults
file "XCircuit.ad" in /usr/lib/X11/app-defaults/XCircuit.
The makefile should also automatically install the man page in
(depending on the Imake configuration) /usr/local/man/man1/xcircuit.1x.
If the program is extremely slow in rendering the screen or if the
system tends to swap during program execution, you may need to
undefine DO_BUFFER in the Imakefile. Clean, no-flicker rendering
is made possible by drawing on a Pixmap and then doing a quick copy
from the Pixmap to the screen. Depending on the default screen
depth (usually 8 or 16 bits) and the window size, the Pixmap can take
a MB of memory or more. Systems with too little memory or systems
without a video card with Bit-BLT (block transfers) can erase all
the gains of graphics buffering. Xcircuit will operate fine without
buffering, but the screen will flicker every time there is a refresh;
consequently, without buffering the system is designed not to refresh
as often, and there will be more "pixel trash" on the screen. It is
expected that under these conditions the user will simply use the
space bar to refresh the screen as needed.
-----------------------------------------------------------------------------
Shared Python Library:
NOTE: The XCircuit build will be *much* smaller if you have a shared
python library. However, the build instructions as of Python-2.1c2
don't include instructions for building a shared library under linux.
Here's how you do it:
1) In the Makefile: set
LDLIBRARY=libpython2.1.so
2) Also in the Makefile:
Add a case for libpython$(VERSION).so which looks
exactly like the case statement for unixware:
linux) \
$(LDSHARED) -o $@ $(LIBRARY_OBJS) \
;; \
3) Make until error (can't find libpython2.1.so)
4) Copy or move libpython2.1.so to /usr/local/lib or /usr/lib
5) Run (as root!) ldconfig -v -n /usr/local/lib (or whereever
you just put the shared library) and confirm that it
found libpython2.1.so.
6) Finish "make" (should run to normal completion).
On my system, this is the difference between a 4MB xcircuit executable
and a 1.5MB executable. That's a big difference! Of course, Python
purists would say I should be embedding xcircuit in python, not the
other way around, then what need do I have for a shared library,
anyway?
Python source (and other information relating to Python) can be found
at www.python.org. The Python interpreter is recommended, as XCircuit
eventually will rely on Python to handle writing netlists, for
flexibility in formatting.
-----------------------------------------------------------------------------
Extras:
The file examples/.xcircuitrc shows how to make a home-directory file
to alter the behavior of xcircuit on startup. It shows how to change the
color scheme, add new fonts, override the default libraries, and change
the editing behavior for polygons. Note that if xcircuit is built with
embedded Python, the syntax for .xcircuitrc will be Python syntax, and
may use any Python commands in addition to the commands which hook into
xcircuit functions. The file examples/test.py is a sample Python script
which features use of Python to create animated graphics within the
xcircuit window, shows how to access on-screen elements and change
their properties, and contains convenience function definitions for
manipulating xcircuit elements.
Other files in the examples directory show how xcircuit can be
used to draw various things, from a simple circuit schematic
(vcoblock.ps) to an entire publishable-quality page of music
(prelude.ps), plus an example of a fancy page border for slide
presentations.
The files psfiles/signal.lps and psfiles/musiclib.lps are examples
of alternate or additional object libraries. The library file lgf.lps
is used primarily by the lgf-to-ps conversion routines, but has some
different circuit objects in it.
The file psfiles/fonttest.ps is a short PostScript program you can
use to get your printer to give you the names of all the built-in fonts
that it knows about, which is useful because if you add a font name to
xcircuit, the spelling has to be exactly correct or else the printer
won't recognize it.
The file examples/gettext.py is a sample Python script which adds
a Python command called "gettext(filename)". gettext(filename) reads
in file "filename", which should be an ASCII text file, and turns it
into a label in XCircuit positioned at the cursor position.
-----------------------------------------------------------------------------
X Resources:
The color scheme of xcircuit has a default setup, but accepts
alternate color schemes using the following keywords which can be put
in the X Defaults (.Xdefaults, .Xresources) file:
Resource name Description Default
------------------- ---------------------------- -------
xcircuit*foreground color of buttons and popups; White
xcircuit*background background of buttons & popups; DarkSlateGray
xcircuit.foreground drawing area foreground; White
xcircuit.background drawing area background; Black
xcircuit*gridcolor color of the grid lines; Gray40
xcircuit*snapcolor color of the snap-to points; Red
xcircuit*selectcolor color of a selected object; Gold
xcircuit*querycolor to differentiate multiple objects; Turquoise
xcircuit*axescolor color of the x, y axes; NavajoWhite4
xcircuit*offbuttoncolor text color of an inoperable button; Gray70
xcircuit*auxiliarycolor text cursor and other things Green
xcircuit*barcolor color of panning bars Tan
A secondary color scheme (for example, black-on-white) can be specified by
adding "2" to each of the above resource names. For example:
xcircuit*foreground2 color of every object drawn; Black
xcircuit*background2 screen background color; White
Other resources accepted by xcircuit are:
xcircuit*width width of the drawing area (pixels); 600
xcircuit*height height of the drawing area; 500
Normally, you will want to put the defaults in /usr/lib/X11/app-defaults.
If you do not have root access, you will want to have them in your own
home .Xdefaults file. If the file is not found by xcircuit, the program
will use its default color schemes, the main one being black-on-white,
and the alternate being white-on-dark-gray.
-----------------------------------------------------------------------------
Altering, Copying, and/or Redistributing XCircuit:
XCircuit is distributed under a generous artistic license. See the file
COPYRIGHT in the top-level directory for details.
-----------------------------------------------------------------------------
Online tutorial: See
"http://bach.ece.jhu.edu/~tim/programs/xcircuit/tutorial.html"
Schematic capture tutorial: See
"http://bach.ece.jhu.edu/~tim/programs/xcircuit/tutorial2.html"
-----------------------------------------------------------------------------
Contact address (check the website above for a current address):
R. Timothy Edwards
Mailstop 4-234
Johns Hopkins University
Applied Physics Laboratory
11100 Johns Hopkins Road
Laurel, MD 20723-6099
Office Phone: (240) 228-4613
FAX: (240) 228-7636
-----------------------------------------------------------------------------
