Beckman Institute University of Illinois at Urbana-Champaign

Syzygy Documentation: Supporting Libraries

Integrated Systems Lab
12/19/2006

Syzygy's build system is designed to let you compile your software using the optional supporting libraries but without installing them in a standard system location. This allows non-root users to compile Syzygy with supporting libraries. The build system expects the "external" libraries to be installed in a directory given by the SZGEXTERNAL environment variable.

The Syzygy makefiles (via szg/build/make/Makefile.libscan) will automatically detect the presence of the libraries, given that they are copied to the places outlined below. See Makefile.libscan for details. This is the file you should change if you need to use different library versions or otherwise tweak this process for your local installation.

General Comments on External Libraries

With the possible exception of the GLUT libraries, if you do not properly install an optional library in SZGEXTERNAL, Syzygy programs will still build and run, but with certain features (such as sound) disabled. When an external library requires a shared library, the runtime linker must be able to find it. A Makefile target exists to install shared libries in $SZGBIN.

    cd $SZGHOME/build
    make install-shared

If you have compiled your executables from scratch on a Unix system, they have a runtime linker path including $SZGBIN. Consequently, installing the shared libraries with the Syzygy executables will let the runtime linker find them. If you are on a Windows system, the runtime linker automatically searches the directory in which the executable it runs resides.

If you are using a precompiled SDK on a Unix-like system, you will need to add the $SZGBIN to the dynamic linker's path.

