This is a copy of the top level README file for the ups debugger. You should find a compressed tar file containing the current release (2.45.2) of ups in the file ups-2.45.2.tar.Z in this directory. WHAT IS UPS? ------------ Ups is a source level C debugger that runs under X11 or SunView. It runs in a window with two major regions: one showing the current state of the target program data and the other showing the currently executing source code. A key feature of ups is that the variables display is persistent: when you add a variable to the display it stays there as you step through the code. The current stack trace (which function called which) is always visible. Ups includes a C interpreter which allows you to add fragments of code simply by editing them into the source window (the source file itself is not modified). This lets you add debugging printf calls without recompiling, relinking (or even restarting) the target program. You can also add conditional breakpoints in a natural way - you just add a statement like "if (i == 73) #stop" at the appropriate place in the source window. Some things you can do with ups: + Add variables to the display by simply clicking on them in the source window. + Expand (recursively) structures and unions to show their members. + Assign to variables by editing the displayed value. + Add breakpoints by pointing with the mouse at the line where you want execution to stop. + Add interpreted code at any breakpoint, including code that calls compiled functions and assigns to variables. It's hard to describe an interactive application in a few paragraphs of text - the best way to see what ups is like grab a copy and try it. There's a walkthrough debugging session in the manual page: if you work through this and aren't hooked at the end of it then I'll give you your money back :-) HOW UPS DIFFERS FROM XXGDB, XDBX AND DBXTOOL -------------------------------------------- The key implementation difference between ups and the various X front ends for dbx and gdb is that ups is not a front end for a command based debugger. Xdbx and xgdb give you a convenient way to invoke the underlying debugger's commands, but it is fairly clear in both that you are talking to a text based debugger. Ups in the other hand is a complete native debugger implementation; there is no underlying command language. An example: to print the value of a variable in xgdb you select (by dragging) a variable name and then click on `print' in the menu. Xgdb passes the print command with the selection to gdb and displays the result. By contract in ups you click the mouse over a variable name and it is added to the display. Once the variable is added to the display it stays there, so you can watch it change as you step through the code. If the variable happens to be a structure or a pointer to a structure you can `expand' it to show its members. Again, the structure members thus added remain in the display until you get rid of them so you can watch their values change as you execute the code. Of course there is a downside to not talking to an existing debugger: you lose portability. Ups is machine dependent - a port to a new architecture is a significant effort. I think the benefits outweigh the cost. SUPPORTED CONFIGURATIONS ------------------------ The current list of supported configurations is: Architecture OS version Window system ------------ ---------- ------------- SPARC SunOS 4.X X11 or SunView 1 Sun 3 SunOS 4.X X11 or SunView 1 Sun 386i SunOS 4.0.X X11 or SunView 1 DECstation Ultrix 3.X and 4.2 X11 Intel 386 BSDI BSD/386 0.3 Beta X11 HLH Clipper 4.3BSD X11 [ You've never heard of the HLH Clipper. Don't worry, you're not alone. ] Ups has also been ported to the Sony NEWS (MIPS) workstation (by Nobuyuki Hikichi) and to the MIPS Magnum 3000 (by Hal R. Brand and Conor Doherty). I have folded these changes into the code but I don't have access to the machines to test them directly. Ups has FORTRAN support on the Sun 3 and SPARC but this is not as stable or complete as the C support. Ups should also work with gcc (even with the -O flag). This is known to work pretty well on the SPARC; your mileage may vary on other systems. Unlike earlier releases, the current version of ups works with gcc 2.X (except on the DECstation). Ups will probably work on OS releases other than these; the list above describes the OS versions on the machines that I have access too. In particular I have built ups for a VAX 750 running 4.3BSD and X11 - it appeared to work OK but wasn't tested thoroughly or used in anger. Ups is unavoidably architecture and OS dependent as it knows about things like the ptrace() system call interface and object file symbol table formats. A port to a new architecture is likely to take several weeks. INSTALLATION ------------ Ups should be reasonably simple to install. It has no library files, just a binary and manual page. You can put the binary and manual pages where you like. There is no need to be root to do any part of the installation (although you must obviously have permission to create files in the directories where you put the binary and manual page). The steps are: 1) Unpack the distribution. You should have a compressed tar file called ups-2.XX.tar.Z (where 2.XX is the version number of the release). Change directory to a disk with a three or more megabytes of free space and say: zcat ups-2.XX.tar | tar xfp - This will create a directory tree called ups-2.XX. Change directory into it. 2) If you wish to use imake then say "sh imake.sh" at this point and skip to step 4. This will unpack Imakefiles from the file imakefiles.tar and run xmkmf to build makefiles. The Imakefiles were written by Rainer Klute (klute@irb.informatik.uni-dortmund.de). If you are building the SunView version of ups, or do not have imake or xmkmf then skip this step and use the supplied makefiles. 3) Optionally edit the Makefile in this root directory. You might want to do this if you want to specify special flags to to compiler (for example if your X header files live somewhere other that /usr/include/X11). You might also want to change the default locations of the installed binary and manual page. 3a) If you are building ups on a Sun (of any architecture) running SunOS 4.0.3 or earlier, uncomment the line in the Makefile in this directory that sets SUBMAKEFLAGS to ARCH_CFLAGS=-DFIX_SHORT_PARAMS. See the comment in the Makefile for more information. 3b) If you are using a MIPS RISC/os machine, uncomment the SUBMAKEFLAGS line for RISC/os. If you are running RISCwindows then uncomment the X11LIB line just below the SUBMAKEFLAGS line. 4) Type "make". If all goes well this should build you a binary called ups/ups. If you want the SunView binary, say "make sunviewups". This will produce a binary called ups/sunviewups. The BSDI make and sh (at least on the Beta 0.3 release) have some bugs which are triggered by the ups makefiles. If you are not using imake (which also failed for me on BSDI), you can use the following evil runes to make ups build: make ups/develhdrs libx11wn make SUBMAKEFLAGS="-n | sh -x" If you want you can experiment with ups at this point. The manual page (in ups/doc/ups.man) has a "GETTING STARTED" section which should get you going. 5) Type "make install". By default this will install ups/ups as /usr/local/X11/ups and the manual page as /usr/man/manl/ups.l. To install the Sunview version of ups say "make sunviewinstall". By default this will install ups/sunviewups as /usr/local/Sunview/ups. If you don't wish to run "make install" you can install ups simply by copying the binary and manual page into place. DOCUMENTATION ------------- The following files contain documentation on ups: ups/doc/ups.man The user manual page ups/doc/porting.ms A guide to porting ups to a new architecture. README.multiarch Description of a scheme for doing simultaneous builds of ups in one NFS mounted source directory on multiple architectures. lib/*/README Brief overviews of the various libraries used to build ups. Some have pointers to more documentation. COPYING THE CODE ---------------- Feel free to copy bits of ups for your own use (caveat: you must contact me first if you want to incorporate the code into a commercial product). You must preserve the copyright notices. Things you might find useful (despite the lack of documentation): ups/ci_*.[cy] A reasonably complete ANSI C interpreter. There are many details that it gets wrong (e.g. the exact type of integer constants and the subtler aspects of typedefs). There is a test driver in ups/cx.c. The grammar is in ups/ci_parse.y. This was derived from the grammar at the back of K&R2. ups/as_*.c Disassemblers for the 68020, SPARC, VAX and MIPS chips. lib/libmtrprog/genmergesort.h A macro to implement a merge sort function for any linked list. lib/libukcprog/*.c Various low level routines that aren't in the standard C library. lib/libarg/*.c General purpose command line parsing, including filename globbing and I/O redirection. One day I might get round to documenting all this stuff ... FEEDBACK -------- I hope you find ups a useful tool. If you have problems building or using it, find bugs or have suggestions for improvements please send me mail (I am mtr@ukc.ac.uk). Paeans of praise describing how wonderful ups is are also appreciated :-) There is a mailing list for discussion of ups and for announcements of bug fixes and new features. The list is ups-users@ukc.ac.uk - send requests to be added to the list to ups-users-request@ukc.ac.uk. I'm especially interested in ports to new architectures. There is a document (ups/doc/porting.ms) giving an overview of the implementation of ups and how to port it. I'll be happy to give advice and help to anyone doing a port, and even happier to incorporate completed ports back into the standard release. A personal note: I have benefited enormously from free software that others have contributed (things like perl, gcc, X and BSD). Ups is my attempt to give something back. Long live free software. Mark Russell mtr@ukc.ac.uk