freebsd-ports/x11-toolkits/xview-clients/pkg-descr

###########################################################################
# README file for the XView Toolkit, Version 3.2, source release
# @(#)README	1.7 1/7/92 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/whats_new.ps files.  Please refer to these for issues
related to using the XView libraries and clients and changes for the 3.2
release.  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 5. 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). This release of XView
was only tested (executing the builds, and running the binaries)
on X11 R5.


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

lib/libxview		The XView toolkit
lib/libolgx		The OLGX toolkit  (used by XView and olwm)
clients/clock		An XView clock application.
clients/cmdtool		An XView terminal emulator.
clients/olwm		The OPENLOOK window manager.
clients/olwmslave	'helper' program for olwm.
contrib/examples	A bunch of XView examples.
fonts/bdf		The OPENLOOK fonts required for Pre-R4 based servers.
doc			Documentation about XView.
misc/message_files	Message file templates for localization.
misc/xrdb_files		X resource files for olwm/XView 3.2

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


Building the Release
--------------------
This release of XView was tested on these systems:
    SparcStation 10, SunOS 5.2
    SparcStation 2, SunOS 5.2
    SparcStation 1, SunOS 4.1.2

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. If you set XvI18nLevel to 4 in config/XView.cf, Asian locale
	   support will be built in XView, and olwm. In this case, for 
	   olwm to work properly, the Xlib library (libX11) has to be 
	   built with internationalization support. If this cannot be 
	   done, config/XView.tmpl will have to be edited for the clients/olwm 
	   build as follows. Change the line:

    XVCLIENTI18NDEFINES = -DOW_I18N_L4 -DOW_I18N_L3 -DOW_I18N -DFULL_R5

	   to

    XVCLIENTI18NDEFINES = -DOW_I18N_L3 -DOW_I18N -DFULL_R5

	3. 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. XView.cf, by default, is designed for building XView 3.2
on Solaris 2.2.

################
NOTE (IMPORTANT)
################
The default configuration will build XView with Asian locale support
(turned on by -DOW_I18N). This requires the presence of Sun private 
header files (i.e. XSunExt.h) available only with Solaris 2.2. It is
included by the build via "-I$(OPENWINHOME)/include".
Therefore, the default configuration requires Solaris 2.2 to be 
installed. If it is not installed, Asian locale support has to be turned 
off by setting XvI18nLevel (in config/XView.cf) to 3. This has to be done
for builds done on SunOS 4.x as well.

In the source release of XView 3.0, we used 'xstr' in shared library
builds. 'xstr' was used to extract string literals from the source which 
was then put into an array which was indexed into instead of using the 
string literal directly. We have removed this functionality for this 
release. Most compilers already have options (-strconst, -xstrconst) 
to insert string literals into the text segment instead of the data 
segment. Building without xstr is also much faster.

But, if your builds fail with:

	"GLOBAL_OFFSET_TABLE overflown"

then, you should revert back to the old way of doing things, with 'xstr'.
This can be done as follows (in the config directory):

	a. mv XView.rules XView.rules.bak
	b. cp XView.rules.xstr XView.rules


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 XView 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 "imake -DUseInstalled -I<X11>/lib/X11/config -I./config" 
	    Type 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
            without any problems on sun4 with SunOS 4.x and sun4 with 
	    SunOS 5.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.  

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


Porting Notes
-------------
This release of XView has been tested extensively on two Sun
platforms, a  SunOS 4.1.2 system and a SunOS 5.2 system. X11R5 was 
build for the SunOS 5.2 system using the base MIT X11R5 source and
the R5.SunOS5.patch in the contrib directory on export.lcs.mit.edu.
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/usenixws. 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 X11R5.


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.