The GTKWave electronic waveform viewer
Copyright (C) 1999-2003 Tony Bybell
Copyright (C) 2000-2003 AMULET Group, Department of Computer Science
The University of Manchester, Oxford Road, Manchester, M13 9PL, UK
Icons borrowed from GNOME2 icons by tigert

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
(hhh) Handshake activity traces from the Balsa system
	(http://www.cs.man.ac.uk/apt/projects/balsa)

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
libbzip2 -- (not required, but useful) for the Bzip2 compressed
    LXT support
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

