README

Here is the original README for InterViews 3.1.  Ignore the installation 
instructions; to install it, see the file INSTALL instead.

This version of interviews has been hacked from the original
distribution to be portable to a few more platforms, and to use an
autoconfigure script.  All of the imake garbage has been removed,
including the imake configuration files, the ivmkmf script, and other
related things.

Do not use this library for new development efforts!  Use a more modern
one, like gtkmm or Qt or wxwindows.  This library is only for legacy
code.

-------------------------------------------------------------------------------


		README for InterViews 3.1


The iv subdirectory in this directory contains the InterViews 3.1
distribution from Stanford University and Silicon Graphics.
You should read the release notes in iv/src/man/refman/refman.PS
for information about differences between 3.0 and 3.1.  You should
read the rest of this file for information about how to build,
install, and use InterViews.

If you have a bug report, please send it to

	interviews-bugs@interviews.stanford.edu

If you have any questions or problems, please post them in the USENET
newsgroup

	comp.windows.interviews

If you do not have access to news and you wish to be on the InterViews
mailing list which is gatewayed with comp.windows.interviews, send a
request to

	interviews-requests@interviews.stanford.edu

The mailing list alias is

	interviews@interviews.stanford.edu

Please post to only the newsgroup or only the mailing list but not
both since whatever you post in one will appear in the other too.


* What else to get


You should have gotten a C++ compiler which accepts revision 2.0 or
later of the language.  You should have installed the X11R4 or
X11R5 distribution from MIT.  If you use a vendor's X11 product,
the product should be based on R4 or later and the product
should include imake, makedepend, and the config files.

If imake and makedepend are not in the same place where the other X11
binaries are or anywhere else on your system, you can get the sources
for imake and makedepend from the X11R4 distribution at several public
ftp archives (such as expo.lcs.mit.edu).  The X11R4 distribution also
contains platform-specific configuration files (*.cf) which you must
put in /usr/lib/X11/config or a similar place before building
InterViews.


* What to do before building InterViews


You should check that you have about 50Mb of free space before you
unpack the 3.1 tar file.  If you have SunOS shared libraries, you can
get by with about 35Mb.  The InterViews source tree itself occupies
only 8Mb, but saying "make World" will add 17Mb to iv and saying "make
install" will add another 18Mb.

You should read and edit iv/src/config/InterViews/local.def before
building InterViews.  This file is the place to set parameters which
may need to be changed for your site.  To find out which parameters
you can set, read params.def in the same directory.

For example, you might add the lines

	#undef CCDriver
	#define CCDriver /usr/CC/sun4/CC
	#undef DependCCFlags
	#define DependCCFlags $(CCDEFINES) $(CCINCLUDES) -I/usr/CC/incl
	#undef SharedCCFlags
	#define SharedCCFlags -PIC

to local.def if you use Sun C++ 2.0.  Sun C++ 2.0 will not be able
to build libIV.so.3.0 unless you use -PIC instead of -pic.

You must decide whether to change the definition of InstalledRoot in
local.def before building InterViews since the name will be compiled
into InterViews applications.  For example, the application "doc" will
expect to get its menus from /interviews/lib/all/app-defaults/Doc at
startup unless you set InstalledRoot to something else before building
InterViews.

Other parameters you may also have to set are where to find the X11
config files, includes, and libraries.  If the X11 config files are
not in /usr/lib/X11/config, the X11 includes are not in /usr/include,
or the X11 libraries are not in /lib, /usr/lib, or /usr/local/lib,
then you should specify their actual locations in local.def.  For
example, you might add the lines

	#undef XConfigDir
	#define XConfigDir /usr/X11R5/lib/X11/config
	#undef XIncDir
	#define XIncDir /usr/X11R5/include
	#undef XLibDir
	#define XLibDir /usr/X11R5/lib

if you are using X11R5 and it is installed in /usr/X11R5.  You will
also have to override XCONFIGDIR when saying "make World"; see
below.

