SCCS-info %W% %E% 

$Id$
     
			The VCG Tool 
			============
	   A Visualization Tool for compiler graphs


DESCRIPTION
     The VCG tool reads a textual and readable specification of a 
     graph and visualizes  the graph.   If  not  all positions of 
     nodes are fixed,  the tool  layouts the graph using  several 
     heuristics as reducing  the number of crossings,  minimizing 
     the  size of  edges,  centering of nodes.  The specification 
     language of  the  VCG  tool is nearly compatible to GRL, the 
     language of the edge tool, but contains many extensions. The 
     VCG tool  allows folding of dynamically or statically speci-
     fied  regions  of the  graph.  It uses  colors and  runs  on 
     SunView or X11.

     The VCG tool has been developed and tested on a Sparc ELC with
     SunOs 4.1.3, SunView and X11 Release 5, and different ANSI C 
     and K&R C compilers. It has further been tested on a Silicon 
     Graphics (IRIX 4.0.5), on a IBM R6000 (AIX 2 with AIX Windows), 
     on a HP-UX (X11R5, c89), on a DecStation (ULTRIX, X11R5, gcc only) 
     and on Linux (X11R5, gcc).
     For the tests on these machines, see README.SYS. This may also
     help for a setup on other machines.


LICENSE CONDITIONS
     Copyright (C) 1993, 1994 by Iris Lemke, Georg Sander, and
                                 the Compare Consortium 

     This work is supported by the ESPRIT project 5399 Compare.
     We thank the Compare Consortium for the permission to distribute
     this software and documentation freely.  You can redistribute 
     it under the terms of the  GNU General Public License as published by
     the  Free Software Foundation;  version 2  of the License.

     The members of the Compare Consortium are ACE Associated Computer 
     Experts bv, GMD Forschungsstelle an der Universitaet Karlsruhe,
     Harlequin Limited, INRIA, STERIA, Stichting Mathematisch Centrum (CWI), 
     and Universitaet des Saarlandes.

     The Compare Consortium will neither assume responsibility for any 
     damages caused by the use of its products, nor accept warranty or 
     update claims. This product is distributed in the hope that it will 
     be useful, but WITHOUT ANY WARRANTY; without even the implied warranty 
     of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
     GNU General Public License for more details.  See the file COPYING.

     The software is available per anonymous ftp at ftp.cs.uni-sb.de.
     Contact  sander@cs.uni-sb.de  for additional information.


MAILING_LIST
	There is a mailing list vcg-users@cs.uni-sb.de that distributes
	mail to all users of the VCG tool.  If you want to be added to 
	this list, please send a request to me (sander@cs.uni-sb.de).
	Then, you will be informed about bugs and new versions of 
	the tool.


FILES
	README       - this file you are reading actually
	README.SYS   - Hints for different systems, how to configure
		       and setup.
	COPYING      - The license conditions for this software.
		       PLEASE READ THIS.
	Makefile     - the Top Level Makefile.
	tMakefile.tpl- template to generate an executive tMakefile  
		       by config.
	config	     - shell script to configure and some
		       additional features
	preconf      - a directory consisting of a lot of preconfiguration
		       files for different architectures.
	demotrue     - a demonstration of a true command, needed
		       by config.
	src	     - directory of the sources of the VCG tool
	man	     - directory of the manual pages 
	doc	     - directory of the documentation files
	demo	     - directory of the sources of some small
		       utilities and demonstrations
	expl	     - directory of example specification for
		       the VCG tool

	

