IRIS Explorer, Release 5.2 IEL6A52NA 64-bit Linux (AMD Opteron), SuSE 8.0 Installer's Note Contents 1. General Information 1.1. Introduction 1.2. Hardware Requirements 1.3. Software Requirements 1.4. Distribution Medium 1.5. Distribution Contents 2. Installation 2.1. Installation Method 2.2. Environment Variables 2.3. License Management 2.3.1. Installing an Uncounted License 2.3.2. Installing a Counted License and FLEXlm on Unix 2.3.3. Installing a Counted License and FLEXlm on Windows NT/2000 2.4. Quick Test 3. Further Information 3.1. Online Documentation 3.2. Configuration Files 3.3. Network OpenGL Issues 3.4. Other Installation Information 3.5. Known Problems with this Release 4. Support from NAG 5. User Feedback 1. General Information 1.1. Introduction This document is essential reading for the NAG Site Contact responsible for installation and maintenance of the IRIS Explorer implementation specified in the title. The installer will be provided with a printed copy of this document (Installer's Note). The use of all supplied software must be in accordance with the terms and conditions of the Software Licence signed by NAG and each site. Any request to use NAG software on a computer other than the one licensed must be referred to NAG (see Section 4). 1.2. Hardware Requirements To run this software you need a PC with an AMD Opteron chip. To obtain the best graphics performance it is recommended that a graphics card be installed with OpenGL acceleration. Some information on OpenGL cards and their performance may be obtained from http://www.opengl.org/. See Section 3.3 below for more information on using IRIS Explorer with graphics acceleration. The recommended minimum configuration for the working system is: - 32Mb real memory - 205Mb disk space 1.3. Software Requirements This system has been developed under the SuSE 8.0 distribution of Linux. Other distributions of Linux have not been tested, but might also work. You can check which software packages are installed on your machine using the rpm(8) command; below, we refer to package names (for example gcc-33-3.3-6) which are used by this command. The following system software is required: - SuSE Linux 8.0 or compatible - more specifically: - kernel-source-2.4.19.SuSE-174 The Linux kernel (the core of the Linux operating system). - glibc-2.2.5-164 The GNU libc libraries. Modules which use text (e.g. DrawText) also require: - freetype-2.0.9-81 A free and portable TrueType font rendering engine. To build your own modules you will need a compiler, i.e. - gcc-33-3.3-6 The GNU C compiler version 3.3 and support files. - gcc-33-c++-3.3-6 GNU C++ compiler. - gcc-33-g77-3.3-6 GNU Fortran compiler. In addition, Motif 2.2.2 is needed in order to compile modules: - openmotif-devel-2.2.2-158 Open Motif development libraries and header files. 3D rendering modules have been dynamically linked against Mesa, the OpenGL(tm)-like 3D graphics library from: - mesa-4.0.3-86 - mesaglu-4.0.3-86 In addition to these mesa packages, you will require an implementation of the GL library from one of the following packages (these names omit the version numbers - e.g., the full name of the first package will be something like mesasoft-4.0.3-86): - mesasoft : OpenGL Software Emulation (works on all graphic boards) - mesa3dfx : Mesa/Glide - NVIDIA_GLX : XFree86 4.x/NVIDIA_GLX - xf86_glx : XFree86 4.x/DRI More help on selecting the GL implementation can be found in the documentation for the mesa package. See Section 3.3 below for more on 3D rendering. An HTML browser such as Mozilla is required to read the on-line documentation (see Section 3.1, below). Other required software libraries are distributed with the installation. No special action to install these libraries is therefore required but, for convenience, we acknowledge their provenance here. - Open Inventor, the object-oriented 3D toolkit. This version of IRIS Explorer uses a modified version of the Open Source distribution of Open Inventor, available from http://oss.sgi.com/projects/inventor/ The modified source is distributed on the IRIS Explorer CD-ROM (see Section 1.4) as osinvent.tgz. 1.4. Distribution Medium The implementation is distributed as a set of tar files on a CD-ROM, which also contains an installation script, unless otherwise indicated on the medium and accompanying despatch note. 1.5. Distribution Contents The IRIS Explorer distribution includes the following components. explorer.tar IRIS Explorer base system, modules, example maps, sample data, module development environment and module source. This release includes 376 modules, of which 91 have been contributed by users and are provided as-is without support from NAG. This release also contains 166 maps demonstrating the use of many of the supplied modules. Finally, the source to 416 modules, which you can use as the starting point for your own module development, is also included. unixdoc.tar An introductory tutorial, plus a four volume manual set (IRIS Explorer User's Guide, Reference Pages, Module Writer's Guide, Collaborative User's Guide) in HTML format. The documentation also includes external links to NAG's IRIS Explorer Center website, which contains newsletters, user stories and example images. flexlm.tar IRIS Explorer license management daemons and associated files. osinvent.tgz Modified source to Open Source Open Inventor used in the build of IRIS Explorer. notes.tar Installer's Note (this file) and Release Note, giving a short description of IRIS Explorer 5.2 and its new features. 2. Installation 2.1. Installation Method The distribution on the CD consists of the following files: l6ana_in.txt - this note relnotes.txt - release note install.sh - installation script explorer.tar unixdoc.tar flexlm.tar osinvent.tgz notes.tar To install the software you should execute the install.sh script on the CD. For example, if the CD is mounted at /cdrom you should do the following: cd /cdrom ./install.sh This script will install IRIS Explorer into a single directory which you will be prompted for. (It is recommended that you choose a directory which does not include spaces in the path.) Note that the Open Inventor source contained in osinvent.tgz is not installed by this script (see Section 1.5, above). While the other files on the CD are tar files, this is a compressed (gzipped) tar file; thus, for example, its contents may be read using tar -tzvf osinvent.tgz Finally, the installation script will run an auxiliary script: $EXPLORERHOME/license/install_default i86_r6 which asks whether license management binaries are to be installed. If so, then the platform-specific FLEXlm utilities will be copied from $EXPLORERHOME/license/bin/i86_r6 to /usr/local/flexlm/bin. The copy will fail if, e.g., the destination directory cannot be created; the installation can be attempted again by running the auxiliary script using the above command. See Section 2.3 below for more information on these files and their use. 2.2. Environment Variables A few environment variables - including EXPLORERHOME, the location of the IRIS Explorer installation - need to be set for IRIS Explorer users. These are all set in the file sample.cshrc (for users of the C shell) and sample.bashrc (for bash shell users), which can be found in the EXPLORERHOME directory. Before running IRIS Explorer, a user must 'source' the appropriate file, (preferably) by copying the appropriate command to the end of their .cshrc or .bashrc file. Thus, for example, if IRIS Explorer has been installed in /usr/local/explorer, the following command must be added to the end of each user's .cshrc file: % source /usr/local/explorer/sample.cshrc if they are users of the C shell. Alternatively, users of the bash shell can append source /usr/local/explorer/sample.bashrc to the end of their .bashrc file. When building modules, there is a set of variables which may be used to control the operation: EXPLORERUSERHOME, CXINST_STRIPPED and CXINST_SYMBOLIC. See $EXPLORERHOME/sample.{cshrc,bashrc} for a discussion of these. Sourcing this file also causes the maximum number of open file descriptors per process to be set to 512. This is necessary because the default value for this resource (around 60) is too low for some of the IRIS Explorer maps (specifically, those that contain a large number of modules) to run properly. If not enough file descriptors are available, modules will fail to start, returning error messages like: "GenLat": failure in executing the module Operating system returned: Too many open files Other errors (including scrambled colors in geometry) are associated with insufficient file descriptors. 2.3. License Management The use of some NAG software is controlled by the FLEXlm network license management system. (FLEXlm is a registered trademark of Macrovision Corporation.) NAG provides binary utilities and daemons for FLEXlm in the license/ subdirectory of each software distribution. This release of IRIS Explorer uses version 9.2 of FLEXlm. The remainder of this section describes how a FLEXlm license key should be installed to enable the use of IRIS Explorer. Further details about FLEXlm and how it may be configured to suit your local circumstances are included in the FLEXlm End User Manual supplied in the directory $EXPLORERHOME/license/htmlman. To request a license key, locate and run the program key_rqst in the appropriate platform specific subdirectory under the license/bin/ subdirectory. key_rqst takes one input parameter: the 9-digit product code (in this case IEL6A52NA). Complete the form that it displays and e-mail (or FAX) it to NAG. The form asks if you wish to use a license server. License servers are described in the remainder of this section. NAG usually provides a license key of one of two types; uncounted and counted licenses. Uncounted licenses which expire after a short period are issued to potential users of IRIS Explorer who wish to try out the product before buying it; these are sometimes called DEMONSTRATION or EVALUATION licenses. Uncounted licenses are also issued if you have bought IRIS Explorer for use on a specific machine. An uncounted license key consists of one FEATURE or INCREMENT line for each product licensed, for example: FEATURE IRIS_Explorer NAG 5.200 31-may-2006 0 \ CBDA2041DC1BC45D2B68 "ANY" 80896b27 This enables an unlimited number of instances of version 5.2 of the application IRIS_Explorer until the date specified on the system with hostid 80896b27 only. Note that the line is continued by escaping the newline character with '\'. Counted licenses are suitable for networks of machines. Such networks may consist of machines which are all the same type, or some machines may be different. A counted license allows you to run a number of IRIS Explorer sessions concurrently on any computer on the network. When IRIS Explorer starts it communicates with the FLEXlm daemon (lmgrd) running on some computer on the network (the license server). lmgrd requests an IRIS Explorer license from the NAG daemon. Depending on the license details and the number of IRIS Explorer sessions that are already running on the network, the request is granted or denied. Due to the complexity of the installation you are advised to have counted licenses installed by your system administrator. Counted licenses are sometimes referred to as NETWORK licenses. A counted license key specifies the license server and the location of the NAG daemon in addition to one FEATURE or INCREMENT line for each product licensed, for example: SERVER derwent 55001341 7312 DAEMON NAG /usr/local/flexlm/naglm/bin/NAG FEATURE IRIS_Explorer NAG 5.200 31-oct-2006 7 \ CBDA2041DC1BC45D2B68 "L6A," This nominates the license server with hostname derwent, hostid 55001341 using communications 'port number' 7312. The full path to the NAG daemon is specified on the second line. Up to 7 concurrent IRIS Explorer sessions are allowed. Note that the FEATURE line is continued by escaping the newline character with '\'. The server hostname, port number and path to the NAG daemon are the only items that may be changed. The port number should be chosen so that it does not conflict with other applications (not mentioned in this license file) managed by FLEXlm. For uncounted licenses it is sufficient to install the license; no other licensing software is required and these licenses are therefore easy to install. Counted licenses also require the installation of the license daemon, the NAG daemon and the FLEXlm utility programs. Only one license daemon and NAG daemon are required per network. They must both be installed on the license server. Any machine on the network may be the license server. You need to consider which machine is most suitable. It should be a machine that is always up and running when anyone on the network is likely to be running IRIS Explorer. It also needs to have an architecture and operating system that is supported by FLEXlm. The following are supported: alpha_u3 - Compaq (DEC) Alpha Tru64 (OSF/1, Digital unix) hp700_u10 - HP-UX 10.x to 11.20 32-bit hp700_u11 - HP-UX 11.20 or higher 32-bit i86_g2 - Intel x86 Linux with GLibc 2.3, Redhat 5 i86_n3 - Intel x86 Microsoft Windows i86_r6 - Intel x86 Linux Redhat 6, etc. i86_r9 - Intel x86 Linux Redhat 9 it64_lr2 - Itanium IA64 Redhat and Turbo Linux ppc_mac10 - Macintosh PowerPC OS X 10.1 or higher rs6000_u3 - IBM PowerPC and RS6000 32-bit AIX sgi32_u6 - Silicon Graphics IRIX 32-bit sgi64_u6 - Silicon Graphics IRIX 64-bit sgio32_u6 - Silicon Graphics IRIX old 32-bit (mips2) sun4_u5 - Sun SPARC SunOS 5.5 (Solaris 2.5) or later 32-bit (1024 files) sun4_u7 - Sun SPARC SunOS 5.7 (Solaris 2.7) or later 32-bit (65535 files) sun64_u5 - Sun SPARC SunOS 5.7 (Solaris 2.7) or later 64-bit 2.3.1. Installing an Uncounted License Once you have obtained the license key, store the text of it in a file, say /opt/nag/license.lic If the license file contains one or more SERVER lines, the FLEXlm daemons must be started before you can use license. Refer to the FLEXlm End Users Guide supplied in the license/htmlman/flexuser subdirectory. For a serverless license, the location of the license file must be made known to the NAG application by setting the environment variable LM_LICENSE_FILE to the full pathname of the file before the application is invoked. For example, in the C-shell, type: setenv LM_LICENSE_FILE /opt/nag/license.lic or in the Bourne shell, type: LM_LICENSE_FILE=/opt/nag/license.lic export LM_LICENSE_FILE No other actions are required to install an uncounted license, and you may skip to Section 2.4. 2.3.2. Installing a Counted License and FLEXlm on Unix If your license server is already running FLEXlm v9.2 or later for a NAG product, add the FEATURE line for IRIS Explorer to your existing license file and use the lmreread utility. The only other action required in this case is to ensure that the environment variable LM_LICENSE_FILE is set as described below. Apart from this, the remainder of this section may be skipped. Store the text of the license key in a file on the license server, say /usr/local/flexlm/naglm/license.dat, ensuring that the word after SERVER is the network name of the license server and the path on the DAEMON line is /usr/local/flexlm/naglm/bin/NAG. On the system(s) where IRIS Explorer is to be run, set the environment variable LM_LICENSE_FILE to "port@host", where port is the port number on the SERVER line and host is the hostname of the license server. For example, in the C-shell, type: setenv LM_LICENSE_FILE 7312@derwent or in the Bourne shell, type: LM_LICENSE_FILE=7312@derwent export LM_LICENSE_FILE If IRIS Explorer is to be used on the license server only, LM_LICENSE_FILE may be set to the full pathname to the license file. Copy the FLEXlm daemons and utilities from the appropriate sub-directory of $EXPLORERHOME/license/bin into /usr/local/flexlm/naglm/bin on the license server (this should be on a local filesystem, not NFS). Set the environment variable LM_LICENSE_FILE to the full path of the license file and enter the command ./lmgrd to start the license manager. If any problems are reported, rectify them using the information in the FLEXlm End User Manual and FAQ. Stop the license manager with the command ./lmutil lmdown. lmgrd should be started on the license server whenever the run level changes into multi-user mode. You need to be 'root' to arrange this, but lmgrd does not have to be run as root so you should set up a non-privileged username, for example flexrun. An appropriate entry in /etc/passwd would be: flexrun:*:22:22:Runs FLEXlm lmgrd only:/nonexistent:/bin/sh This example places flexrun in group 22, which should be lmadmin. The entry in /etc/group is: lmadmin:*:22:root,flexrun In the scripts executed by init, lmgrd should be started with a command like: su flexrun -c "umask 022; /usr/local/flexlm/naglm/bin/lmgrd \ -c /usr/local/flexlm/naglm/license.dat -2 -p \ -l /usr/local/flexlm/naglm/lmgrd.log" Refer to the FLEXlm End User Manual for a full description of the possible arguments to lmgrd. 2.3.3. Installing a Counted License and FLEXlm on Windows NT/2000 In this subsection, we assume that drive C: is the Windows system drive. If your WINNT directory is on another drive, use the proper drive letter in all paths. If your license server is already running FLEXlm 9.2 or later for a NAG product, add the FEATURE line for IRIS Explorer to your existing license file and use the Reread option of the lmtools utility. The only other action required in this case is to ensure that the environment variable LM_LICENSE_FILE is set as described below. Apart from this, the remainder of this section may be skipped. Store the text of the license key in a file on the license server, say C:\FLEXLM\NAGLM\LICENSE.DAT, ensuring that the word after SERVER is the network name of the license server and the path on the DAEMON line is C:\FLEXLM\NAGLM\BIN\NAG.EXE. The file must be saved as a simple text file. On the system(s) where IRIS Explorer is to be run, set the environment variable LM_LICENSE_FILE to "port@host", where port is the port number on the SERVER line and host is the hostname of the license server. For example, in the C-shell, type: setenv LM_LICENSE_FILE 7312@derwent or in the Bourne shell, type: LM_LICENSE_FILE=7312@derwent export LM_LICENSE_FILE Copy the contents of $EXPLORERHOME/license/bin/i86_n3 into C:\FLEXLM\NAGLM\BIN on the license server. Open an MS-DOS Command Prompt window, change directory to C:\FLEXLM\NAGLM and type the command: bin\lmgrd -app -c C:\FLEXLM\NAGLM\LICENSE.DAT This will start the license manager and report its success or failure. If any problems are reported, rectify them using the information in the FLEXlm End User Manual and FAQ. To terminate the license manager, change directory to C:\FLEXLM\NAGLM and type the command: bin\lmutil lmdown -c C:\FLEXLM\NAGLM\LICENSE.DAT The license manager is most easily controlled by the "Configuration using Services" facility of the lmtools program, as described in Chapter 7.15 of the FLEXlm End User Manual. Use the Service Name "FLEXlm License Manager for NAG". 2.4. Quick Test Assuming that you have installed in /usr/local/explorer and completed the installation procedure detailed in the previous section, you can test some basic functionality as follows: % source /usr/local/explorer/sample.cshrc % explorer -map $EXPLORERHOME/maps/simple.map This draws a simple 3D model which you can rotate with the mouse. Try any other maps in the $EXPLORERHOME/maps directory. 3. Further Information 3.1. Online Documentation A full set of documentation in online hypertext format is provided with this release of IRIS Explorer. The root of the online distribution is at $EXPLORERHOME/doc/html/index.htm The documentation can be viewed by any suitable HTML browser such as Mozilla. For example, if you are using Mozilla from your shell window, type mozilla $EXPLORERHOME/doc/html/index.htm The documentation set comprises an introductory tutorial, plus a four volume manual set for the system: IRIS Explorer User's Guide IRIS Explorer Reference Pages IRIS Explorer Module Writer's Guide IRIS Explorer Collaborative User's Guide together with a list of Frequently Asked Questions (with pointers to interactive demos). The documentation also contains external links to case studies, training course information, an on-line user newsletter and a module repository; use of these external links requires your computer to be connected to the Internet. 3.2. Configuration Files The default preferences file for IRIS Explorer is $EXPLORERHOME/Explorer.config. It contains the default locations of modules and maps, establishes module categories, and sets the shared memory arena size. You can customize your own preferences by editing the sample.explorerrc file in $EXPLORERHOME and saving the updated copy under the name .explorerrc in your home directory. 3.3. Network OpenGL issues There are a number of modules that originally used the OpenGL 3D graphics library for rendering. Specifically, these modules are ColorEditor, Render, RenderRemote, TransformGen, ViewGeom and VolumeRender. In this distribution, the executable for each module is dynamically linked against the system Mesa libraries (see Section 1.3, above). Some versions of those libaries take advantage of 3D graphics hardware acceleration and will render only on an OpenGL-capable display - specifically, one where the X server has the GLX extension. If this is missing, the module will exit with an error message like: Render: Xlib: extension "GLX" missing on display "otley:0.0". In this case, it might be helpful to switch to using a version of the Mesa libraries which does not take advantage of hardware acceleration, and which will render on any X display, but with a comparative performance penalty. To make this switch, use the command /usr/X11R6/bin/switch2mesasoft (which is part of the mesasoft package). Switch back to using the hardware accelerated version of the libraries using a command like /usr/X11R6/bin/switch2xf86_glx (the name of this command will depend on which packages are installed and, in turn, on the specific hardware acclerator on your machine - for example, this comes from xf86_glx). Note that you must be root to execute these commands. One other issue is noteworthy. For some values of the DISPLAY variable, an OpenGL module will produce a message like: Render: Xlib: connection to ":0.0" refused by server Render: Xlib: No protocol specified Render: This message does not affect the operation of the module and can be ignored. 3.4. Other Installation Information Most modules built under IRIS Explorer version 5.0 will require recompilation and relinking before they will work in IRIS Explorer 5.2. Module resource files, map files, DataScribe script files, and saved lattice or pyramid files have not changed in structure between versions 5.0 and 5.2. Maps which generate text (e.g. using the DrawText module) for display in the Render module need to be able to find TrueType fonts for the display of the text. This version of IRIS Explorer uses the FreeType Font Engine (see Section 1.3) to handle fonts. The environment variable FL_FONT_PATH specifies the directory containing the font files. The fonts distributed in $EXPLORERHOME/data/fonts are automatically picked up by IRIS Explorer; FL_FONT_PATH need only be used to specify additional font directories. Each font can then be selected by specifying the name of its file in the FontName text slot on the control panel of DrawText. 3.5. Known Problems with this Release The group compilation process has been tested extensively and has been found to work with several groups of modules, but it cannot be guaranteed to behave correctly with every combination of modules. In particular, problems may occur for groups that include multiple instances of modules which are statically linked to libraries containing global or static data. Examples of these types of modules include those that use the NAG Graphics Library, LatFunction-based modules and ImageVision modules on some platforms. The LineGraph module has been omitted from this release. The NAGGraph module may be used in its place. The VolumeRender module has been omitted from this release. The VolumeToGeom module may be used in its place. The ReadPhoenics module has been omitted from this release. The cxGeoPlot* API routines have been omitted from this release. The documentation has not been updated from Release 5.0 for this release. 4. Support from NAG (a) Contact with NAG Queries concerning this document or the implementation generally should be directed initially to your local Advisory Service. If you have difficulty in making contact locally, you can contact NAG directly at one of the addresses given in the Appendix. Users subscribing to the support service are encouraged to contact the IRIS Explorer Centers (see below). The NAG Response Centres are available for general enquiries from all users. (b) IRIS Explorer Centers The IRIS Explorer Centers are available for technical queries from sites with an annually licensed product or support service. The IRIS Explorer Centers are open during office hours, but contact is possible by fax, email and phone (answering machine) at all times. When contacting the IRIS Explorer Centers please quote your NAG site reference and NAG product code (in this case IEL6A52NA). Contact details for the IRIS Explorer Centers are the same as those for the NAG offices; they are given in the Appendix at the end of this Note. (c) NAG Websites The NAG websites are an information service providing items of interest to users and prospective users of NAG products and services. The information is reviewed and updated regularly and includes implementation availability, descriptions of products, downloadable software, product documentation and technical reports. The NAG websites can be accessed at http://www.nag.co.uk/ or http://www.nag.com/ (in North America) or http://www.nag-j.co.jp/ (in Japan) (d) NAG Electronic Newsletter If you would like to be kept up to date with news from NAG you may want to register to receive our electronic newsletter, which will alert you to special offers, announcements about new products or product/service enhancements, case studies and NAG's event diary. To register visit one of our websites or contact us at nagnews@nag.co.uk. 5. User Feedback Many factors influence the way NAG's products and services evolve and your ideas are invaluable in helping us to ensure that we meet your needs. If you would like to contribute to this process we would be pleased to receive your comments by email at feedback@nag.co.uk. Alternatively contact the appropriate NAG Response Centre who will be happy to record your comments. Appendix - Contact Addresses NAG Ltd Wilkinson House Jordan Hill Road OXFORD OX2 8DR NAG Ltd Response Centre United Kingdom email: support@nag.co.uk Tel: +44 (0)1865 511245 Tel: +44 (0)1865 311744 Fax: +44 (0)1865 310139 Fax: +44 (0)1865 310139 NAG Inc 1431 Opus Place, Suite 220 Downers Grove IL 60515-1362 NAG Inc Response Center USA email: infodesk@nag.com Tel: +1 630 971 2337 Tel: +1 630 971 2345 Fax: +1 630 971 2706 Fax: +1 630 971 2706 Nihon NAG KK Hatchobori Frontier Building 2F 4-9-9 Hatchobori Chuo-ku Tokyo 104-0032 Japan email: sales@nag-j.co.jp Tel: +81 (0)3 5542 6311 Fax: +81 (0)3 5542 6312