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 
     X11. (An older version runs on Sunview).

     The VCG tool has been developed and tested on a Sparc ELC with
     SunOs 4.1.3, X11 Release 5 and Release 6, and different ANSI C 
     and K&R C compilers. It has further been tested on Solaris
     (SunOs 5.3, gcc only), 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), on Linux (X11R5, gcc),
     and on OSF (X11R5, gcc). A user ported the tool to VAX/VMS,
     but this port is currently not fully integrated.
     For the tests on these machines, see README.SYS. This may also
     help for a setup on other machines.


LICENSE CONDITIONS
     Copyright (C) 1993-2005 Saarland University

     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.


A SPECIAL REMARK ABOUT LICENSE CONDITIONS
     We would certainly like to continue to distribute the documented 
     sources freely, but currently we have the situation that we cannot
     continue in this programmer-friendly way as before.

     Thus, we have uglified some of the files in the distribution: these 
     are the graph layout modules. These files are not anymore readable 
     for human being, but they are readeable for the compiler. Thus you 
     can compile the sources as before, but you cannot find out anymore 
     how the details of the layout algorithms work.

     This is a compromise. I think this is a better solution than to 
     distribute binaries, because the users still can adapt the tool to
     their computer system. (In the layout modules, normally no adaption
     is necessary). Further, we did not spent too much time with 
     uglification, thus the result should not be too ugly ;-)


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

     0) For the installation on a VAX/VMS, see the special remarks
        in preconf/X11VMS/README.vms.

     1) For UNIX systems, 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.
	(Currently, the SunView version is not anymore supported.)
	Depending on that, you do one of

		make xvcg_gcc        (for a X11 version made by gcc)
	or	make xvcg_g++        (for a X11 version made by g++ on SunOs)
	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 SunOS, gcc should be preferred before g++. But g++ works, too:
        The VCG tool is C++ compatible.

        Note that the SunOS preconfiguration is for SunOS 4.xxx. It
        will also work for Solaris (SunOS 5.3), except that make install
        will probably not work.  See section PROBLEMS. 

	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 (but should be avoided, if possible). 

	The meaning is:
	On SunOS:      cc  =   K&R C 
		       g++ =   the Gnu g++  
	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 OSF1:       cc  =   /usr/bin/cc (near ANSI C) ???

	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 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.

	Further, people reported problems with some versions of gnu-make.
	Although I tried to solve these problems in this new version
	of the VCG tool, it is probably better to use /bin/make instead.
	Setting
		alias make /bin/make

	might help in such situations.

	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 in these steps.
	
     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 xvcg 

	This compiles the program 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) 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.3, revision 3.17
	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.ps" 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.


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. The problem does not occur with gcc 2.6.3. 

     6) 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.

     7) 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.
 
     8) 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.

     9) 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. 

     10) On Solaris (SunOS 5.3), the dynamic libraries of X11 are 
         sometimes not found. Typical messages are something like this:
 
          ld.so.1: xvcg: fatal: libXext.so.0: can't open file: errno=2
          Killed


       SOLUTION
         A user of the VCG tool recommended to add -lsockets to the
         list of libraries, but on our test system, we had no success
         with this.
         In the environment, we set 

         	LD_LIBRARY_PATH=/usr/openwin/lib:/usr/lib:/lib

         Then, we had success and everything was okay.

     11) On Solaris (SunOS 5.3), /bin/install does not exist, thus the
         preconfiguration is wrong (it is for SunOS 4.3.1). 

       SOLUTION
	 We used /usr/ucb/install instead of /bin/install, i.e. in
         tMakefile

           INSTALLDIR = /usr/ucb/install -d -m 755
           INSTALL    = /usr/ucb/install -s -m 755 dummy /home/me/bin/dummy
           INSTALLMAN = /usr/ucb/install -m 644 dummy /home/me/man/manl/dummy

         The real problem is, that both SunOS 4.x and Solaris are reported 
         as 'SunOS' to the Makefile. Thus, the Makefile does not see the
         difference.

     12) 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.

     13) On a HP-UX system with c89, the library seems to be buggy.
         The declaration of gettimeofday is not found. Further, atof is buggy.

       SOLUTION
         I added a declaration of gettimeofday to src/timelim.c.
         But is is probably superfluous on other (newer) HP-UX systems.
         No solution for the atof problem. Try to avoid floats in your
         specification.
        
     14) 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. 

     15) 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.

     16) 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.
	 
     17) 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.
	
