V9/jtools/README

This directory contains some tools which run under X11 and Sunview
which are derived from the 9th Edition 5620 tools.  Manual pages for
the tools are in man/man1.  See jtools.1 for an overview.

To use them, just put /usr/jtools/bin in your PATH.  If you are planning
to use pi on a Sun system running SunOS release 3.5 or earlier, the above
directory should be before /usr/ucb in your PATH as there is a pi
(Pascal Interpretor) there.
The files in /usr/jtools/bin are all links to the same shell file.
This file attempts to figure out which window system is running
and determine the architecture of the machine to select the
appropriate binaries.   To install the directory somewhere else
it will only be necessary to edit the DIR= line in the bin shell file.

Some of the programs (pi and sysmon) read kernel memory.  In SunOS
release 4.0 this access is restricted to the group kmem.  For these
programs to work correctly, the following must be done by a super-user
of the system:
	chdir /usr/jtools/xxbin;
	chgrp kmem pi sysmon;
	chmod 2755 pi sysmon;
where xx is either s2,s3,s4,x3, or x4 dedending on the machine architecture
and window system used. This does not need to be done for SunOS releases 3.5
and earlier.  If the permissions are not changed on 4.0 releases, sysmon
won't work and pi will not allow examination of kernel data structures.

A list of the subdirectories (some of which may be missing)
and their contents is shown below:

	man:		Man pages
	doc:		Documentation (TMs)
	src:		Source code for tools and 5620 emulator library
	lib:		Emulator libraries
	include:	Include files for emulator library
	bin:		Common bin (a single shell file with multiple links)
	s2bin		sun-2 sunview binaries
	s3bin		sun-3 sunview binaries
	s4bin		sun-4 sunview binaries
	x3bin		sun-3 X11 binaries
	x4bin		sun-4 X11 binaries

A list of the currently ported tools (in bin) is given below:

	Jpic -	parses pic input for cip. Not called directly by the user.

	blitblt - Interactive screen dumping program.  Output files
		are in Ninth Edition bitfile format and can be converted
		to PostScript and other printer languages using filters.
		This program ONLY works with monochrome displays.

	cip -	Drawing program which generates pic output.

	cleave - Separates C++ header files into private and public parts
		for efficiency in big applications.  Used to generate pi.

	hang -	Used to stop a process before it executes the first instruction
		so pi can attach to it.  Useful when you don't want to start
		the process from pi (if started from pi, it redirects the
		standard input and output to /dev/null).  Don't use this
		with dbx unless you are willing to reboot your machine
		with SunOS releases 3.5 and earlier.

	icon -	Icon editor.

	pads -	Terminal half of pi. Not called directly by the user.

	pi -	Tom Cargills process inspector: a window based debugger
		with a very nice user interface.  Currently not available
		for Sun 4's.

	rtpi -	Real-time pi.  Used to remotely debug real-time processors
		over Ethernet.

	sam -	A mouse/screen editor with a powerful command language
		written by Rob Pike.

	sux -	an interactive terminal program which emulates the
		terminal interface provided by mux terminal windows.
		Text can be edited anywhere on the screen using an
		interface which is very similar to sam.

	sysmon - Bar style load monitor.  Looks best when it is
		long and skinny.

	tek -	Tektronix 4014 emulator

	xsamterm - Terminal process for sam. Not called directly by the user.

	Games:
		asteroids - Use mouse buttons to control.
		life -	Use left and middle mouse button to control.
		pacman - Instructions on startup.
		swar -	Use asdwx and kl;o. keys to control.
		The games don't work very well with X11.

Feel free to give the binaries to other AT&T employees.
However, I would appreciate if you would send me the names of people
who receive it, so I can notify them when bugs are fixed.

If you have any problems, please contact me (email preferably).

	Dave Kapilow
	alice!dak
	(201) - 582 - 3596
	MH 2B-424