INSTALLATION NOTES

     1) There are three different methods of installation.

	   a) Installation by using one of the preconfigurations.
	      This is the fastest and easiest possibility to install.
	      This works only on machines that I know, and may 
	      fail in general.
	      The preconfigured files are in the directory preconf.

	      The SunView-version is installed in /usr/local/bin
	      and /usr/local/man/manl. It is called vcg.

	      The X11-version asks xmkmf (or imake) for the pathes
	      of BINDIR and MANDIR and installs there. You should
	      have a working xmkmf.
	      The X11-version normally uses a courier-14 font as 
	      default font (Exception: ULTRIX: fixed-bold 13). 
	      The X11-version is called xvcg.

           b) Installation by using the config script. This allows
	      to create a very specific setup. The config script
	      asks interactively for different pathes, compilers,
	      options, the default font, etc. Here, you can setup
	      very individually.
	      This may be appropriate, if none of the standard 
	      configurations is appropriate.

           c) Installation by hand. This is only needed, if b) fails
	      for some reason.
	      Installation by hand means that you edit the CHANGE AREA
	      of the files tMakefile, src/globals.h and demo/demo.csh.
	      To do so, you must first create these files, either by
	      using a preconfiguration as mentioned in a), 
	      or by using the config script in b), 
	      or by copying the files
		preconf/tMakefile -> tMakefile
		preconf/globals.h -> src/globals.h
		preconf/demo.csh  -> demo/demo.csh

     2) INSTALLATION BY USING A PRECONFIGURATION

	If you are using gcc to create a standard X11 version of
	VCG that is called xvcg and is installed in the directories
	bin and man/manl in the home of X11, simply type 

		make
		make install 
		make distclean
	Ready.

	Otherwise:

	First make sure that tMakefile does not exist on the top level.
	If it exist, then it remained from a previous try of installation.
	Remove it:

		rm -f tMakefile

	You should decide whether you want to have a X11 version or
	a SunView version, and which compiler you want to use.
	Depending on that, you do one of

		make xvcg_gcc        (for a X11 version made by gcc)
	or	make xvcg_cc         (for a X11 version made by cc)
	or	make xvcg_c89        (for a X11 version made by c89 on HP-UX)
	or	make vcg_gcc         (for a SunView version, gcc)
	or	make vcg_cc          (for a SunView version, cc)

	On ULTRIX, there is only a preconfiguration for gcc.

	On IBM AIX systems, where xmkmf was not available, I succeeded
	with
		make xvcg_gcc_noxmkmf
	or
		make xvcg_cc_noxmkmf

	On HP-UX systems, where xmkmf was not available, I succeeded with

		make xvcg_c89_noxmkmf

	The xvcg_* specifies a X11 version, the vcg_*  specifies a 
	SunView version. gcc specifies the GNU ANSI C compiler,
	cc specifies the usual compiler. On HP-UX systems, c89 can
	also be specified. 

	The meaning is:
	On SunOS:      cc  =   K&R C 
	On IRIX:       cc  =   MIPS ucode CC (ANSI C)
	On AIX:        cc  =   XL R6000 CC (ANSI C)
	On HP-UX:      cc  =   K&R C
		       c89 =   POSIX ANSI C 
	On Linux:      cc  =   gcc 

	On success, you should now have a file tMakefile.
	Now continue with step 5)
		
     3) INSTALLATION BY USING config

	Enter /bin/sh config   or  make configure.

	On a ULTRIX machine, enter    sh5 config

	This starts the shell script config, which asks you a lot
	of questions. The questions are self-explained. 
	Don't worry about complaints of missing *.dvi-files,
	*.ps-files, or missing generators like bison, flex, latex, etc.
	In the most cases, these warnings are not relevant.

	After a successful run of config, you should now have a file 
	tMakefile.
	Now continue with step 5)

     4) INSTALLATION BY HAND 

        This is only necessary, if 'make configure' does not work, or
        if you want to make small changes after `make configure'.
	First look for the files tMakefile, src/globals.h and demo/demo.csh.
	If they don't exist, copy the corresponding files from preconf.
		preconf/tMakefile -> tMakefile
		preconf/globals.h -> src/globals.h
		preconf/demo.csh  -> demo/demo.csh

	In these files, there are marked CHANGE AREAS. Please edit these
	according to your needs.

	demo.csh is only used, if you want to see the demonstration 
	(see make test).

     5) On a ULTRIX machine (DecStation), we had some problems with
	paths. On these machines, you should now go into the directory
	src and run the script ultrixpreconf, i.e. enter "csh ultrixpreconf".
	Further,  perhaps the font fixed-bold or the font Courier is not 
	available.  Please edit the file src/globals.h at the place 
        VCG_DEFAULT_FONT to select another font. 
 
        Now you are ready to compile and install. This is done by

		      ( make depend )      
			make vcg    or     make xvcg
		      (	make install )
			make test  
		      (	make clean     )
		      (	make distclean )

	Messages like  "sh: parsegen: not found"  can be ignored.

	If the files grammar.y, grammar.l or grammar.h are not found,
	then there is the same path-problem we had on a ULTRIX system.
	Please go to the directory src and run the script "ultrixpreconf".
	Then try again.

	Note: If you use Linux and gnu-make, make install may yield
	a infinite recursion, even if it works correctly. It simply
	does not terminate.
	In Linux, before "make test", you have to adapt the file
	demo/demo.csh by hand, i.e. to change all /bin/echo into
	/usr/bin/echo. If you use a preconfiguration, this is already
	done.

	IMPORTANT: be careful if the environment variables LIBPATH or
	BINPATH are set by your shell. Then, something may not work.
	In this case, unsetenv LIBPATH and unsetenv BINPATH in your
	shell. Further, it may be necessary to set SHELL=/bin/sh
	(or SHELL=sh5 on ULTRIX).

	make depend is normally not necessary. make install does the
	installation. It is a good idea to check that the directories
	exist where you want to install something before you do
	make install.  Not in all cases, the installation directories can 
	be created automatically.  make clean  or  make distclean 
	clean the directories.
	If this was successful, we are ready. If not, see the following,
	what happens.
	
     6)	If you think it is necessary, type the command at top level

		make depend

	In all subdirectories, a `make depend' is executed. This adds
	the dependency relations of the source files to the Makefiles.

     7) To compile the VCG tool and all demo's, type the command

		make vcg
	or 
	 	make xvcg 

	This compiles the program vcg|xvcg in src and some small 
	utilities in demo.

     8) To install the binaries and manual pages, type the command

		make install

	In all subdirectories, a `make install' is executed.

     9) To cleanup, type one of the commands

		make clean
		make targetclean
		make veryclean
		make distclean

	Clean means, that all object files and temporary files are 
	deleted.
	Targetclean means, that the binary executables are removed
	from the source directories. This is useful after a call
	of `make install'.
	Veryclean means, that all generated sources are deleted.
	WARNUNG: It may be that you don't have all generators that are 
	needed to regenerate after a veryclean. Thus you should
	avoid veryclean in this case !!!
	Distclean cleans everything unless the files that are in
	the original distribution.

     10) If you want to learn how to use the VCG tool, or if you
	want to test the VCG tool, then run demo.csh in the 
	directory demo.
	Alternatively, you can type

		make test
	or
		make demonstration

	It is useful to make test before make clean.

     11) If you want to make only the documentation, you can type

		make docu
	or
		make documentation

	A short (may be incomplete) documentation can be made by

		make shortdocu

	See doc/README for more information about the documentation
	format.

     12) Typical warnings that may occur during the compilation and
	 installation:

	   a) Unused variables (in drawlib.c, grprint2.c, PSdev.c)
	      occur, because the same code is used several times
	      in these modules, and not all variables are needed
	      each time.
	      I hope that the C optimizer will eliminate this drawback.

	   b) Statement not reached: Here, some assertions are
	      fullfilled such that the unreached statements are not
	      necessary. I sometimes check the system by assertions. 

	   c) Address operand '&' in front of address expressions occur
	      if a function is passed as parameter. Some compiler 
	      require the operand '&' in this case. ANSI compiler
	      should ignore the operand '&', because it is not necessary.

	   d) The messages "not_available  not found", or "bison not found"
	      or "flex not found" or "parsegen not found" during the
	      installation are not fatal.
	      In these cases, one of the preconfigured files is taken
	      instead of the generated one.

	  All these warnings are not fatal and can be ignored !


