Table of Contents - Unix Builds

  1. Preliminaries
  2. Unpacking the openrm-devel distribution.
  3. Third Party Software Dependencies
  4. Compiling the openrm-devel distribution.
  5. Installing the OpenRM libraries and headers.

  6. Unpacking the openrm-demo distribution.
  7. Configuring and compliing the openrm-demo distribution.
  8. Running the demo programs.

  1. Preliminaries

    Before we get started with the details of building OpenRM, we should spend a moment to identify the goals of the build process. The most obvious goal is to build OpenRM. A more subtle goal is consideration of the longer term objectives - are you going to place the OpenRM headers and libraries in a "standard location" for general use on your system?

    Beginning with OpenRM version 1.5.2 (April 2004), a "make install" target is provided on Unix/Linux systems. However, since we're not using "autoconf" or a similar facility, the install directory path is located in the main Makefile, and must be edited by hand (sorry) if you don't like the default install location. Therefore, for these instructions, we assume that you will be unpacking the OpenRM distribution somewhere into /tmp for the purpose of building, and then will install into the default location, which is /usr/local/rm160.

    For the purposes of simplifying the following discussion, we are going to make these assumptions:

    • The OpenRM development and demo tarballs were downloaded into /tmp on your system.
    • You will be building the OpenRM development and demonstration packages in subdirectories rooted at /tmp/openrm.
    • You will be installing the OpenRM headers, libraries and documentation into /usr/local/rm160.

  2. Unpacking the openrm-devel distribution.

    First, create the openrm directory rooted in /tmp:

    % cd /tmp % mkdir openrm

    Next, unpack the OpenRM development package under that directory

    % cd /tmp/openrm % gunzip -dc /tmp/openrm-devel-1.6.0.tar.gz | tar xvf -

    That will create the subdirectory rm152 under /tmp/openrm, and the OpenRM source and headers will be unloaded into this new directory.

  3. Third Party Software Dependencies

    Starting with v1.4.0 of OpenRM, we've introducted dependencies upon third party software in order to provide support for i/o for different types of files. As of the time of this writing (August 2001), the only dependency is upon the JPEG library, and this will affect only Solaris (and Win32) users, as JPEG headers and libraries are provided with other OSs. In the future, this section will be expanded as a function of an increasing number of dependencies.

    If you wish, you can disable the dependency upon the JPEG library and headers. This is a one-line change:

    % cd /tmp/openrm/rm160/include/rmi % vi rmi.h

    Inside rmi.h, change this line:

    #define RM_JPEG 1

    to this:

    #define RM_JPEG 0

    You must make this change prior to compiling the OpenRM distribution. This change will result in a build that does not depend upon the JPEG headers or libraries, and which will not support JPEG file i/o.

  4. Compiling the openrm-devel distribution.

    To build OpenRM, you start the make process from the directory where OpenRM is installed:

    % cd /tmp/openrm/rm160 % make target-architecture

    Where target-architecture is one of the following build targets:

    Target Notes
    linux
    linux-debug
    1. Builds for x86 Linux (tested on Fedora Core 4, SuSE 9.2 and 9.3 Professional)
    2. Use linux-debug for debuggable builds.
    3. Assumes that OpenGL headers are located under /usr/include/GL.
    4. Assumes that X headers are located under /usr/X11R6/include.
    5. If JPEG support is enabled, make.cfg assumes jpeglib.h and friends live in /usr/include.
    linux-x86_64
    linux-x86_64-debug
    linux-x86_32
    linux-x86_32-debug
    1. Builds for either the 64-bit or 32-bit ABIs on 64-bit Linux on AMD64 systems (tested on SuSE 9.1).
    2. Use the *-debug variants for debuggable builds.
    3. Assumes that OpenGL headers are located under /usr/include/GL.
    4. Assumes that X headers are located under /usr/X11R6/include.
    5. If JPEG support is enabled, make.cfg assumes jpeglib.h and friends live in /usr/include.
    linux-nopthreads
    linux-nopthreads-debug
    1. Primary objective of this build target is to exercise a build version that does not use the Posix threads library. When using these build targets, none of OpenRM's parallelization or synchronization capabilities (that rely on Posix Threads library support) are available, although both OpenRM and applications that use those OpenRM constructs will still compile. Most notably, the RMpipe parallel processing modes (RM_PIPE_MULTISTAGE_PARALLEL and RM_PIPE_MULTISTAGE_VIEW_PARALLEL) are not available, and their use will produce a runtime error message.
    2. Builds for x86 Linux (tested on Fedora Core 4, SuSE 9.2 and 9.3 Professional).
    3. Use linux-nopthreads-debug for debuggable builds.
    4. Assumes that OpenGL headers are located under /usr/include/GL.
    5. Assumes that X headers are located under /usr/X11R6/include.
    6. If JPEG support is enabled, make.cfg assumes jpeglib.h and friends live in /usr/include.
    macosx-X11
    macosx-X11-debug
    1. Builds MacOSX (Darwin).
    2. Use macosx-X11-debug for debuggable builds.
    3. Assumes that OpenGL headers are located under /usr/X11R6/include/GL.
    4. Assumes that X headers are located under /usr/X11R6/include.
    5. If JPEG support is enabled, make.cfg assumes jpeglib.h and friends live in /usr/local/include. Note: Darwin/MacOSX does not provide the JPEG libraries and headers by default. You will have to obtain, build and install the JPEG library for yourself.
    solaris
    solaris-debug
    1. Builds for Solaris (tested on 2.6 and 2.8).
    2. Use solaris-debug for debuggable builds.
    3. Assumes that OpenGL headers are located under /usr/openwin/include/GL.
    4. Assumes that X headers are located under /usr/openwin/include.
    5. If JPEG support is enabled, make.cfg assumes jpeglib.h and friends live in /usr/local/include. Note: Solaris does not provide the JPEG libraries and headers by default. You will have to obtain, build and install the JPEG library for yourself.
    irix6-32
    irix6-32-debug
    irix6-n32
    irix6-n32-debug
    irix6-n32-mips4
    irix6-n32-mips4-debug
    irix6-64
    irix6-64-debug
    1. Builds for IRIX ABI targets: "old" 32-bit, "new" 32-bit, 64-bit. Tested on IRIX 6.5.X (and earlier versions).
    2. Use irix6-*-debug for debuggable builds.
    3. Assumes that OpenGL headers are located under /usr/include/GL.
    4. Assumes that X headers are located under /usr/include.
    5. If JPEG support is enabled, make.cfg assumes jpeglib.h and friends live in /usr/include.
    6. There is some confusion on IRIX about what kind of code is generated during -n32 builds. The man pages say that -mips3 code is generated, but our experience shows that -mips4 is generated. Your mileage may vary depending upon which revision of 6.5 is installed on your machine. Hint: check the /etc/compilerdefaults file.
    freebsd
    1. Builds for FreeBSD systems.
    2. The OpenRM development team has not tested the FreeBSD build. The build target and mklib.freebsd script were contributed by the OpenRM user community.
    netbsd
    netbsd-debug
    netbsd-pkgsrc
    1. Builds for NetBSD systems.
    2. The OpenRM development team has not tested the NetBSD build. These build targets and the mklib.netbsd and mklib.netbsd-pkgsrc scripts were contributed by the OpenRM user community.

    In most circumcstances, these assumptions will prove to be valid. If you need to alter paths, edit the make.cfg file.

  5. Installing the OpenRM libraries and headers.

    Beginning with OpenRM version 1.5.2 (April 2004), there is a "make install" target that will copy the OpenRM libraries, headers and documentation into a "standard location". After you successfully compile OpenRM, to install the libraries, headers and docs, type:

            % make install
    

    Note that /usr/local/rm152 is the destination for the install. In most cases, you need sudo or root access to write into /usr/local. If you wish to install OpenRM into some other location, such as /home/joe/rm160, then you will need to edit the main OpenRM Makefile (sorry) and change the line that reads:

       INSTALL_DIR = /usr/local/rm160
    

    to this:

       INSTALL_DIR = /home/joe/rm160
    

    You can choose to install OpenRM anywhere you like. However, all of the the OpenRM demonstration programs - the RMdemo distribution, the OpenRM/Chromium distribution, the OpenRM/CAVE demos and the Gordo distribution - all expect that OpenRM is install in /usr/local/rm160.

  6. Unpacking the openrm-demo distribution.

    First, create a directory for the OpenRM demonstration programs in the same location where you unpacked the OpenRM headers and libraries:

    	% cd /tmp/openrm
    	% mkdir rmdemo
    

    Next, unpack the OpenRM demonstration programs under that directory:

    	% cd /tmp/openrm
    	% gunzip -dc /tmp/openrm-demo-1.6.0.tar.gz | tar xvf -
    

    That will create the subdirectory rmdemo under /tmp/openrm, and the demo programs source code and data will be unpacked into /tmp/openrm/rmdemo.

  7. Configuring and compling the openrm-demo distribution.

    Inside the /tmp/openrm/rmdemo directory are a couple of Makefiles: Makefile.x11 for Unix/X11 and Makefile.w32 for Win32 systems. The Makefile.x11 file includes a file called makeinclude, and makeinclude has the definitions that are likely to vary from system to system.

    Also included in the /tmp/openrm/rmdemo directory is a shell script called configure that you should use to generate a makeinclude for your particular system. The configure script will detect which OS you are running, and in the absence of any command-line arguments, will generate reasonable default values for the "standard" libraries and headers, such as X11, OpenGL and JPEG (except for Solaris and MacOSX, where JPEG must be manually installed). Chances are, most of you will only need to specify the location of OpenRM Scene Graph on your system. The table below lists the command line flags, their default values along with some additional information.

    The configure script takes up to seven command line arguments that specify:

    1. The location of OpenRM Scene Graph.
    2. The location of OpenGL.
    3. The location of X11.
    4. The location of the JPEG libraries and headers.
    5. The location of Chromium on your system.
    6. An ABI specification.
    7. Compiler optimization arguments.


    Command line flag Default Value Info
    -rm=/locationOf/OpenRMSceneGraph /usr/local/rm160 Specify the location of the OpenRM Scene Graph headers and libraries. Under the directory specified here, the headers should live in an "include" subdirectory, and the libraries should live in a "lib" subdirectory.
    -opengl=/locationOf/OpenGL Solaris: /usr/openwin
    Linux/FreeBSD/MacOSX/Irix: /usr
    Under most circumstances, you should not need to change the value of this flag. We use it occasionally to test against new versions of Mesa. Note that OpenRM requires the libGLU library in addition to libGL. If your system does not have libGLU, you can grab a tarball from the Mesa website and build/install for your system.
    -x11=/locationOf/x11 Solaris: /usr/openwin
    Linux/FreeBSD/MacOSX: /usr/X11R6
    Irix: /usr
    Under most circumstances, you should not need to change the value of this flag. This command-line option will likely be deprecated in a future release.
    -jpeg=/location/of/JPEGstuff Linux, Irix: Depends upon ABI.
    Solaris, MacOSX: No default location.
    On some OSs where the JPEG headers and libraries are installed, their location is a function of the ABI. For example, if you're building for a 64-bit ABI on Linux, the libraries are located in /usr/lib64 and the headers are located in /usr/include. The configure script knows about these nuances and will do the right thing. Note that the SGI guys goofed when they put Irix together - there is no 64-bit version of the JPEG library included with Irix. You'll have to build it yourself. The version SGI ships is not compatible with the most recent version of the source code from the JPEG working group, so you're on your own here.

    On the other hand, if you specify a value for this argument, it is assumed that JPEG headers and libs live in the one directory that you specify. This approach works if you have simply unpacked the jpeglib source into a single directory and built it - the headers and libs will both be in the directory. If you have done something a bit more ambitious like copy the JPEG headers into /usr/local/include and libjpeg.a into /usr/local/lib, then the values placed into makeinclude by the configure script (e.g., /usr/local) will not be accurate, and compilation will fail. You may have to modify the makeinclude file generated by the configure script to manually set up include and link lines to accommodate your setup.
    -cr=/locationOf/Chromium None. Note: Unless you are purposefully attempting to use Chromium, you can ignore this option.
    If you do with to use Chromium, be forewarned that this script will work only for Linux systems. If you are running on a non-Linux system, you must modify the makeinclude by hand. The places where changes are needed should be obvious. This option is intended to specify the root directory for the Chromium installation on your machine.
    -abi=[some abi spec] Each system has a default ABI. All platforms have a default ABI (application binary interface): when you compile and link using default parameters, you get a binary that will run on your system. Some operating systems, like Irix and 64-bit Linux, support multiple ABIs. Both Irix and Linux let you build 64- or 32-bit binaries. The purpose of this flag is to let you specify a specific ABI to match the one you used when building the OpenRM libraries. The ABIs must be the same, otherwise the demo programs will not run.

    The ABI arguments that are supported by the configure script are:
    • irix6-o32 — builds for the "old style" 32-bit ABI on Irix
    • irix6-n32-mips3 — builds for the "new style" 32-bit ABI on Irix using the mips3 instruction set.
    • irix6-n32-mips4 — builds for the "new style" 32-bit ABI on Irix using the mips4 instruction set.
    • irix6-64 &8212; builds for the 64-bit ABI on Irix.
    • linux-x86_64 — builds for the 64-bit ABI on Linux.
    • linux-x86_32 — builds for the 32-bit ABI on Linux.
    Example: to build for the 64-bit ABI on linux, run the configure script as follows:
    % configure -abi=linux-x86_64
    
    -opt=[compiler optimization] None. Use this argument to set other compiler flags, such as optimization level. If you want to specify multiple arguments, enclose the option group in quotes. For example:
    % configure -opt="-g -O2"
    

    After running the configure script, you may want to peek inside the resulting "makeinclude" file to make sure everything seems reasonable. Then, type:

    % make -f Makefile.x11

  8. Running the demo programs.

    All demonstration programs are launched from the command line, and each will do something reasonable with no command line arguments. Prior to running the demonstration programs, be sure to set the LD_LIBRARY_PATH variable:

    % setenv LD_LIBRARY_PATH /usr/local/rm160/lib

    For detailed information about each individual demonstration program, please refer to the OpenRM demonstration program description and usage page.


This page last modified -- Sunday, 07-Aug-2005 08:30:37 PDT