########################################################################### # 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 /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 /config/*.cf files. 3. Double-check the parameters in /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/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.