# @(#)README	3.32 17/06/98

This directory contains the source code of the ups debugger.
This file describes what ups is, what it runs on and how to build
and install it.  The file CHANGES in this directory summarises
the changes between this release and previous public releases.


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 contrast 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		
	------------		----------		
	SPARC			SunOS 4.X, Solaris 2.X		
	Sun 3			SunOS 4.X		
	Sun 386i		SunOS 4.0.X		
	DECstation		Ultrix 3.X and 4.2	
	Intel 386		BSDI BSD/386 0.9 Gamma	
	Intel 586		Linux 2.0.31 (ELF), FreeBSD 2.2.2

This beta release has only been tested on the SPARC under SunOS 4 and
Solaris 2.  Support for the other architectures will be fixed or
deleted in a future release.

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

You can optionally build ups using a modified version of gdb - see
README.gdb for details.


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

See README.gdb for instructions on building the gdb-based version of ups.
To build the native version, follow the following steps:

1)  Unpack the distribution. You should have a compressed tar file called
    ups-3.XX.tar.Z (where 3.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-3.XX.tar | tar xfp -
 
    This will create a directory tree called ups-3.XX.  Change directory
    into it.
 
2)  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.

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

3a) If you are using Linux such as Red Hat 5.0, uncomment
    the X11LIB line just below the "X11LIB = -lX11" line.

Note: If you are using cc under Solaris 2, make sure you are using
      the standard /opt/SUNWspro/bin/cc and *not* picking up /usr/ucb/cc.
      /usr/ucb/cc will use header files from /usr/ucb/include, which
      will make the compilation fail.

      Similarly, if you are using cc under SunOS 4, make sure you get
      the standard /usr/ucb/cc (or /usr/bin/cc) and *not* /usr/5bin/cc.
      
4a) Under Solaris 2, if you are using SPARCcompiler C 2.0.1 or less,
    say `make CFLAGS="-g -DSVR4".  If you are using SPARCompiler C
    3.0.1 or greater, or gcc, you can just say `make'.

4b) Under SunOS 4, or Linux, type "make RANLIB=ranlib SVR4_LINKFLAGS="

    If all goes well this should build you a binary called ups/ups.

    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/local/man/man1/ups.1.
    
    If you don't wish to run "make install" you can install ups simply by
    copying the binary and manual page into place.

6)  Optionally copy the Ups resource file to 
    /usr/lib/X11/app-defaults/app-defaults.



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
		Various low level routines that aren't in the standard
		C library.

lib/libarg	General purpose command line parsing, including filename
		globbing and I/O redirection.

lib/libedit	Emacs style editing in an X window

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).  I also appreciate paeans of praise
describing how wonderful ups is :-)

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.

A personal note: I have benefited enormously from free software
that others have contributed (things like emacs, perl, gcc, X and BSD).
Ups is my attempt to give something back.  Long live free software.

Mark Russell
mtr@ukc.ac.uk


17 June 1998
------------
Mark Russell has decided to let the "RGA" contrib release become the 
"official" release, as he is unlikely to be able to work on ups in 
future. Consequently, I've dropped the `RGA' suffix in this version.

Rod Armstrong
rod@san-jose.ate.slb.com
