Syzygy works on reasonably modern versions of
Linux, Windows, Mac OS X, and Irix. Every user should read the
You will also want to look at the chapter on
installing supporting libraries
for Syzygy compilation. If you want to write Syzygy
programs in Python, then you will also need to read about compiling the
The following software (and data) packages are part of the
- szg-1.3.zip: Everything necessary to build and test the
libraries. Includes some example programs.
Also includes everything needed for writing Syzygy programs in Python.
- szgdata-1.3.zip: Data necessary for the sample
applications, as outlined in the example programs page,
but excluding some particularly large files, which are available by
- external-1.3.zip: External libraries and headers for all platforms
A Note about GLUT
We're gradually phasing the GLUT dependency out of Syzygy. GLUT is no longer used
for window mangagement, but it is still used in a few places for rendering
(e.g. using glutWireSphere() to draw a wireframe sphere). These are the only
GLUT commands that you can use in your programs, and if you do use them you should
include the header arGlut.h.
OS-Specific Build Instructions
- X11 and ncurses development packages are required for
compilation. Your distribution might not install these by default, e.g.
on Ubuntu 8.04 we install build-essential, libncurses5-dev,
libxi-dev, libxext-dev, libxmu-dev. For Python development install
python-sip4-dev and sip4; note also that if you want to compile the
Python bindings a bug in g++ 4.2 will make this a very slow process;
4.1 or 4.3 will work much better.
- GLUT is required for compilation as well. Either install a
GLUT development package via your distribution (freeglut3-dev)
or install GLUT in Syzygy's external build libraries, as described
- IMPORTANT NOTE: the Syzygy build environment produces code
for the i686 architecture by default.If you have an older processor,
you need to change the "-march=i686" flag in
szg/build/make/Makefile.varslinux. Experiment with either removing it or
downgrading, for instance to "-march=i586".
- Syzygy's build system uses GNU make and either the command line
Visual Studio compiler and linker (either Visual Studio 6 with
the STLPort STL headers or Visual Studio 7 (.NET) without)
or the MinGW implementation of the GNU g++ compiler and linker.
Note that when compiling with g++ on Windows,
the device driver for the SpacePad is unavailable (see
Supported Input Devices.
However, we can supply you with a precompiled binary of
the device driver. Users have successfully built Syzygy with
Visual Studio 2005. New in 1.2: Speech synthesis, .3ds model files,
and joysticks are now supported when using the MinGW g++ compiler. It
turns out that it was possible to build the Python bindings all along,
presumably because the MinGW runtime is linked against the dynamic-linked
Microsoft runtime library.
- You will need a Unix-like environment for Windows that provides a
GNU make utility. We have tested two, MinGW/MSYS and Cygwin. If you're
not currently using either (and are not using Windows 98, see below),
we recommend MinGW. Cygwin is a much larger package, comprising an
entire Unix system, and is only available via a network installer. On
the other hand, MinGW is relatively small and comes as two
- Syzygy programs expect to be able to scrape their name from
the command-line args. The Windows NT, Windows 2000, and Windows XP
(cmd.exe) shells all work. Unfortunately, the Win98 cmd.exe shell
mangles argv, interfering with Syzygy's proper operation. The cygwin
shell does, however, work with Syzygy on all Windows versions,
including Windows 98. Consequently, we recommend using installing and
using the cygwin shell on Windows 98.
- To install MinGW, run the MinGW installer first (which
gives you the underlying system) and then the MSYS installer (which
gives you the Unix-like shell needed to run the commands). Please note,
the MSYS shell, as of this writing, has a hard time printing text from
Syzygy programs (it stalls frequently). Consequently, we recommend running Syzygy commands
from a regular Windows shell (cmd.exe) and only compiling in MSYS. This
workaround means that MinGW is unsuitable for Win98, where cygwin
should be used instead.
- You might prefer to install cygwin (www.cygwin.com) if
you want more Unix functionality from the command line than MinGW
provides. You can create a minimum-disk-space Cygwin which will still
build Syzygy by selecting only these packages (uncheck all
- Category: Base
ash bash cygwin fileutils login sh-utils
- Category: Devel
- Category: Shells
ash bash sh-utils
- Install MS Visual Studio. If you are using Visual Studo 6,
you'll also need STLport to replace VC-6's non-threadsafe STL. With
Visual Studio .NET (i.e. 7), STLport is not necessary.
Please see Supporting Libraries for instructions.
- To compile from the command-line, Visual Studio needs
several enviroment variables to be set appropriately. Please see
Visual Studio Environment Variables for
- You will need to install GLUT, as described in the Windows
section of Supporting Libraries.
Please note that we no longer encourage users to install the glut
headers and library in the Visual Studio directory.
Mac OS X
The Syzygy shared library code uses dlopen, as is provided in
szg/contrib/dlcompat. You must compile this first:
- cd szg/contrib/dlcompat
PLEASE NOTE that the Syzygy application frameworks now use their own
windowing API (as built on X11) in place of GLUT. Consequently, to run
Syzygy graphical applications you will need X11 installed on your system
and running (by default it does not start at system start). If X11 is
not running, the application will fail upon launch with an error message
prompting you to start X11.
Either install GLUT on your machine in the normal Unix way or
follow the SGI instructions here to install
GLUT in a Syzygy-specific way, which does not require "root".
Syzygy Build Environment Variables
The Syzygy build process uses recursive make. A top-level Makefile in
szg/build guesses the operating system and executes a machine-specific
Makefile in a subdirectory. For example, on a Windows machine, the Syzygy
shared library libarLanguage.dll would be built in szg/build/win32/language,
but on a Linux system libarLanguage.so would be built in
szg/build/linux/language. The Makefile guesses the operating system
via uname, defaulting to the OSTYPE environment variable if this fails.
If the top-level makefile fails to guess your machine type, you can fix
the problem by setting $OSTYPE (to "linux" or "cygwin", for instance).
To build Syzygy, You MUST set SZGHOME to the path to the top-level Syzygy install
directory. You will probably also want to set SZGEXTERNAL, which points to the
directory containing the external dependencies (see
Supporting Libraries). By default, copies of libraries and
executables will end up in the directory szg/bin/<OS>, e.g szg/bin/win32; if
you want them to go somewhere else, you can set SZGBIN to the path to
the desired directory.
On Windows, when setting directories with these environment
variables use forward slashes instead of backslashes
and do NOT use the cygwin abbreviations "/cygdrive/d" or "/d" for "d:".
Otherwise, the shell/compiler combination will misinterpret them. For
example, you should use:
The following environment variables are meaningful on all
- SZGHOME: (required) The top-level syzygy directory (for
- SZGEXTERNAL: (optional) The location of external libraries,
such as those providing sound. If this is not set, the code will
compile but disable support for such features. The arrangement of the
- SZGBIN: (optional) The directory where the built binaries
and shared libraries should be placed. If this is not set it defaults
to szg/bin/$(MACHINE_TYPE), where MACHINE_TYPE is one of linux, win32,
darwin, mips3, or mips4. The last two possibilities refer to SGI
- SZGDEBUG: (optional) If set to "TRUE", a debug build will
- SZG_LINKING: (optional) By default, the Syzygy makefiles are set up
to use dynamic linking, i.e. libraries are built as shared libraries
(dll's on Windows, so's on Linux, etc.) If this variable is set to STATIC,
the build process will create static libraries, and executables will
link the resulting libraries statically. This can be useful sometimes
for simplifying DLL management. To prevent a name conflict (on Win32
the DLL import/export libraries have the same .lib extension as static
libraries), the static libraries have different names, such as libarLanguage_static.lib
IMPORTANT NOTE: Using Visual C++ on Win32, there is a problem with
static linking. Because DLL's cannot link to a static libc, loadable
DLLs cannot be built with this option.
The Python bindings must be built as a DLL and cannot be built with
SZG_LINKING set to STATIC. The supported Unix-like platforms do not suffer from
New in Syzygy 1.2: You can now compile input device drivers and the
DeviceServer program with static linking. The device drivers are linked
directly into the DeviceServer executable instead of each comprising its
own shared library. Building the Python bindings with static linking enabled
appears to work with the MinGW g++ compiler.
New in Syzygy 1.3: The device drivers are built as dll's using MinGW
g++ on Win32.
The following environment variables only have meaning on
- SZG_STLPORT: Visual Studio 6's STL
implementation is insufficent to run Syzygy. In this case,
be used instead. It must be installed in the SZGEXTERNAL directory
(see Supporting Libraries) and
SZG_STLPORT must be set to TRUE.
- SZG_USE_PCH: (optional) To get the Windows build reasonably
fast, precompiled headers must be used (the default). However, these
are extremely sensitive to minor differences in Visual Studio patch
level. Sometimes it is convenient to be able to turn off
precompiled headers by setting this variable to "FALSE".
Compiling the Syzygy Libraries
Make sure you have followed the following specific guidelines
for your platform (if any):
- If using Visual Studio 6, you must install STLport as
and SZG_STLPORT must be set to "TRUE".
- If using Visual Studio .NET, do NOT use STLport.
SZG_STLPORT must be unset or "FALSE".
- Remember to set paths appropriately as outlined in
Syzygy Build Environment Variables.
- OS X: Because Syzygy depends on X11, you must have the
developer version installed on your machine.
- Irix: Be sure to use "gmake" instead of "make", since
Syzygy Makefiles follow the GNU syntax.
On all platforms, follow these general instructions.
- Unpack szg-1.3.[zip/tar.gz].
- You MUST set $SZGHOME appropriately and should optionally
set other variables (Syzygy Build Environment Variables).
- In szg/build, type "make". Note that "make clean" deletes
On Windows this must be done from a cygwin or MinGW
shell since syzygy uses GNU make (actually, any shell will
do provided the appropriate version of make.exe, compiler,
linker, and so on are on your application search path as
specified by the PATH environment variable. One of us
routinely uses IPython as a build
shell). On Irix, you MUST use "gmake" instead
of "make", since Syzygy uses GNU make syntax.
- If the supporting libraries are not properly installed (see
then Syzygy will build, but certain capabilities, such as sound, will
make process will build a collection of shared libraries that collectively
comprise the Syzygy toolkit (shown here with Linux/Irix extensions, replace '.so'
with '.dll' for Windows):
Alternatively, if you chose the static linking option, the
will look like (shown here with Linux/Irix extensions, replace '.a' with '.lib'
It will also compile a collection of plugins for the input
framework (e.g., input device drivers), infrastructure
programs like szgserver, and utility programs like dkillall. Remember,
in the special case of statically-linked Syzygy on Win32, your
input driver plugins will not work with
DeviceServer. However, static builds have no such drawback on supported
You can also build individual shared (or static) libraries,
which can be very convenient during development. To build the objects
derived from src/language, for example, run "make" (or "gmake" on
Irix) in the directory szg/build/$(MACHINE_TYPE)/language, where
MACHINE_TYPE is one of linux, win32, darwin, mips3, or mips4.
Compiling the Sample Applications in szg
Many example applications are included with the Syzygy code
(located in szg/src/demo).
- Set SZGHOME, SZGBIN, SZGEXTERNAL, etc. as before.
- To build all the samples, in szg/build type "make demo",
which will result in the executables being placed either in
szg/win/<MACHINE_TYPE> or in the directory pointed to by the
SZGBIN environment variable. The "demo" target also rebuilds
the libraries (i.e. does the equivalent of "make") if
needed. If one sample application fails to build, it continues to the
next. You can clean the demo directories with "make demo-clean".
You can also build demos individually. For
example, to build the
atlantis demo on Linux,
cd szg/build/linux/demo/atlantis; make. As above, for
this to work properly, the build environment variables must be set
Advanced Makefile Targets
- drivers: build only up to the drivers. Don't build anything
sound, or the application frameworks. This is useful when OpenGL is
missing. The drivers requires dynamic linking.
- install-shared: This is in every top level Makefile and in
Makefile.rules. It copies shared libraries into the binary directory
- bin-install: This target exists in every top level Makefile
and in Makefile.rules. It copies a project's compiled binaries and
libraries into the binary directory ($SZGBIN).
NOTE: Syzygy no longer supports precompiled SDK's.
- create-sdk: This is in every top level Makefile and also in
Makefile.rules (and consequently every low-level Makefile as well).
When invoked from a developer's install of the szg source, it creates
an SDK installation in $SZGHOME/szg-install. All executables and shared
libraries, including the external libraries, are copied into the bin subdirectory
and symbolic links are created there to deal with library sonames, as required.
In addition, documentation, header files, and some of the make infratsructure
are copied over. Elsewhere (like in py-szg or szgdemo), create-sdk just
causes locally produced binaries and libraries to be added to an
- clean-sdk: This is in the top-level Makefile of the
developer's version of szg only. Removes the working SDK
installation, if such exists (i.e. deletes $SZGHOME/szg-install).
- install-pch: This has meaning only when using the Windows version of
the SDK. By default, compiling with the SDK has precompiled headers turned
off, resulting in slower compilation on Windows. To use precompiled
headers to speed up compilation, invoke this
from the build directory of the SDK. Afterwards, turn on
precompiled headers by setting environment variable SZG_USE_PCH to
- clean-pch: This deletes the precompiled header file created
by the install-pch target.