FURTHER REMARKS 
	In one of the previous distributions, I started to include a 
	version number starting at V.1.0.  Before, I had included a 
	revision number, but this is not appropriate, because it is 
	simply the number of the version control file of main.c.

	Okay: the first release was VCG, no version,  revision 3.4
	The newest release is       VCG, version 1.1, revision 3.13
	I hope nobody is confused by this. 

	If you have successfully tested the tool VCG on a new machine 
	or with a new operating system that I still don't know, please 
	send me the files tMakefile, src/globals.h and demo/demo.csh.
	On problems/warnings, please add a problem description.

	My mail address:   sander@cs.uni-sb.de

	Please read the documentation, the manual pages, and the files
	doc/README*. The documentation is a file "visual.dvi" (or 
	"vis_short.dvi") that is generated in the directory doc.
	Last minute changes are documented in doc/README*.

	The printer driver and printer utilities in the directory
	demo are written as demonstration, how to deal with PBM files.
	Because there are many printer types in the world, I cannot
	write a printer driver for every type.
	However, many printer drivers are already in the PBM-distribution.

	The documentation in LaTex uses PostScript files for pictures
	and screen dumps. If no PostScript printer is available, a
	short documentation can be made that only describes the usage
	of the tool by 

		make shortdocu

	The short documentation is called vis_short.dvi.
	Making this short documentation needs pictex and a big latex. 
	Some pictures in the short documentation are rather ugly.


