SCCS-info %W% %E% $Id$ The VCG Tool ============ A Visualization Tool for compiler graphsDESCRIPTION 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--1995 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.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.FILESREADME - this file you are reading actuallyREADME.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 featurespreconf - 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 toolman - directory of the manual pages doc - directory of the documentation filesdemo - directory of the sources of some small utilities and demonstrationsexpl - directory of example specification for the VCG toolINSTALLATION 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 filespreconf/tMakefile -> tMakefilepreconf/globals.h -> src/globals.hpreconf/demo.csh -> demo/demo.csh 2) INSTALLATION BY USING A PRECONFIGURATIONIf you are using gcc to create a standard X11 version ofVCG that is called xvcg and is installed in the directoriesbin and man/manl in the home of X11, simply type makemake install make distcleanReady.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 tMakefileYou should decide whether you want to have a X11 version ora SunView version, and which compiler you want to use.(Currently, the SunView version is not anymore supported.)Depending on that, you do one ofmake 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 succeededwithmake xvcg_gcc_noxmkmformake xvcg_cc_noxmkmfOn HP-UX systems, where xmkmf was not available, I succeeded withmake xvcg_c89_noxmkmfThe 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 canalso 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 configEnter /bin/sh config or make configure.On a ULTRIX machine, enter sh5 configThis starts the shell script config, which asks you a lotof 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 -> tMakefilepreconf/globals.h -> src/globals.hpreconf/demo.csh -> demo/demo.cshIn these files, there are marked CHANGE AREAS. Please edit theseaccording 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 withpaths. On these machines, you should now go into the directorysrc 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 yielda infinite recursion, even if it works correctly. It simplydoes not terminate.In Linux, before "make test", you have to adapt the filedemo/demo.csh by hand, i.e. to change all /bin/echo into/usr/bin/echo. If you use a preconfiguration, this is alreadydone.Further, people reported problems with some versions of gnu-make.Although I tried to solve these problems in this new versionof the VCG tool, it is probably better to use /bin/make instead.Settingalias make /bin/makemight help in such situations.IMPORTANT: be careful if the environment variables LIBPATH orBINPATH are set by your shell. Then, something may not work.In this case, unsetenv LIBPATH and unsetenv BINPATH in yourshell. Further, it may be necessary to set SHELL=/bin/sh(or SHELL=sh5 on ULTRIX).make depend is normally not necessary. make install does theinstallation. It is a good idea to check that the directoriesexist where you want to install something before you domake 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 levelmake dependIn all subdirectories, a `make depend' is executed. This addsthe 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 commandmake installIn all subdirectories, a `make install' is executed. 9) To cleanup, type one of the commandsmake cleanmake targetcleanmake verycleanmake distcleanClean means, that all object files and temporary files are deleted.Targetclean means, that the binary executables are removedfrom the source directories. This is useful after a callof `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 shouldavoid veryclean in this case !!!Distclean cleans everything unless the files that are inthe original distribution. 10) If you want to learn how to use the VCG tool, or if youwant to test the VCG tool, then run demo.csh in the directory demo.Alternatively, you can typemake testormake demonstrationIt 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.4The newest release is VCG, version 1.3, revision 3.17I 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.dePlease read the documentation, the manual pages, and the filesdoc/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 directorydemo are written as demonstration, how to deal with PBM files.Because there are many printer types in the world, I cannotwrite 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 windowmanager you use.After starting and opening the window, the input focus ofany X11 program is not set to the window, even if the cursor points into the window. As consequence, any input into thewindow is ignored; it is handled as if it would be inputof the old window that was input focus before starting VCG.Nearly all demoprograms of the X11/mit distribution have thisproblem. The user can solve it by moving the cursor one timeout 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 toolbehaves 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 shoulddefine NOINPUTFOCUS when making the tool, or you should usethe 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, ifnot enough colors are available. The VCG tool need 32 colorsand tries to allocate them constructively. If other tools(e.g., programs that set the root window to colored backgroundpictures) allocate colors destructively, it may happened thatless than 32 colors are available. SOLUTION Do not use such programs at the same time as the VCG toolor 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. SOLUTIONInstall 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 withoption -static, because this causes some strange effects.For example: xvcg -display something:0.0 does not workanymore. Colors are strange, etc.This may happen on other versions of gcc, too. Be careful ! SOLUTIONUse 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. SOLUTIONAdd 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 systemsat the end of src/globals.h.If malloc is used instead of alloca, the parser does not freeits memory, i.e. more memory is used than necessary.If getcwd is used instead of getwd, the file selector boxis much slower. Hopefully, getcwd is available on the mostUnix systems.If type casts are used instead of irint, the behaviour onoverflow is not defined anymore. Further, ugly rounding errorsmay occur during the PostScript output. 7) The bison version 1.16 does not work correctly. If you have used it, the typical message "Unexpected $$ ..."may appear on specifications, that are perfectly correct. SOLUTIONDo not use bison 1.16. Set YACC=not_available in the tMakefileinstead. 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. SOLUTIONTry 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 doesnot 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.