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?

As of the time of this writing (August 2005), the OpenRM build process does not provide a "make install" target on Windows. This means that you must first unpack and build in some random directory, perhaps c:\temp. Next, you'll perform the compilition. Finally, you may want to create an installation of OpenRM on your system that is available to others.

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

• You will be building the OpenRM development and demonstration packages in subdirectories rooted at c:\openrm.

2. #### Unpacking the openrm-devel distribution.

First, create the openrm directory rooted in c:\temp:

	c:> cd c:\
c:> mkdir openrm


Next, unpack the OpenRM development package under that directory. From Windows Explorer (not Internet Explorer), change the directory to c:\temp, where you downloaded openrm-devel-1.6.0.tar.gz, and click on the file openrm-devel-1.6.0.tar.gz. Winzip will then launch (if you don't have Winzip on your system, you can grab an evaluation version for free from www.winzip.com). Click on "Yes" when Winzip asks you if it should uncompress the openrm-devel file into a temporary folder.

Assuming you are using the "Classic Winzip" interface, click on the button that says "extract." Type in c:\openrm\ as the directory into which the contents of the archive will be extracted. You may close Winzip when the extraction process has completed.

This process will create the subdirectory rm160 under c:\openrm, and the OpenRM source and headers will be unloaded into this new directory. You can verify this is the case by using Windows Explorer to peek inside c:\openrm\rm160.

3. #### Third Party Software Dependencies

Starting with v1.4.0 of OpenRM, we've introduced dependencies upon third party software in order to provide support for different types of file i/o, as well as support for multistage and multithreaded rendering capabilities. Of these dependencies, we rely upon a third party library to provide an implementation of Posix threads on Win32 system, and this additional software must be installed on your system prior to building OpenRM.

• #### Microsoft Visual C++, Version 6.0

We have built and tested OpenRM 1.6.0 using Microsoft's Visual C++ compiler, version 6.0 on these Win32 platforms: Windows XP Professional. Earlier in OpenRM's history, the builds were performed and tested on these other Windows platforms: Windows 98 Second Edition, Windows NT Workstation Version 4, Service Packs 4 and 6a, Windows 2000 Professional Workstation, Windows Millenium Edition, Windows 95. Since we no longer have access to these older distributions, we cannot claim that the current OpenRM version will build and run on those platforms.

Prior to OpenRM 1.6.0, you had to do builds on Windows using "nmake" (MS's "make" program) from the command line. Starting in 1.6.0, we added MSVC workspaces so that you can do debug and non-debug builds of all OpenRM libraries from inside MS Visual Studio.

• #### Posix Threads (Optional, but recommended)

Normally, OpenRM requires the presence of Posix Threads for thread creation, control and synchronization. The "win-32" and "win-32-debug" build targets imply the presence of Posix Threads as described in the following paragraphs.

Beginning with OpenRM 1.6.0, we have provided build targets with which you may build a version of OpenRM that does not use the Posix Threads library, and correspondingly, does not provide any explicit support for parallelization. On Linux platforms, use the "linux-nopthreads" and "linux-nopthreads-debug" build targets. On Windows, use the "win-32-nopthreads-static" build target to compile OpenRM without needing a Posix Threads library. Note the "win-32-nopthreads-static" build is available only via the command line build interface. There is no corresponding "no Posix Threads" build target at this time in the form of a MSVC workspace.

On Windows, we rely on an implementation of Posix threads provided by Ross Johnson's Posix Threads for Win32 project. (Please be sure to thank Ross Johnson for providing this invaluable library.) If that site is busy, there is a mirror at the R3vis website, which is linked from the OpenRM download page. Note that installation of this package is required in order to build the OpenRM libraries and demonstration programs.

Our Makefile.w32 in the rmdemo distribution assumes a particular directory layout that is slightly different than the directory layout inside the pthreads-win32-*.exe distribution. We assume the following directory structure:

\pthreads
\include
\lib


The makefiles for both openrm-devel and openrm-demo distributions assume such a directory structure for Pthreads.

• #### The JPEG Library (Optional)

If you wish to enable OpenRM support for JPEG raster file i/o, you will need to obtain and build the JPEG library as Windows does not provide the JPEG headers or libraries with the OS distribution. You may grab a copy of the JPEG source distribution for free from Independent JPEG Group website. On the other hand, if you don't want to bother with downloading and building the JPEG library, you can make a one-line modification to the OpenRM source code prior to building the libraries (see below).

On Windows, you have (at least) two choices for building the JPEG libraries. First, if you use the MSVC OpenRM build workspaces, you'll see that the source code for the JPEG-6b library has been incorporated into the openrm-devel source tree, and that workspace builds will produce debug and release versions of the JPEG-6b libraries. Second, you may manually download the jpeg6b.src.tar.gz tarball from the IJG website, unpack into c:\jpeg-6b, then build as follows:

	c:> cd \jpeg-6b
c:> copy jconfig.vc jconfig.h
c:> nmake /f Makefile.vc


On the other hand, if you wish to disable OpenRM's JPEG support, you can make a simple modification to the OpenRM source. You will need to modify the file c:\openrm\rm160\include\rmi\rmi.h, using your favorite Win32 text editor to change this line:

	#define RM_JPEG 1


to this:

	#define RM_JPEG 0


If you make this change, you can build and use the OpenRM libraries and demo programs without the JPEG libaries. You can undo the change if you later decide to install the JPEG libraries and headers to make use of OpenRM's JPEG support. If you undo the change, be sure to recompile the rmi library inside of OpenRM.

4. #### Compiling the openrm-devel distribution using MS Visual Studio Workspaces (New in 1.6.0)

In the openrm-devel-1.6.0 distribution is a new directory named visualc. After you launch MS Visual Studio on your machine, read the single workspace named openrm-devel.dsw from the rm160/visualc directory. We usually just do a "batch build" and let MSVC build both Debug and Release versions of all the OpenRM and JPEG libraries. All libraries are placed in rm160/lib upon completion.

As of the time of this writing (August 2005), only non-DLL libraries are built by this script. If you want DLLs, you will have to use the command-line build process and choose the win-32-dynamic build target.

Why use the MSVC interface to build the libraries? Arguably, it is somewhat easier then dealing with a command line. As of the time of this writing (August 2005), none of the other demonstration applications (openrm-demo, openrm-gordo) have corresponding MSVC workspaces, although building them is on the To-Do list.

5. #### Compiling the openrm-devel distribution.

The Microsoft make utility nmake is provided as part of the MSVC++ distribution, and the OpenRM Win32 Makefiles were written for nmake. Prior to building OpenRM, you need to have the directory to nmake and the compiler in your path. Assuming the sane path name for the MSVC++ install, you can accomplish this with:

	c:> cd \Program Files\Visual Studio 98\bin
c:> vcvars32.bat


(Note: if you installed MSVC into some other location, you will have to manually search on your machine to locate the "vcvars32.bat" file, or otherwise manually modify your environment to include the compiler "cl" and Make application "nmake" in your path.)

The vcvars32.bat script will modify your environment in order to have the compiler and other utilities placed into your PATH. This script will chew up a lot of environment space, and if you are on a Win98 or WinME system, you may get a message that says "out of environment space." You can remedy this situation by modifying how an MS-DOS shell is launched: first, launch a shell (on a Win98 SE system, it is Start->Programs->MS-DOS Command Prompt), then right-click with the cursor in the title bar of the shell. A menu will pop up. Change your environment size to 2048 bytes by modifying the "Cmd line:" value to this:

	c:\WINDOWS\COMMAND.COM /e:2048


Note that on this same menu, there is a line called "Batch file," and you could add a link to the vcvars32.bat file in that line to simplify your life.

We've not had any problems running out of environment space on Windows XP Pro or Windows 2000 Workstation.

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

	c:> cd \openrm\rm160
c:> nmake build-target


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

Target Notes
win-32-static
1. Creates debuggable, static libraries.
2. Assumes a Posix Threads library has been installed on your system.
3. If JPEG support is enabled, make.cfg assumes jpeglib.h and friends live in c:\jpeg-6b.
win-32-dynamic
1. Creates debuggable DLL libraries.
2. Assumes a Posix Threads library has been installed on your system.
3. If JPEG support is enabled, make.cfg assumes jpeglib.h and friends live in c:\jpeg-6b.
1. Creates debuggable static libraries.
2. If JPEG support is enabled, make.cfg assumes jpeglib.h and friends live in c:\jpeg-6b.
3. Will not compile using Posix Threads: no pthreads header files required, and no parallelization suppport will be provided.
1. Creates debuggable DLL libraries.
2. If JPEG support is enabled, make.cfg assumes jpeglib.h and friends live in c:\jpeg-6b.
3. Will not compile using Posix Threads: no pthreads header files required, and no parallelization suppport will be provided.
6. #### Unpacking the openrm-demo distribution.

(Sorry - this section still needs to be written)

7. #### Compliing the openrm-demo distribution.

(Sorry - this section still needs to be written)

8. #### Running the demo programs.

(Sorry - this section still needs to be written)

9. ##### Obtaining Win32 Binaries

If this all seems like too much trouble to you, take heart, you're not alone. Starting with v1.4.3, R3vis is providing a tarball containing pre-built Win32 OpenRM libraries (dynamic DLLs), along with pthreads for Win32 in the appropriate directory structure, and a prebuilt version of FLTK for applications development. Unfortunately, we have to charge a nominal packaging fee for this distribution, but it is inexpensive and is available to purchase and download online. Visit this page for more information.