Beckman Institute            University of Illinois at Urbana-Champaign             

Documentation Table of Contents

• Notes for Windows Users
• Environment Variables
• Using the Build Template
• Include-file hints

Notes for Windows Users

Windows users need to take some extra care in compiling their programs.

• If you are using Visual Studio 6 on Windows, you must compile with STLport (SZG_STLPORT=TRUE). Using STLport is described in Supporting Libraries. On the other hand, do not use STLport with Visual Studio .NET (its native standard template library is OK).
• Another note for Windows users, you must set up your environment variables so that the Visual Studio compiler (cl.exe) and the Visual Studio linker (link.exe) are on your path and can find their header files. There's an option to set these environment variables when you install Visual Studio. If it's too late for that, the proper way to set this is via the Windows control panel. Please note that, after setting the variables in the control panel, you will have to restart your cygwin or MinGW shell in order to access the new values there. The proper values for the environment variables are outlined in the Visual Studio Environment Variables section.
• If you are using the precompiled SDK for Windows, you must use the same SDK as your compiler (-vc6 for Visual Studio 6 and -vc7 for Visual Studio .NET). If you mix versions, your executables either will not link or will crash on startup. No longer supported
• If you are compiling using cygwin on Windows then there can be a problem. The Visual Studio linker is called "link" and some installs of cygwin may also install a "link" program. If, during your build, you see an error message like:

      link error: too many arguments
  

  You will know you are getting the cygwin "link" program by mistake. You can solve this problem by typing "which link", seeing where the cygwin "link" resides, and removing it, or you can make sure your PATH environment variable has the Visual Studio program in it first.

Environment Variables

A number of environment variables control the build process.

• SZGHOME: The top level directory of your distribution. This MUST be defined.
• SZGBIN:
  • If $SZGBIN is defined, then this is used as the directory for Syzygy executables and shared libraries that you compile.
  • If $SZGBIN is not defined, there are two possibilities, depending upon whether or not the developer style is "EASY".
    • If SZG_DEVELOPER_STYLE=EASY, then your executables and shared libraries will be placed in $(SZGHOME)/bin. No longer supported
    • Otherwise, you are assumed to have a "developer" version of Syzygy and your executables will be placed in $(SZGHOME)/bin/$(MACHINE_DIR), where $(MACHINE_DIR) is one of darwin, linux, mips4, or win32.

• SZGEXTERNAL: The location of any external libraries used. Optional if GLUT is preinstalled. See this section.
• SZG_LINKING: Controls whether libraries are built as dynamic (shared) libraries or static. Must be either 'DYNAMIC' or 'STATIC' (defaults to 'DYNAMIC'). If DYNAMIC, then the Syzygy libraries will be built as a set of shared libraries (.dlls on Windows, .so files on Unix) that applications load at runtime. If STATIC, the libraries are linked into each executable at build time. The latter creates larger files but much less of a version-control headache. Note that the input device drivers and Python bindings can only be built with this set to DYNAMIC, and that STATIC is the only option when compiling with MinGW g++ on Windows.
• SZG_COMPILER: Currently effective only on Windows. Must be 'VC6' (Visual C++ 6, the default), 'VC7' (Visual C++ 7), or 'MINGW' (MinGW g++).
• SZGDEBUG: By default, executables and shared libraries are built without debugging information. If you want to debug, set this to TRUE.
• SZG_STLPORT: This is only used on Windows. If you are using Visual Studio 6, you must set this to TRUE (and have the STLPort headers in your SZGEXTERNAL directory). If you are using Visual Studio 7 (.NET), then you must set this to FALSE.
• SZG_DEVELOPER_STYLE: By default, the system assumes you are using software compiled by you from a szg source distribution. To use a precompiled SDK, this must be set to EASY. Not currently supported

Using the Build Template

Syzygy has a build system designed for writing cross-platform applications, hiding the differences from the programmer. If your build directory is simultaneously mounted on different platforms, you can compile both versions of your code at once.

The directory szg/skeleton represents a build template for your applications. Copy and re-name that entire directory as you like. The source files go in skeleton/src. Modify skeleton/build/makefiles/Makefile.my_app to specify what gets built. After you've set things up, typing 'make' in the top-level directory will build your application (assuming you've compiled the Syzygy libraries first, of course). Typing 'make clean' in the same place will remove built executables and object files. The compiled executable will end up in skeleton/build/<platform> (e.g. skeleton/build/win32 on Windows) and in the directory pointed to by the SZGBIN environment variable. If SZGBIN is not set, $SZGHOME/bin/<platform> will be used.

The contents of szg/skeleton:

• szg/skeleton/Makefile: The overall Makefile for the template project. Scans the host to determine the platform and then executes the appropriate machine-specific Makefile.
• szg/skeleton/src: Your source code goes here. It contains two versions of a simple master/slave program (see the Programming chapter): skeleton.cpp uses the old method of installing event callback functions, oopskel.cpp achieves exactly the same behavior by sub-classing the arMasterSlaveFramework class and overriding callback methods.
• szg/skeleton/build/makefiles/Makefile.my_app: This is the fill you will edit to create your project. It's heavily commented, so in most cases it shouldn't be too hard to figure out how you need to modify it.
• szg/skeleton/build/darwin: Contains the Mac OS X Makefile and OS X objects. The machine-specific Makefile just sets the machine type and then includes the cross-platform Makefile.my_app.
• szg/skeleton/build/linux: Linux objects.
• szg/skeleton/build/mips4: Irix objects.
• szg/skeleton/build/win32: Windows objects.

Include-file hints

• Because Windows uses precompiled headers for speed, the first non-comment line in every .cpp file must be:

      #include "arPrecompiled.h"
  

  On Unix this does nothing. On Windows, omitting this causes compile errors.

• Within the Syzygy core, the last Syzygy include file in, say, drivers/*.cpp must be:

      #include "arDriversCalling.h"
  

• Instead of platform-dependent OpenGL includes, do:

      #include "arGraphicsHeader.h"
  

  and if you want to use the GLUT rendering functions (e.g. glutSolidCube()):

      #include "arGlut.h"
  

• Each syzygy core class must be declared SZG_CALL. The exception is classes entirely contained within a .h file: no SZG_CALL for them, because that confuses Windows' linker.

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