freebsd-ports/x11-toolkits/iv/pkg-descr

* How to use InterViews

After installation, you can start using InterViews by putting the following
lines in your .cshrc:

 setenv CPU FREEBSD
 setenv MANPATH $MANPATH:/usr/local/interviews/man
 setenv PATH $PATH:/usr/local/interviews/bin/$CPU

Once you have /usr/local/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).

* How to stay tuned

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.