XV Installation Instructions
============================
While Imakefile's have been provided for you, I recommend using the regular
Makefiles, as that's what I use.  

If you don't plan to use Imake, copy 'Makefile.std' (a regular
old-style minimalist makefile) to 'Makefile'.  (Actually, this has
already been done for you, as I prefer to just use 'make'.  This is
mainly to let you know that if you ever *do* run Imake (and thereby
trash the Makefile), there's a backup of the 'simple' Makefile in
'Makefile.std'.)

The following are installation instructions for some of the more common
types of systems.

	--------------------------------------------------------------
	SUNs running SunOS and MIT's X11R4 distribution
	DECstations running Ultrix
	HP workstations running HPUX 8.*

	On these machines, you should be able to just type 'make' and
	have everything compile cleanly.  (On the DECstation, you'll see
	some warnings about some functions being too long to be optimized.
	Ignore such messages, as those functions don't need to be
	optimized.)

	--------------------------------------------------------------
	SUNs running OpenWindows

	By default the Makefile assumes your X11 include files and the
	libX11.a library are in the 'normal places' (/usr/include/X11/*.h and
	/usr/lib/libX11.a) If this is not the case on your system, (as is
	often the case on Suns running OpenWindows) you should add '-L' and
	'-I' options on the CCOPTS line in the Makefile to tell the compiler
	where to find said files.  See the Makefile for more details.

	--------------------------------------------------------------
	DEC ALPHAs, CRAYs, and other 64-bit architectures

	The TIFF library does *not* work on 64-bit machines.  Edit the
	Makefile, find the comments about TIFF, and comment out the
	appropriate lines.

	--------------------------------------------------------------
	IBM RS/6000 running AIX

	On an IBM RS/6000, you can build cleanly with one minor tweak.
	Replace tiff/Makefile with tiff/Makefile.aix, then type 'make' in the
	main XV directory.

	--------------------------------------------------------------
	SGI IRIS running IRIX

	Edit the Makefile, and turn on the SVR4 and SGI options
	
	--------------------------------------------------------------
	Other SVR4 systems
	
	Edit the Makefile, and turn on the SVR4 option.
	
	--------------------------------------------------------------


Check the Makefile for the configuration option(s).  There are
unfortunately quite a few these days, to support a number of different
machines.  


If you're using 'imake', check the options in the Imakefile, and generate
a Makefile using 'xmkmf' (or whatever).  Be sure to 'make depend'
before building the program.


The following are things to be wary of when building XV, and some
hints for building XV on some less-popular systems.


GCC USERS: It is important that the XV source and the contents of the
JPEG and TIFF subdirectories all be compiled with the same compiler.
While this should normally be the case, as the value of the CC
variable in the XV makefile is propigated to the makefiles in the
subdirectories, it's something to keep in mind.  Also, be sure to
specify '-traditional' when compiling with gcc, otherwise it'll blow
up on some code in the TIFF subdirectory.


GCC USERS: If you compile XV with gcc, and find XV crashing in the
function 'vsprintf()', the gcc-specific include files on your system
are screwed up.  You should get your sysadmin-type to fix the
gcc-include files (you can test it by compiling 'vargs.c', a simple
varargs-verification program in the unsupt directory), or alternately,
just use 'cc' instead.


HP USERS: If you are running HP-UX 7.* , you should remove the '-O'
compiler flag from the Makefile.  The optimizer supplied with that
version of the OS has been known to break code in xvgam.c (and
possibly elsewhere, as well).  You'll know the optimizer has broken
the code if pictures come out 'purple'.


DECSTATION USERS: I've had a report that compiling 'xvevent.c' with
the optimizer turned on (Ultrix 4.1, MIPS C compiler version 2.1)
breaks the routine TrackPicValues().  I haven't been able to verify
this behavior, but if you're building on this sort of system, you may
want to turn optimization off, at least for that routine.


IRIS/HP/Other SysV-based machines: If you find XV 'going out to lunch'
when you click on any of the buttons in the controls window, (or do
any of a number of other things), it is almost certainly a matter of
configuring the 'Timer()' function (in xvmisc.c) to correctly wait the
requested number of milliseconds.  This is one of those things that
doesn't seem to be very well nailed down in the different variants of
Unix.  IF you experience problems, take a look at that function, and
add an '#ifdef' for your machine that makes it use the whatever the
proper 'sleep for some number of milliseconds' call on your machine.
(Could be poll(), usleep(), setitimer(), or possibly select(), and
probably some others.)


Once you've built the program succesfully, copy the programs 'xv', 'bggen',
'xcmap, and 'vdcomp' (if you want PDS/VICAR support) to wherever you like
your binaries to live, and copy the files 'docs/xv.man', 'docs/xcmap.man'
and 'docs/bggen.man' to the approprate man-page directory.  Don't forget to
change the suffixes appropriately.  'imake' users can just say 'make
install' and 'make install.man', with any luck.


Note: also included in this distribution (in the unsupt directory) is
'getweather', a dopey little shell script that you may want to run in
a crontab entry every hour, on the half-hour or so.  It will
automagically go out and get the current US weather map via anonymous
ftp, and stick it in some standard place (normally
/usr/local/lib/weather.gif).


Finally, print out a copy of docs/xvdocs.ps on a PostScript printer.
If you are unable to do so, and would like a printed copy of the
manual, see the bit about donating $25 in the README file...


Note: If you are using 'transcript 2.1' to drive your PostScript
printer, you may run into a problem where the xvdocs.ps file prints in
the wrong font (courier, or something, instead of helvetica).  This
seems to be caused by 'psrv', which tries to reverse the pages of all
PostScript files.  It fails on this PostScript file.  You (or the
local system administrator) can temporarily fix this by replacing the
line:
  'REVERSE = /pkg/lib/ps/psrv'
with
  'REVERSE = /bin/cat'
in the file /pkg/lib/ps/psint.sh.  (Your pathnames may vary.)


Caveats
------- 
XV has been developed on a Sparc 2 running SunOS 4.1.3, using both the
normal 'cc' and gcc-2.00 compilers.  There shouldn't be anything
grotesque enough in the code to break any other compilers.  (Though
'optimizers' from HP are quite another story...)

The viewing environment has mainly been an IBM RS6000 with an 8-bit
color display.  It has been tested with MWM, TWM, OLWM, TVTWM, and
DXWM, in roughly that order of thoroughness.  (ie, I personally use
MWM, and most of the folks in the GRASP Lab use TWM.)

I have personally compiled and tested it on the following systems: Sun
4 running SunOS 4.1, VAXstation 3500 running Ultrix 3.0, MicroVax II
running Ultrix 2.0, DecStation 3100 running UWS 3.0, IBM RISC
System/6000 running AIX 3.1.

It has displayed on the following systems: IBM RT (8-bit color), Sun 3
(1-bit B/W), Sun 3 (8-bit grayscale), Sun 4 (1-bit B/W), MicroVax II
(8-bit color), MicroVax II (4-bit grayscale), a variety of HPs (4-bit
color, 6-bit color, 8-bit color, and 24-bit color), and Visual, NCD,
Tektronix, and HDS X terminals (1-bit B/W and 8-bit color).

'vsprintf.c' has been included for the benefit of those on machines
that don't have it.  (Basically, machines running 'vanilla' BSD 4.3)


Bizarrities
-----------
There are some known problems with running XV in conjunction with
'dxwm'.  I'm hoping that that is now a defunct window manager, and
that everybody who was using that will switch to mwm.  Whether this
hope is well-founded or not is another matter entirely.  See the DXWM
option in the Makefile/Imakefile.


Problems with TWM and TVTWM
---------------------------
XV would appear to exercise a pair of bugs in the version of TWM in
MIT's X11R4 Standard Distribution tape.  Perhaps they've been fixed by
now.

Colormap Installation: under twm, if you have multiple XVs running,
and each has their own colormap, sometimes the colormap doesn't get
properly installed if you move the mouse directly from one XV to the
other, quickly, so that it doesn't see the mouse go into the root
window, or any other window.  If you move the mouse outside the window
and move it back in, it SHOULD install the colormap correctly.

Colormap Installation: Note, if an alternate colormap is installed, it
will ONLY be installed when the mouse is inside the IMAGE window.  It
will not be installed when the mouse is in any other XV windows
(except, possibly, the color editor window).  This is because I can't
guarantee that the other windows will still have contrasting
foreground/background colors when the alternate colormap is installed.
It is assumed that if you put the mouse in a window, you will want to
use that window, so you'd better be able to READ that window...

There's a bug in my version of TWM that creeps up if you have
titlebars turned off.  Essentially, XV tells the window manager to
make the window a certain size.  TWM (wrongly) adds enough room at the
top to put its title bar there, but doesn't draw it, since titlebars
are turned off.  XV gets back a ConfigureNotify event on the window
with the new size, which is large by 20-odd pixels in height.

There *used* to be a '-twmkludge' option in a previous version of xv
to 'work around' this problem.  Unfortunately, this workaround
introduced more problems than it solved, and has since been removed.
The current thinking is: if you're using TWM, you should probably be
using titlebars.  If you insist on not having titlebars, and your TWM
doesn't behave properly, you should fix TWM.  (It's a one-line fix,
and I'll gladly send it to anybody who asks for it.)


Be sure to read the README file for shareware information, copyright notice,
and other such things.

--jhb,  3/12/93
