###########################################################################
# README file for the XView Toolkit, Version 3.0, source release
# @(#)README	1.6 10/5/91 SMI
#
# Please read this document before building the XView release.


What Is XView
-------------
XView (X Window-System-based Visual/Integrated Environment for Workstations)
is a user-interface toolkit to support interactive, graphics-based
applications running under the X Window System.  XView provides a set of
pre-built, user-interface objects such as canvases, scrollbars, menus, and
control panels.  The appearance and functionality of these objects follow
the OPEN LOOK Graphical User Interface (GUI) specification.  XView features
an object-oriented style Application Programmer's Interface (API) that is
straightforward and easy to learn.


More Information
----------------
More information on the XView release is supplied in the 
<XVIEW>/doc/relnotes.txt, <XVIEW>/doc/rtf.txt and 
<XVIEW>/doc/whats_new.ps files.  Please refer to these for issues
related to using the XView libraries and clients and changes for the 3.0
release.  Known bugs and bugs fixed since 2.0 are listed in the
<XVIEW>/doc/bugs directory.  Information on documentation, bug reporting and
help can be found in the doc directory: xview-info.  Information on
resources/defaults is included in the XView man page contained in
this directory.


XView Requirements
------------------
XView requires the use of an ICCCM-compliant window
manager.  One such window manager is olwm, which supports the OPEN
LOOK (TM) user interface.  Further, XView requires full ICCCM
support in Xlib. This is the standard in the X Window System
Version 11, Release 4. In order to run under Release 3, you must
define the PRE_R4_ICCCM compile-time flag (see config/XView.cf) 
and the set resource, xview.icccmcompliant, to False in the 
.Xdefaults file (see the xview man page). 


Contents
--------
The XView release contains the following:

lib/libxview		The XView toolkit
lib/libolgx		The OLGX toolkit  (used by XView and olwm)
lib/libxvps		A postscript extension/subclass to XView. 
clients/clock		An XView clock application.
clients/cmdtool		An XView terminal emulator.
clients/olwm		The OPENLOOK window manager.
clients/props		A workspace property program.
clients/textedit	An XView text editor.
contrib/examples	A bunch of XView examples.
fonts/bdf		The OPENLOOK fonts required for Pre-R4 based servers.
doc			Documentation about XView.

The unpacked source is ~18meg
You'll need an additional 17meg to do a complete build. (assuming shared libs)
To install everything, you'll need about 7.5meg.


Building the Release
--------------------
Like X11, XView uses imake to configure the Makefiles for a particular
system.  The Makefiles delivered with this release are probably not
configured correctly for your system.  New Makefiles will need
to be generated from the Imakefiles.  In order to do this,
the following items are required:

	1. Installed X11 R5

		a. X11 header files.
		b. X11 libraries.
		c. X11 config directory.

	2. Compiled versions of imake and makedepend must be found
	   in your $PATH.  If you are building the fonts you'll
	   need the X11 font compilers in your path too.  The fonts
	   are only needed if you are building for a Pre-R4 server.

Assuming R5 is installed in /foobar/R5, the X11 config directory is
in /foobar/R5/lib/X11, and compiled versions of imake and makedepend
should be found in /foobar/R5/bin.

The XView release provides an additional set of rules and configuration
parameters that are necessary to build the release.  These can be
found in ./config.   Most notably is ./config/XView.cf which contains
XView specific build options.  This file should be read before a build
is attempted. 

Here is what you need to do to build:

	1.  Set the environment variable IMAKEINCLUDE to point to both the
	    R5 config directory and the XVuew config directory.
	    Examples, first one for csh, second for sh: 

		% setenv IMAKEINCLUDE -I`pwd`/config -I/foobar/R5/lib/X11/config
            or
		$ IMAKEINCLUDE="-I`pwd`/config -I/foobar/R5/lib/X11/config"
		$ export IMAKEINCLUDE

        2.  Set the OSMajorVersion and OSMinorVersion variables in the
                appropriate <X11>/config/*.cf files.  

        3.  Double-check the parameters in <X11>/config/site.def.

	4.  Double-check the build options in ./config/XView.cf.
	    There are comments in this file to explain what each option
	    is for. Among other things, this is where you can define where you 
	    want XView to be installed.

	5.  Type "make Makefile; make World >& make.world &" 
		(do not name the log file make.log or it will get deleted).
	    This will build libxview and libolgx.

        6.  Check the log file for any errors.  The release should build
                cleanly on sun3, sun4, sun386i with SunOS 4.x.

	7.  As root, type "make install".  See tail end of log file for 
		special directions for shared libraries, if used.

	8.  Type "make Clients >& make.clients &"
	    This will cause the programs in ./clients to be built.

	9.  Type "make Contrib >& make.contrib &"
	    This will cause the examples in ./contrib to be built.

	10. Type "make 'SUBDIRS=clients contrib' install"

	11. Type "make 'SUBDIRS=clients contrib' install.man"

	12. Type "make 'SUBDIRS=clients contrib' install.srcs"

	13. Documents, release notes, known bugs are in the doc directory.
	    Can install these with "make -k 'SUBDIRS=doc' install".

	14. When done, can get rid of all compiled files and links used
	    during the build with: "make Clean" 

Building a lint library is not yet supported.  We have a prototype lint
library which needs some more testing and work.  If you are interested in
working on this, please send a note to xviewbugs.


Source Notes
------------
This version of the XView source corresponds to that provided with
OpenWindows Version 3 from SunSoft Inc.  Libraries generated with this
source should be interchangeable with those from the OpenWindows Version 3
release.


Porting Notes
-------------
This release of XView has been tested extensively on a Sun
platform (SunOS 4.1).  While efforts have been made to keep the toolkit
portable to other platforms, you may encounter problems.  Please inform
us of the porting problems you find.  Send email to xviewbugs@Eng.Sun.COM 
and we will attempt to evaluate the problem and possibly include
a fix in a future patch or release.


Build Environment Notes
-----------------------
The style of the build environment has been outlined by the X.V11 Release 5
build environment from MIT.  "Outlined" is used instead of "defined" since
there is no standard procedure for X software builds.  The precedent is set
by the X Consortium for certain procedures and conventions; however, since
these conventions are neither reviewed nor documented, they cannot always
be followed.  As much as possible, the conventions used in the X11R5 build
have been followed in the XView build.

If you've not used imake before, there is a document which explains how
it works in doc/config.  The easiest way to think of it is creating a
Makefile description language with CPP macros.  The order in which files
are included will define which CPP rules and variables are active.

The configuration files specific to XView all begin with "XView."
The "XView.cf" file is one meant to easily choose certain build or
configuration options.  The "XView.tmpl" file defines common configurations
for XView and is included by each Imakefile.  All relevant variables 
defined in the  XView.tmpl file may be changed in the site.def file by
pre-defining the appropriate CPP variable.  Both files are heavily
commented to explain what each option does.  The other files, "XView.lib",
"XView.obj", and "XView.prog" are just a means of sharing common Imakefile
commands among many Imakefiles.  The "XView.rules" file supplements the
"Imake.rules" file as supplied by X11R4.


Feedback
--------
While the XView team makes every effort to watch the ``net'' for questions
and problems with XView some messages may slip by.  The xviewbugs@Eng.Sun.COM
alias has been created to provide a means for XView source product customers
to send input to the XView engineers.  If you find problems or have
comments on XView, please forwarded them to this alias.  We appreciate
any and all input.
