About the XGL Directory Structure

The XGL runtime library, font files, and error message files are installed with the Solaris product, and the XGL include files and documentation are installed with the Solaris Software Developer Kit (SDK). The Solaris product includes the XGL packages listed in Table 2-1.

Table 2-1

Package Name	Package Contents
SUNWxglrt	XGL runtime library and the Roman_M stroke font
SUNWxgler	Localized error message files for SUNWxglrt
SUNWxgldg	Loadable pipeline libraries for generic drivers with specific error message files when applicable. The generic drivers are cg6 (GX, GXplus, TurboGX, and TurboGXplus), cfb (non-accelerated color frame buffers such as cg3 and cg8), mem (memory), xpex (combined xlib and pexlib), swp (software pipeline), and cgm (CGM Stream device) . XGL loadable libraries for other devices are included in the packages distributed with each device.
SUNWxglft	XGL stroke fonts

The SDK provides the XGL packages listed in Table 2-2.

Table 2-2

Package Name	Package Contents
SUNWxglh	Additions to the XGL runtime library that an XGL developer needs, including include files, example programs, and man pages.
SUNWAxg	AnswerBook versions of XGL documentation.

By default, the XGL software packages are installed in /opt/SUNWits/Graphics-sw/xgl, and the AnswerBook software in /opt/SUNWAxg.

The following XGL directories contain files that are links to other files. These links are required by the System V Release 4 UNIX^(R)runtime loader, since the loader does not recognize files that end in a release number.

• SUNWxglrt Files in lib/

libxgl.so ->libxgl.so.3

• SUNWxgldg Files in lib/pipelines

xglSUNWcg6.so ->xglSUNWcg6.so.4
xglSUNWcfb.so ->xglSUNWcfb.so.4
xglSUNWmem.so ->xglSUNWmem.so.4
xglSUNWswp.so ->xglSUNWswp.so.4
xglSUNWxpex.so ->xglSUNWxpex.so.4
xglSUNWcgm.so ->xglSUNWcgm.so.4

The XGL directory structure is shown in Figure 2-1. The SDK packages are shown as shaded boxes.

Figure 2-1

Font Files

The files in the lib/xglfonts/stroke directory contain the current XGL font files as well as links from the XGL 2.0 font file names, which are provided to accommodate programs written for the XGL 2.0 library. Links are from the XGL 2.0 font file names with the suffix .phont to the current XGL font files with the suffix .font.

XGL AnswerBook Directory Structure

Figure 2-2 shows the directory structure of the XGL AnswerBook package. The _data directory contains the files the AnswerBook software uses to display the XGL Programmer's Guide and XGL Reference Manual.

Figure 2-2

Setting XGL Environment Variables

You need to set the XGLHOME and LD_LIBRARY_PATH environment variables to use the XGL product. These instructions assume that the XGL library is installed in the default directory.

1. Set the XGLHOME environment variable to the directory containing the XGL library.

host% setenv XGLHOME /opt/SUNWits/Graphics-sw/xgl

2. Set LD_LIBRARY_PATH to include $XGLHOME/lib.

host% setenv LD_LIBRARY_PATH $XGLHOME/lib:$LD_LIBRARY_PATH

Verifying the Installation of XGL

You can use the install_check program in the XGL demo directory to verify that the XGL product has been installed correctly. Follow these instructions:

1. Change directory to the top of the XGL directory tree.

   If the XGL library was installed in the default directory, the command would look like this:

host% cd /opt/SUNWits/Graphics-sw/xgl-3.0

install_check expects to find the XGL library in the default installation directory and the OpenWindows library in /usr/openwin. If install_check cannot locate the XGL library, it uses the path listed in $LD_LIBRARY_PATH.

2. Change directory to the demo directory and run install_check.

host% cd demo host% install_check

The install_check program displays a window labeled "XGL Installation Checker". The window contains XGL stroke text describing the device that XGL is using on your system. If the program runs successfully, your XGL library has been correctly installed.

Installation and System Administrator Notes

This section presents information on installation and system administrator issues.

Debuggable XGL Runtime Library

Due to space constraints, the XGL runtime environment installed with the operating system has been stripped of the symbol table information. This does not interfere with the normal running of an application built with the XGL library, but it may make it difficult for you to debug your graphics application, since you will not be able to produce stack traces from the .so files. Therefore,

patch packages that contain XGL runtimes with all the symbol table information have been provided on the CD. See your system administrator for assistance if you need to have the patches installed.

XGL Library and Reference Pipelines

The current XGL runtime library, libxgl.so.3, which is shipped as part of the SUNWxglrt package must be used with the current versions of the XGL reference pipelines in the SUNWxgldg package. The previous version of the reference pipelines cannot be mixed with the current version of libxgl.so. If users try to use a previous version of the reference pipelines with libxgl.so, XGL will fail from within the runtime loader with unresolved external reference errors.

XGL and the PEXLib Library

If a window raster is created on a remote server that supports PEX, but the PEXlib library, libPEX5.so, cannot be found on the local machine, XGL issues an error message and uses Xlib to communicate with the remote window raster. To eliminate the error, either install the PEXlib library or disable PEX on the remote server.

Solaris Security Feature and DGA

There is a security feature in Solaris that governs frame buffer access by processes that were started by users other than the first user of the window system. As a result, non-owners of the window system will not have access to DGA. For example, if a user starts the window system, and then another user sits at the workstation, changes to his own environment using su, and starts an XGL application, the application will not run via DGA even though the second user is running the application locally. To give all local users access to DGA, change directory to the file /etc/logindevperm and change the permissions to 0666 in the following lines and then reboot.

/dev/console 0666 /dev/mouse;/dev/kbd /dev/console 0666 /dev/sound/* # audio devices /dev/console 0666 /dev/fbs/* # frame buffers

Using the Solaris XGL AnswerBook

To start the XGL AnswerBook under the Solaris release, use the following start-up script provided with the Solaris software:

% /usr/openwin/bin/answerbook

This script allows access to all AnswerBooks installed on your system. Once the script is invoked, all available AnswerBooks are loaded onto a new AnswerBook Navigator.

Accessing the XGL Man Pages

To access the XGL reference manual pages, the MANPATH environment variable must be modified to include the directory where the man pages are located. catman(8) formats all the reference manual pages and stores the formatted version of each page. This optional operation causes the man command to work faster. It also builds the whatis database so that the keyword search option of man (-k) will include the XGL reference manual pages.

1. Set the XGLHOME and MANPATH environment variables. Assuming you've installed XGL in the default directory, set the variables as follows:

host% setenv XGLHOME /opt/SUNWits/Graphics-sw/xgl host% setenv MANPATH /usr/man:$XGLHOME/man

2. Format the man pages.

   This will enable you to use the keyword search option (-k).

host% su root Password: enter your root password root% /usr/etc/catman -M $XGLHOME/man 3