You should read the X11 platform-specific .cf file that will be used
when you build InterViews.  It probably will set a few InterViews
parameters like extra compiler flags, extra defines, or extra
libraries so you should check that all of these extra flags work with
your C++ compiler as well as with your C compiler.  If your C++
compiler will not accept some of them or it needs some additional
flags, you can set the affected InterViews parameters in the
corresponding iv-*.cf file before xparams.cf sets them.  See iv-sgi.cf
and iv-ultrix.cf for examples.  The iv-*.cf file is the only other
file besides local.def which you should ever need to change.  (If you
have to change this file, please send us the changes so we can
incorporate them in the next release.)


* How to build InterViews


After you set any necessary parameters in local.def, you can build
InterViews with the following commands (but read the rest of this
section first!):

	cd iv
	setenv CPU `make CPU`
	make World XCONFIGDIR=<actual location of X11 config files>

As the first command shows, you should be in the iv directory (below
this README) before starting to build InterViews.  

The second command assigns the name of your machine's architecture to
the environment variable CPU.  Saying "make CPU" by itself will print
the name that you should assign to CPU (MIPSEL, SUN4, etc.).  If you
do not set CPU, the Makefiles will not be able to create the
appropriate subdirectories in which to put the object code files and
you will not be able to build InterViews.

The third command builds everything for you.  If the X11 config files
are not in /usr/lib/X11/config, you must override XCONFIGDIR on the
command line as well as set XConfigDir in local.def or "make World"
will not work correctly.

You may want to redirect the output of "make World" to a file and
inspect it later since the build will take more than two hours to
complete on a system with the performance of a DECstation 3100 or
SPARCstation 1.

Once the build concludes, you can find errors in the output quickly by
searching for the character ':' (unfortunately, this will not work
very well if your C++ compiler driver prints verbose output showing
the execution of each phase).


* How to install InterViews


To install InterViews, say

	make install

in the same directory where you said "make World".  This command will
create a new subdirectory called installed and install inside this
directory everything that you will need to use InterViews.  Since
"make install" will not try to install anything outside of
iv/installed, you can say it without having to become the superuser.

The only additional step you may need to take is to create a symbolic
link elsewhere that points at iv/installed.  If you did not change the
definition of InstalledRoot in local.def, then this symbolic link
should have the name "/interviews".  This link allows InterViews
applications to find installed data files at startup time.  For
example, the application "doc" will not be very functional if it
cannot read its menus from /interviews/lib/all/app-defaults/Doc.

Once you finish the installation of InterViews, you will no longer
need iv/src (the source tree).  You can say "make clean" to save disk
space by removing all object code files in the source tree.  You can
even copy iv/installed to another computer and use InterViews on that
computer without iv/src having to be present.  If you have a symbolic
link that points at iv/installed, your PATH can be the same on any
computer which contains iv/installed as long as they all have the same
name for the symbolic link (like /interviews).


* How to use InterViews


If /interviews is a symbolic link to iv/installed, you can start using
InterViews by putting the following lines in your .cshrc:

	setenv CPU SUN4		# or MIPSEL or whatever
	setenv MANPATH $MANPATH:/interviews/man
	setenv PATH $PATH:/interviews/bin/$CPU

Once you have /interviews/bin/$CPU in your PATH, you can use the
InterViews script "ivmkmf" to generate Makefiles for your own
InterViews applications.  You have to write an Imakefile first, but
you can do that by copying one of the Imakefiles in iv/src/bin and
replacing the filenames with the names of your application's source
files.  Saying "ivmkmf" will generate a Makefile that contains the
appropriate -I and -L flags for using the InterViews includes and
libraries when building your application.


* How to write an Imakefile


The easiest way to write an Imakefile is to start with a copy of a
similar Imakefile and modify it.  If you use only 3.1 classes, you can
copy alert's Imakefile.  If you use both 3.1 and 2.6 classes, you can
copy doc's Imakefile.  If you use only 2.6 classes, you can copy dclock's
Imakefile.  If you use the Unidraw library, you can copy idraw's
Imakefile.  Reading the config files to understand how the rules are
defined will also help if you need to do anything complicated.

Some make variables are reserved for your application's use.  You can
compile your application with special compiler flags, defines,
includes, linker flags, or libraries by setting APP_CCFLAGS,
APP_CCDEFINES, APP_CCINCLUDES, APP_CCLDFLAGS, or APP_CCLDLIBS in your
Imakefile.  You can make your application depend on libraries by
setting APP_CCDEPLIBS.

