Syzygy Documentation: Getting the Software
Integrated Systems Lab
01/05/2007
Documentation Table of Contents
Syzygy works on reasonably modern versions of
Linux, Windows, Mac OS X, and Irix. Every user should read the
testing document.
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
Python bindings.
Software Packages
The following software (and data) packages are part of the
Syzygy distribution:
Source Package
- szg-1.1.[zip/tar.gz]: Everything necessary to build and test the
library. Includes some example programs.
Also includes everything needed for writing Syzygy programs in Python.
Data Packages
- szgdata-1.1.[zip/tar.gz]: Data necessary for the sample
applications, as outlined in the example programs page,
but excluding some particularly large files, which are available by
request.
External Library Packages
(Note that one of these is required by each of the precompiled packages above).
- external-1.1-linux.tar.gz: External libraries and headers
used to produce the executables on Linux.
- external-1.1-win32.tar.gz: External libraries and headers
used to produce the executables on Win32.
- external-1.1-darwin.tar.gz: External libraries and headers
used to produce the executables on Mac OS X.
- external-1.1-sgi.tar.gz: External libraries and headers
used to produce the executables on Irix.
Development Template Packages
- szg_app_template-1.1.tar.gz: A cross-platform build structure
for C++ projects.
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.
Hopefully the GLUT dependency will be completely removed by version 1.2.
OS-Specific Build Instructions
Linux
- X11 and ncurses development packages are required for
compilation. Your distribution might not install these by default.
- GLUT is required for compilation as well. Either install a
GLUT development package via your distribution or install GLUT in
Syzygy's external build libraries, as described here.
- 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.vars. Experiment with either removing it or
downgrading, for instance to "-march=i586".
Windows
- 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 .NET without)
or the MinGW implementation of the GNU g++ compiler and linker.
Note that not all functionality is available when compiling
with g++ on Windows: You can't currently compile device drivers
or Python bindings, and speech synthesis and .3ds file support are
also unavailable. However, we can supply you with precompiled binaries of
the device drivers, Python bindings, and SoundRender for speech
synthesis in Cluster Mode.
- 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
self-contained installers.
- 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[0], 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
other checkboxes):
- Category: Base
-
ash bash cygwin fileutils login sh-utils
- Category: Devel
-
bin-utils make
- 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
details.
- 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
- make
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.
Irix
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:
SZGHOME=D:/szg
SZGEXTERNAL=g:/public
The following environment variables are meaningful on all
systems:
- SZGHOME: (required) The top-level syzygy directory (for
example, /home/user1/szg).
- 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
processor families.
- SZGDEBUG: (optional) If set to "TRUE", a debug build will
be produced.
- 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
on Win32.
IMPORTANT NOTE: On Win32, there is a problem with
static linking. Because DLL's cannot link to a static libc, loadable
DLLs (like Syzygy input device drivers) will NOT work with this option.
Consequently, DeviceServer will not work. Similarly, the Python
bindings (on Win32) 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
this problem.
- SZG_DEVELOPER_STYLE: (optional, and no longer supported) If set to "EASY", the build
assumes that the Syzygy headers and libraries are arranged as in one of
the precompiled binary distributions, such as szg-0.8-linux.tar.gz. See
this chapter for
further information. Please note, by default the code assumes that the
Syzygy headers and libraries are arranged as in the "developer" version
(szg-0.8.tar.gz) you compile yourself.
The following environment variables only have meaning on
Windows.
- SZG_STLPORT: Visual Studio 6's STL
implementation is insufficent to run Syzygy. In this case,
STLport must
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):
- Windows
- If using Visual Studio 6, you must install STLport as
outlined here,
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.1.[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
previously-built libraries.
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
Supporting Libraries),
then Syzygy will build, but certain capabilities, such as sound, will
be disabled.
Potential problems
Generated Files
The 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):
- libarLanguage.so
- libarPhleet.so
- libarBarrier.so
- libarMath.so
- libarDrivers.so
- libarGraphics.so
- libarSound.so
- libarObject.so
- libarInteraction.so
- libarFramework.so
Alternatively, if you chose the static linking option, the
built libraries
will look like (shown here with Linux/Irix extensions, replace '.a' with '.lib'
for Windows):
- libarLanguage_static.a
- libarPhleet_static.a
- libarBarrier_static.a
- libarMath_static.a
- libarDrivers_static.a
- libarGraphics_static.a
- libarSound_static.a
- libarObject_static.a
- libarInteraction_static.a
- libarFramework_static.a
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
Unix-like platforms.
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).
- atlantis
- coaster
- cosmos
- cubes
- hspace
- parade
- ribbons
- schprel
- Make sure that SZGHOME, SZGBIN, SZGEXTERNAL, etc. are
set 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".
It is also possible to build the demos individually. For
example, to build the "cosmos" demo on a Linux machine, go to
szg/build/linux/demo/cosmos
and invoke "make". As above, for this to work properly, the build
environment variables must be set appropriately.
Advanced Makefile Targets
Some more Makefile targets can be useful.
circumstances. These create an installable SDK
and manage the external shared libraries.
- drivers: build only up to the drivers. Don't build anything
involving graphics,
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
(i.e. $SZGBIN).
- 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: We no longer support any precompiled SDK's. These targets may
work, but there are no guarantees.
- 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
existing $SZGHOME/szg-install.
- 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
TRUE.
- clean-pch: This deletes the precompiled header file created
by the install-pch target.
|
