The GTKWave electronic waveform viewer
Copyright (C) 1999-2002 Tony Bybell
Copyright (C) 2000-2002 AMULET Group, Department of Computer Science
The University of Manchester, Oxford Road, Manchester, M13 9PL, UK

GTKWave is a waveform viewer which supports waveform data in
the following formats:

(vcd) VCD/EVCD -- Verilog Value Change Description files
(out) Synopsys Timemill/Powermill/Nanosim .out files
(lxt) Tony Bybell's LXT format, which can be generated by Icarus Verilog

Prerequisites
=============

To build GTKWave you must have:

GTK+/GLib -- versions from the 1.2 series.  GTK+ 2.0 is not yet supported.
zlib -- to support .gz and .zip compressed files and compressed traces
	in the LXT format loader
libxml2 -- from xmlsoft.org. Any version from 2.4.
A C compiler -- A certain amount of care is taken to make sure than
	GTKWave will build on ISO C compliant compilers other than GNU CC,
	please let me (bardsley@cs.man.ac.uk) know if you have trouble.

Building GTKWave
================

1. Run the autoconf generated configure script in this directory:

	./configure

	This will build Makefiles throughout the package after
	checking for availability of the prerequisite software on
	your system.  You may need to set the CFLAGS and LDFLAGS
	environment variables to appropriate values to be able to
	find some things on your system (e.g. I have to do
	export CFLAGS="-I/home/amulocal/solaris/include" and
	export LDFLAGS="-L/home/amulocal/solaris/lib" to build on
	my local Solaris system).

	Common command line arguments to configure are:

	--prefix=/directory/to/install/everything/in
	--exec-prefix=/directory/to/install/platform/specific/binaries/in
	--libdir=/directory/for/library/files (the format loader modules)
	--datadir=/directory/for/icon/and/other/non/binary/files

	Most users can copy perfectly well just specifying --prefix.

	Arguments specifically for GTKWave are:

	--enable-builtin-pixmaps -- build icons into the gtkwave binary
		rather than loading them at run time 

	--enable-builtin-readers="ext,ext,..." -- build static versions
		of the specified readers and build them into the gtkwave
		binary.  Dynamic versions of readers are still built for
		all formats but may not get used.  If no format names
		are specified after the `=' sign this variable then its
		value currently defaults to "vcd,out,lxt": all the current
		format readers).  The names of the supported readers appear
		at the top of this file in parentheses.

	Combining these two options allows you to build a gtkwave
	binary which is stand-alone and statically linked.  This
	may be convenient for platforms where the GTKWave installation may
	need to be moved or building dynamic modules is difficult.

2. make
	Build the package, look out for error messages

3. make install
	Install the package in the --prefix... directories

Invoking GTKWave
================

An installed copy of GTKWave looks like this (if only prefix is set,
please refer to the configure.in file to better understand the
structure if one or more of the other directory arguments to
configure is given):

.../bin/gtkwave -- the GTKWave program
   /share/gtkwave/pixmaps/*.xpm -- Icons
   /lib/gtkwave/reader_lxt.{la,so...}
               /reader_out.{la,so...}
               ...

GTKWave is invoked with the filename of the waveform file you wish
to view.  Some example files are provided in the directory ./examples,
e.g.:

	gtkwave ./examples/simple.vcd

GTKWave chooses which format reader to use based on the file extension
of the given filename, in this case VCD (extensions are treated case-
insensitively).
The appropriate reader for a format is searched for in the following
way:
	1. If the required reader was built into the gtkwave binary
		by specifying it using the --enable-builtin-readers
		argument to configure, that reader is used.
	2. If the environment variable WAVE_READER_PATH
		is set then try to load reader modules (by finding the
		file reader_{format}.la) following the directories given in
		WAVE_READER_PATH.
	4. GTKWave will try and find a reader module in the lib/gtkwave
		directory of the installation which was built into the
		gtkwave binary.  This directory can be changed by hand,
		if required, by modifying the file config.h in this directory
		after running configure.

Moving GTKWave After Installation
=================================

You may want to move the installed GTKWave files after installation.
This is common when building binary packages without a fixed installation
directory.  The --enable-builtin-pixmaps and --enable-builtin-readers
configure flags allow a single, stand-alone gtkwave binary to be built
with linked in format readers.  It is possible to move GTKWave, however,
without doing this by setting the environment variables WAVE_READER_PATH,
as described above, and WAVE_SHARE_DIR, to the new location of the
`share' directory.  Wrapping invokation of gtkwave in a script may be
the best way to do this, eg.:

#! /bin/sh

INSTALL_DIR=/somedir
# Still allow user WAVE_READER_PATH
WAVE_READER_PATH=${INSTALL_DIR}/lib:${WAVE_READER_PATH}
WAVE_SHARE_DIR=${INSTALL_DIR}/share

export WAVE_READER_PATH WAVE_SHARE_DIR