You can cause your application to be linked with InterViews libraries
bu using one and only one of the macros Use_libInterViews(),
Use_libUnidraw(), and Use_libgraphic().  Both libUnidraw and
libgraphic depend on libInterViews so saying Use_libUnidraw() or
Use_libgraphic() makes saying Use_libInterViews() unnecessary.  You
cannot say both Use_libUnidraw() and Use_libgraphic() because
libUnidraw and libgraphic conflict with each other.  All of these
macros also add -lXext -lX11 -lm to CCLDLIBS for you.

If your application uses classes from the "old" InterViews 2.6,
Unidraw, or graphic libraries, you should use the macro Use_2_6() as
well as one of the macros Use_libInterViews(), Use_libUnidraw(), or
Use_libgraphic().  Many 3.1 classes have the same names as 2.6 classes
so the shorter names are reserved for the 3.1 classes and the 2.6
classes' names are prefixed with "iv2_6_".  The macro Use_2_6() allows
you to use the classes' shorter 2.6 names instead of their real names
and their shorter include paths (<InterViews/*.h>) instead of their
real include paths (<IV-2_6/InterViews/*.h>.  If you want to use
both 3.1 and 2.6 classes in the same application, you will
need to omit Use_2_6() and use the 2.6 classes' real names and
include paths.

You can use the macro ComplexProgramTarget(dest) to build a program.
The parameter specifies the name you want the program to have after
it's installed.  The make variable $(AOUT), which defaults to "a.out,"
specifies the name the program will have when it's built.  The make
variable $(OBJS), which defaults to "*.o," specifies the list of
object code files which must be linked together.  You don't have to
define either $(AOUT) or $(OBJS) in the Imakefile because the
generated Makefile will assign default values to them.  You don't have
to define the list of object files in $(OBJS) because the Imakefile
will generate dependencies between the program and its object code
files of the form

a.out:
	$(CC) $(OBJS)

a.out: a.o
a.out: b.o
a.out: c.o

which is equivalent to the traditional form

a.out: a.o  b.o  c.o
	$(CC) $(OBJS)

You will define these dependencies automatically when you use the
macros MakeObjectFromSrc(file) and MakeObjectFromSrcFlags(file, flags)
for each source file in the program.  Each source file must have its
own rule (hence the macro) because the implicit make rule cannot
compile source files which are not in the current directory.  However,
you won't have to specify the name of the source file again in any
other place in the Imakefile.

You should surround the Imakefile with the following lines,

	#ifdef InObjectCodeDir
	<contents>
	#else
	MakeInObjectCodeDir()
	#endif

so that saying "make Makefiles" will create a subdirectory in which to
put the object code files.  You do not have to use these lines, but if
you do not you will not be able to build optimized, debuggable, and
non-shared object code files alongside of each other in separate
subdirectories.  You also will not be able to build object code files
for different machine architectures alongside of each other in
separate subdirectories.  On the SPARCstation, such object code
directories will have the names SUN4, SUN4.debug, and SUN4.noshared
(the latter two will be created only if you use a special make
command, see below).

After you finish writing your Imakefile, saying "ivmkmf" will generate
the corresponding Makefile.  Then you can say "make Makefiles; make
depend; make all" to build your program.  If you make a new change to
the Imakefile, all you have to do is to say "make Makefile"---you
don't have to use "ivmkmf" again.

Saying "make Makefiles.debug" and/or "make Makefiles.noshared" will
create the special object code subdirectories and saying "make
depend.debug", "make depend.noshared", "make all.debug", or "make
all.noshared" will build in them just like the normal subdirectories.
Note that the Makefile will provide the "make *.noshared" targets only
if you're on a computer which has shared libraries (currently we
support only SunOS shared libraries).

If you write a Makefile by hand instead of writing an Imakefile,
you'll have to specify everything that make needs to know.  For
example, you'll have to specify the -I and -L flags needed to use the
InterViews includes and libraries when compiling your application.
You'll also have to specify any extra flags that your system may need
even though you may have to change them when building on a different
system (when you use an Imakefile, the platform-specific X11 .cf file
specifies these flags for you so they don't have to be in the
Imakefile).