A note about GLUT. Syzygy compilation requires it (although hopefully it won't in version 1.2). Some systems will have in installed by default (Mac OS X). Some systems might or might not have it installed (Linux, SGI), and some will probably not have it installed (Windows). If it is installed so that the compiler will automatically find the header and library and the runtime linker will find the shared library, then you need do nothing else. Otherwise, you can either install GLUT like that yourself, or install it for Syzygy only in SZGEXTERNAL, as described below.

Directory Structure of SZGEXTERNAL

The top level of the SZGEXTERNAL directory has subdirectories for each system (Linux, Windows, Mac OS X, SGI) that it supports. When creating your own SZGEXTERNAL, you do not need all of these subdirectories, since you might support only one or two system types.

    SZGEXTERNAL
      darwin
      linux
      sgi
      win32

The subdirectories of each system-specific directory vary depending on the supporting libraries required on that platform. As a general rule, each subdirectory will contain in turn "include" and "lib" subdirectories for headers and libraries, respectively. Here is a list of libraries required for full functionality:

    darwin
      fmod-4
      jpeg

    linux
      fmod-4
      glut-3.7
      jpeg
      lib3ds
      vrpn
      zlib

    sgi
      glut-3.7

    win32
      STLport
      ascension
      fmod-4
      glut-3.7
      isense
      jpeg
      lib3ds
      sapi-5.1
      zlib
      evart

Use of Specific Libraries

STLport: Visual Studio 6 (Windows) needs a replacement STL, which this provides.
ascension: Contains a Windows-only driver for the Flock-of-Birds.
evart: Contains a driver for the Motion Analysis optical motion capture system.
fmod-4: A cross-platform sound library.
glut-3.7: A cross-platform OpenGL windowing library.
isense: Drivers for the Intersense motion trackers.
jpeg: A library for encoding/decoding jpeg image files. Needed by the q33 and cubecake demos.
lib3ds: A library for reading 3ds (3D Studio Max) files.
sapi-5.1: A Microsoft text-to-speech library.
vrpn: A library for interfacing with VR input devices.
zlib: A library for compressing/decompressing files. Needed by the q33 and cubecake demos.

Installing Libraries for Windows

Of special note is the STLport library. If you are using Visual Studio 6 to compile Syzygy, you CANNOT use the native STL. In this case, you MUST use STLport (the software will crash otherwise). If you are using Visual STudio .NET, you should use the native STL.

STLport
1. You should only compile against STLport if you have Visual Studio 6.
2. Down and compile STLport (you will want the iostream library, not just the header files).
3. Make a directory $(SZGEXTERNAL)/win32/STLport. This is the Syzygy STLport directory (in contrast with the native STLport directory where you compiled the software).
4. From the native STLport directory, copy the lib and stlport subdirectories to the Syzygy STLport directory.
ascension
1. Download BirdWindowsDriver.zip from the Ascension website.
2. Copy Bird.lib and Bird.dll to $(SZGEXTERNAL)/win32/ascension/lib.
3. Copy Bird.h to $(SZGEXTERNAL)/win32/ascension/include.
evart
1. You should have received files EvaRT.h, macrtcom.lib, and macrtcom.dll with your optical motion capture system.
2. Copy EvaRT.h into $(SZGEXTERNAL)/win32/evart/include.
3. Copy macrtcom.lib and macrtcom.dll into $(SZGEXTERNAL)/win32/evart/lib.
fmod-4
1. For sound support, install fmod version 4.
2. Copy fmod.dll and fmodvc.lib into $(SZGEXTERNAL)/win32/fmod-4/lib.
3. Copy these include files into $(SZGEXTERNAL)/win32/fmod-4/include: fmoddyn.h, fmod.h, fmod_errors.h, wincompat.h.
4. If you don't copy these files, Syzygy will still build and run but sound support will be disabled.
glut-3.7
1. You will need to obtain GLUT since it is not built in on Windows systems.
2. Download GLUT-3.7.
3. Make a directory $(SZGEXTERNAL)/win32/glut-3.7/include/GL and put glut.h there.
4. Make a directory $(SZGEXTERNAL)/win32/glut-3.7/lib and put glut32.dll and glut32.lib there.
isense
jpeg
1. You will need to download, configure, and compile libjpeg for your system. This is trickier than on Unix-like systems.
  1. Before compiling, copy jconfig.vc to jconfig.h.
  2. Before compiling, copy makefile.vc to Makefile.
  3. Before compiling, edit jmorecfg.h so that:
```
      #ifndef XMD_H                   /* X11/xmd.h correctly defines INT32 */
      typedef long INT32;
      #endif
```
    becomes
```
      #ifndef _BASETSD_H_
      #ifndef XMD_H                   /* X11/xmd.h correctly defines INT32 */
      typedef long INT32;
      #endif
      #endif
```
  4. Before compiling, edit Makefile so that
```
      $(cc) $(CFLAGS) $*.c
```
    becomes
```
      $(cc) $(CFLAGS) /MD $*.c
```
  5. You will need to use nmake from a DOS prompt to build the software.
2. Make a directory $(SZGEXTERNAL)/win32/jpeg/lib and copy libjpeg.lib there.
3. Make a directory $(SZGEXTERNAL)/win32/jpeg/include and copy jconfig.h, jmorecfg.h, and jpeglib.h there.
lib3ds
1. In order to import .3ds files (Autodesk 3D Studio format), you will need to build and install lib3ds. Included in $SZGHOME/contrib/ is a folder named "lib3ds", which is simply the latest release of lib3ds, downloaded from the SourceForge lib3ds page. Follow the instructions provided in $SZGHOME/contrib/lib3ds/INSTALL to build the library.
2. Make a directory $(SZGEXTERNAL)/win32/lib3ds/include/lib3ds and copy all header files there.
3. Make a directory $(SZGEXTERNAL)/win32/lib3ds/lib and copy lib3ds.lib there.
sapi-5.1
zlib
1. Download, configure, and compile zlib. This will be done using nmake from the DOS prompt. You will want to add the compile flag "/MD" as in the libjpeg example above.
2. Make a directory $(SZGEXTERNAL)/linux/zlib/lib and copy libz.lib there.
3. Make a directory $(SZGEXTERNAL)/linux/zlib/include and copy zconf.h and zlib.h there.
GL
1. This is only used to provide glext.h to certain demos (q33 and cubecake).
2. Make a directory $(SZGEXTERNAL)/win32/GL/include. Copy glext.h there.
3. Make a directory $(SZGEXTERNAL)/win32/GL/include/GL. Copy glext.h there.

Installing Libraries for Mac OS X (darwin)

fmod-4
1. For sound support, install fmod version 4.
2. Copy libfmod.a into $(SZGEXTERNAL)/darwin/fmod-4/lib.
3. Copy these include files into $(SZGEXTERNAL)/darwin/fmod-4/include: fmoddyn.h, fmod.h, fmod_errors.h, wincompat.h.
4. If you don't copy these files, Syzygy will still build and run but sound support will be disabled.
jpeg
1. Either download, configure, and compile libjpeg or simply copy the files that are already installed on your system (try 'locate libjpeg').
2. Make a directory $(SZGEXTERNAL)/darwin/jpeg/lib and copy libjpeg.a there.
3. Make a directory $(SZGEXTERNAL)/darwin/jpeg/include and copy jconfig.h, jmorecfg.h, and jpeglib.h there.

Installing Libraries for Linux

fmod-4
1. For sound support, install fmod version 4.
2. Copy libfmod-4.so into $(SZGEXTERNAL)/linux/fmod-4/lib.
3. Copy these include files into $(SZGEXTERNAL)/linux/fmod-4/include: fmoddyn.h, fmod.h, fmod_errors.h, wincompat.h.
4. If you don't copy these files, Syzygy will still build and run but sound support will be disabled.
glut-3.7
1. Download and compile GLUT-3.7.
2. Make a directory $(SZGEXTERNAL)/linux/glut-3.7/include/GL and put glut.h there.
3. Make a directory $(SZGEXTERNAL)/linux/glut-3.7/lib and put libglut.so.3.7 there. You will also need to make symbolic links like so:
```
        ln -s libglut.so.3.7 libglut.so.3
        ln -s libglut.so.3 libglut.so
```
jpeg
1. Either download, configure, and compile libjpeg or simply copy the files that are already installed on your system (try 'locate libjpeg.a').
2. Make a directory $(SZGEXTERNAL)/linux/jpeg/lib and copy libjpeg.a there.
3. Make a directory $(SZGEXTERNAL)/linux/jpeg/include and copy jconfig.h, jmorecfg.h, and jpeglib.h there.
lib3ds
1. In order to import .3ds files (Autodesk 3D Studio format), you will need to build and install lib3ds. Included in $SZGHOME/contrib/ is a folder named "lib3ds", which is simply the latest release of lib3ds, downloaded from the SourceForge lib3ds page. Follow the instructions provided in $SZGHOME/contrib/lib3ds/INSTALL to build the library.
2. Make a directory $(SZGEXTERNAL)/linux/lib3ds/include/lib3ds and copy all header files there.
3. Make a directory $(SZGEXTERNAL)/linux/lib3ds/lib and copy lib3ds.a there.
vrpn
1. Download and compile vrpn.
2. Copy libvrpn.a to $(SZGEXTERNAL)/linux/vrpn/lib.
3. Make a directory $(SZGEXTERNAL)/linux/vrpn/include and copy the vrpn header files there. Note that only vrpn_Shared.h, vrpn_Tracker.h, vrpn_Analog.h, and vrpn_Button.h are needed.
zlib
1. Either download, configure, and compile zlib or simply copy the files that are already installed on your system (try "locate libz.a").
2. Make a directory $(SZGEXTERNAL)/linux/zlib/lib and copy libz.a there.
3. Make a directory $(SZGEXTERNAL)/linux/zlib/include and copy zconf.h and zlib.h there.

Installing Libraries for SGI

glut-3.7
1. Download and compile GLUT-3.7. You will want to compile "n32" format objects since this is what Syzygy uses.
2. Make a directory $(SZGEXTERNAL)/sgi/glut-3.7/include/GL and put glut.h there.
3. Make a directory $(SZGEXTERNAL)/sgi/glut-3.7/lib and put libglut.a there.

[Schedule] [Labs] [Beckman Meeting Rooms] [Equipment] [Projects] [CUBE Projects] [Syzygy] [VSS] [People] [Events] [Publications]