PROBLEMS

     1) The X11 version of VCG has the `InputFocus' problem. 
	This problem depends on the X11 installation and the window
	manager you use.
	After starting and opening the window, the input focus of
	any X11 program is not set to the window, even if the cursor 
	points into the window. As consequence, any input into the
	window is ignored; it is handled as if it would be input
	of the old window that was input focus before starting VCG.
	Nearly all demoprograms of the X11/mit distribution have this
	problem. The user can solve it by moving the cursor one time
	out of the program's window and back into the window. 

      SOLUTION IN THE VCG TOOL:	
	If NOINPUTFOCUS is undefined (see src/globals.h) the VCG tool
	behaves like this:
	The VCG tool tries to solve this problem by setting the input 
	focus actively by XSetInputFocus when startup VCG. This 
	implies that the input focus after a successful start is 
	set correctly to the window the curser points to.
	However, this works only in 99 % of all cases. In some non-
	deterministical cases, the X11 window system notifies a
	`Bad Match Error on XSetInputFocus'. In this case, you should
	define NOINPUTFOCUS when making the tool, or you should use
	the option -grabinputfocus.
	Sorry, but this problem can only be solved by an X11 wizard.
	Hints are wellcome.

     2) (solved)

     3) On color screens, the tool may fail in the startup phase, if
	not enough colors are available. The VCG tool need 32 colors
	and tries to allocate them constructively. If other tools
	(e.g., programs that set the root window to colored background
	pictures) allocate colors destructively, it may happened that
	less than 32 colors are available. 

      SOLUTION 
	Do not use such programs at the same time as the VCG tool
	or call the VCG tool without colors (flag -nocolors).

     4) The default font may not be available. In this case, the VCG 
	tool fails in the startup phase.

      SOLUTION
	Install the default font, or call the VCG tool with an 
	appropriate font (flag -font).

     5) If gcc version 2.4.5 is used, you should not link with
	option -static, because this causes some strange effects.
	For example: xvcg -display something:0.0 does not work
	anymore. Colors are strange, etc.
	This may happen on other versions of gcc, too. 
	Be careful !

      SOLUTION
	Use another version of gcc, another C compiler or don't 
	link statically. 

     6) On some machines, the drawlib is too large to be compiled.
	Typically, I got messages "internal compiler error" in this
	case. This happened mostly on IBM AIX systems.

      SOLUTION
	Add -DDRAWLIB_TOO_LARGE to the list of CFLAG's in the tMakefile.
	If this does not help, do not use the optimizations of your
	compiler, i.e. not the -O flag of your compiler.
	In both cases, the performance of the VCG tool is reduced.

     7) Some C libraries don't contain certain functions:

	     * alloca is used by bison generated code. 
		(This is one of the small ugly disadvantages of this 
		 excellent parser generator).
	     * getwd is used by the file selector box.
	     * irint is used by the PostScript device driver.

      SOLUTION
	Add certain definition to src/globals.h. Examples:

	#define alloca(x) (malloc(x)) 
	#define getwd(x)  (getcwd(x,1023)) 
	#define irint(x)  ((int)(x)) 

	As an example, see the adaptions I have made for HPUX systems
	at the end of src/globals.h.
	If malloc is used instead of alloca, the parser does not free
	its memory, i.e. more memory is used than necessary.
	If getcwd is used instead of getwd, the file selector box
	is much slower. Hopefully, getcwd is available on the most
	Unix systems.
	If type casts are used instead of irint, the behaviour on
	overflow is not defined anymore. Further, ugly rounding errors
	may occur during the PostScript output.

     8) The bison version 1.16 does not work correctly. If you have used 
	it, the typical message "Unexpected $<start/end of input>$ ..."
	may appear on specifications, that are perfectly correct.

      SOLUTION
	Do not use bison 1.16. Set YACC=not_available in the tMakefile
	instead.
 
     9) The demo sequence that is executed on "make test" does not 
	start the tool vcgdemomaker (message: vcgdemomaker not found,
	... cannot execute).
	This happended on IBM AIX systems.

      SOLUTION
	Try to "make install" before "make test". 
	On SunOs systems, you can do "make test" even without
	"make install", but on IBM AIX systems, this feature does
	not work. I don't know why; I'm not an IBM AIX specialist.

     10) The animation demo at the end of the demo sequence that is
	 executed by "make test" does not work.

       SOLUTION
	 The timing behaviour of your system is different than that
	 of my computer. E.g. if you have discless ELCs connected by
	 NFS, the network may be too slow. By changing some integers 
         in the source of the files demo/animation1.c and 
	 demo/animation2.c would solve the problem.
	 But you will probably not want to change that files.
	 Simply ignore this. Note: the animations are the end of
	 the "make test" show, so you don't miss something important
	 if you do not see them. 
		
     11) On a HP-UX system, I did not succede to compile VCG with
	 X11R4. I don't know why.
	 However, I was successful with X11R5 on that machine.

       SOLUTION
	 Use X11R5 or X11R6 on HP-UX systems.

     12) On Linux systems, some targets of make like "make clean",
	 "make install" etc. yield a infinite recursion.
	 To my surprise, make install works properly, except the fact that
         it installs infinitely often.
         The reason is probably the incompatible behaviour of gnu-make 3.68.

       SOLUTION
	 Break install by "control-C" after a while.
	 Or install by hand. 

     13) Linux does not have /bin/echo, such that /usr/bin/echo must
	 be used in demo/demo.csh

      SOLUTION
	 Adapt demo/demo.csh by hand, i.e replace all occurences 
	 of /bin/ech by /usr/bin/echo.

     14) After the first animation in the sequence of "make test",
	 the curser may not focus in the main window. The reason is
	 probably some strange behavior of the window manager.
	 The effect is, that you cannot enter anything into the window.
	 This occured on Linux with tvtwm.

       SOLUTION
	 Touch into the main window by the mouse. Then, the window becomes
	 active again, such that you can continue.
	 
     15) The xvcg may start and open the window, but immediately fail
	 by a bus error. Typically, nothing is drawn in the window,
	 and the mouse cursor image has not changed yet.
	 This indicates an incompatible behaviour of X11 during the
	 waiting for X11 Events. It happened on a IBM AIX and on a 
	 DecStation (ULTRIX).

       SOLUTION
	 Add -DAIX or -DULTRIX to the list of CFLAG's in the file 
	 tMakefile. This is already done, if you use a preconfiguration 
	 on a IBM AIX or on ULTRIX.
	 Now, make clean and recompile. 


AUTHORS
     Georg Sander, University of Saarland, 66041 Saarbruecken, Germany.
     Iris Lemke,   University of Saarland, 66041 Saarbruecken, Germany.
	
