GLUT/Tk Installation

Context:	TOC -> GLUT/Tk Overview -> Installation
Related:	Installation, Application Programming Interface, Application Development
Details:	Registration, GLUT/Tk Download, Resources Download

GLUT/Tk Installation

GLUT/Tk is distributed as source code and executables for some common platforms, i.e., Windows, Linux, Solaris, and IRIX. Please register so that we can inform you of important bug fixes or feature enhancements.

Executable Installation

Windows

Software Requirements:

Microsoft Windows 95, 98, ME, NT, 2000, or XP
Tcl/Tk (version 8.x, where x > 1)
SpaceWare (3dxware) spaceball driver, if using spaceball

Installation Procedure:

Download the GLUT/Tk Windows executable distribution and execute it.
To test your installation, provided you selected to install the sample program, activate the "Start" menu, select "Programs," select "gluttk," and run the sample program "Platonics." This should open three windows, a console window containing some informative text (probably behind the other windows), a GLUT graphics window displaying a green octahedron inside a white spherical grid on a black background, and a Tk control window containing yellow, blue, and red buttons on a grey background.
You can use the header "include\GL\glut.h" and library stub "lib\libgluttk32.a" files where they are, in "C:\Program Files\gluttk" or whatever directory you selected, by compiling and linking with the appropriate options, or copy them to the "include\GL" and "lib" subdirectories of a standard location, like "C:\cygwin\usr."
For more information, if you selected to install the documentation, activate the "Start" menu, select "Programs," select "gluttk," and open "Documentation." This should open the documentation in your default web browser.

The installation program installs the GLUT/Tk Tcl module where your other Tcl modules are, usually "C:\Program Files\Tcl\lib" or "C:\Tcl\lib," based on the location of Tcl specifed in the registry (in "HKEY_CLASSES_ROOT" either "TclScript\shell\open\command" or "ActiveTclScript\shell\open\command"). If one of these values is not set, GLUT/Tk will fail to install. In that case, use "regedit.exe" to create the required keys and a default string value consisting of the quoted location of your Tk interpreter, followed by the parameters, e.g., "C:\Tcl\bin\wish83.exe" "%1" "%*". View this screen shot to see how it should look.

Unix

Software Requirements:

IRIX 6.5, Linux (ELF), or Solaris 8
The X Window System
Tcl/Tk (version 8.x, where x > 1)
GNU zip
SpaceWare (xdriver) spaceball driver, if using spaceball

Installation Procedure:

Select a location for GLUT/Tk. The "gluttk" directory, created in the next step, needs to be in the Tcl auto path so that the Tcl package system can find and load the "gluttk" extension. You have two options:
1. Put GLUT/Tk in the default location where Tcl looks for subdirectories containing Tcl modules. Usually only the superuser (root) can do this. This location is typically the "lib" sibling of the "bin" directory containing the Tk 8.x shell "wish" or "wish8.2," "wish8.3", etc., and it contains the file "tclConfig.sh." It might be "/usr/local/lib," "/usr/lib," or something completely different.
2. Add the location containing the "gluttk" directory to "TCLLIBPATH," which Tcl searches in addition to the default location described above. The last component of the directory name, i.e., "gluttk," can be omitted because TCL searches one level of subdirectories. For example, if GLUT/Tk is in "/home/self/graphics/gluttk," then a POSIX shell (/bin/sh, ksh, bash, ash) user might execute "TCLLIBPATH=/home/self/graphics; export TCLLIBPATH", and a C-shell (/bin/csh, tcsh) user might use "setenv TCLLIBPATH /home/self/graphics" (no '=' for csh). If multiple directories are included in the path, they must be separated by spaces, not colons or semicolons. The spaces must be escaped to hide them from the shell, e.g., "setenv /usr/local/lib\ /home/self/graphics".

Download the appropriate GLUT/Tk tarball (compressed tar file) for Unix executables and crack it open in the selected location. For example, user "self" on an SGI might save the tarball as "/home/self/gluttk-irix.tar.gz", then

   cd /home/self/graphics  # an existing directory
   gzip -dc /home/self/gluttk-irix.tar.gz | tar xvf -

This will create the following directory structure in /home/self/graphics:

gluttk
   pkgIndex.tcl         : tcl package index
   gluttk-tclmod1.0.so  : tcl dynamic module
   docs                 : html documentation
      [various files]
   include
      GL
         glut.h         : gluttk header file
   lib
      libglut.a         : gluttk library file
   example
      ctl.tk            : example program tk script
      platonics         : example program executable
      platonics.c       : example program source code, incomplete

Test your installation by running "wish" interactively and entering the Tcl command "package require gluttk". It should complain "{Cannot read OpenGL window ID from first argument}". Then type "exit" to exit "wish." If you get an error message that includes "Application initialization failed: invalid command name "tcl_findLibrary"" then you might need to remove the envronment variable TCL_LIBRARY, pointing to an obsolete Tcl 7.x library, e.g., "unsetenv TCL_LIBRARY" or "unset TCL_LIBRARY".
If desired, try executing the example program "platonics". You might need to correct the location of the "wish" Tk interpreter in the first line of "ctl.tk." This line should begin with "#!" and contain the full pathname of the "wish" interpreter, which can usually be found with the command "which wish".
To make it easier to compile and link GLUT/Tk programs, you might want to move "glut.h" into a subdirectory named "GL" in the directory where you keep your header files, e.g., "/usr/local/include/GL," and move "glut.a" to where you keep your static libraries, e.g., "/usr/local/lib."

Source Code Installation

The process of installing the source code and building the executables is similar on Unix and Windows. Differences are noted where they occur. Windows users are encouraged to use the Cygwin shell, which automatically converts the forward slashes in these instructions into the backward slashes appropriate for Windows.

Software Requirements:

Unix or Windows
GLUT 3.7 source code
patch (This is probably already installed on a Unix system, and on Windows it comes with Cygwin.)
Tcl/Tk (version 8.x, where x > 1) If are using Tcl/Tk 8.4a1, you need to upgrade to 8.4a2 or higher because it is missing tkPlatDecls.h.
SpaceWare (3dxware or xdriver) spaceball driver (if using spaceball)
SpaceWare (3dxware) SDK (if using spaceball in Windows)
Cygwin (if using Windows)
GNU Zip(provided by Cygwin for Windows)
GNU Make (provided by Cygwin for Windows)
GCC or another ANSI C compiler (provided by Cygwin for Windows, we have not tried MSVC)
To build the example, you also need our local collection of subroutine libraries that we call "Resources".

We have built and tested GLUT/Tk on Windows 98 and 2000, RedHat Linux 7.2, Solaris 8, and IRIX 6.5. We used current or nearly current versions, as of January 2002, of all the open source and free software. GLUT/Tk should work on a variety of other Windows and Unix systems, perhaps requiring minor changes.

The GLUT/Tk source code has two main components and one example application, which are all built separately:

GLUT, with a few new functions added for creating and communicating with a Tcl process, and support for the SpaceWare spaceball drivers (in addition to the xinput support already in GLUT).
A Tcl module containing functions for communicating with a GLUT process.
Platonics, an example program that draws, translates, zooms, and rotates the five platonic solids in a GLUT window, with a Tcl window that provides controls to select a shape, mouse mode, spaceball sensitivity, etc.
There is a fourth part, the "resources" libraries. They are built automatically along with the example program, which uses them.

Directory structure

The directory resulting from unpacking the source code has the following structure (where "graphics" is an arbitrary parent node):

graphics
   gluttk
      docs             : documentation
      glut-3.7         : this sub-tree contains the modified GLUT
         ...             source code and/or executables.  Note
                         especially lib/glut/libglut.a, which contains
                         the basic executable library for GLUT.
      source.diff      : modifications to GLUT source code
      tcl              : tcl module source and object files
      example          : files for example application
         libpl         : application-specific subroutines
   resources           : other subroutines needed for example program
      ogl              : OpenGL utility routines
      geom             : geometry utility routines
      ...              : other utility routines that the example does not use

Building

Download the GLUT/Tk compressed tar file for source code and untar it, in order to build most of the directory tree described above, e.g.
```
   cd /home/self/graphics
   gzip -dc gluttk-source.tar.gz | tar xvf -
```
If you want to build the example program, download "Resources", and untar it in the same place as gluttk-source.tar.gz, e.g.,
```
  gzip -dc resources.tar.gz | tar xvf -
```
Download the standard source code for GLUT itself (see http://www.opengl.org/developers/documentation/glut/index.html#2), and untar it to create the "glut-3.7" sub-tree, e.g.,
```
   cd gluttk
   gzip -dc glut-3.7.tar.gz | tar xvf -     # or unzip glut37.zip
```
Modify GLUT source code, as indicated in the patch file gluttk/source.diff, i.e.,
```
   patch -p0 < source.diff
```
Run the version of "mkmkfiles" appropriate for your system, unless you are using IRIX, where we have had better results using "mkmkfiles.imake" instead of "mkmkfiles.sgi." GLUT comes with three, and the patch above adds "mkmkfiles.cygwin" for compiling with the GCC compiler that comes with Cygwin. (We have not tested GLUT/Tk with Microsoft Visual C.) Refer to the GLUT "README" files for more details. E.g.,
```
   cd glut-3.7
   ./mkmkfiles.cygwin
```
Modify the configuration as needed.

Windows

Modify "glutcygwin.mak" as needed. Make sure the location of the Microsoft Platform SDK is correct. If you have the spaceball driver and SDK installed and you want to compile in spaceball support, uncomment "#USE_SPACEBALL=1" by removing the '#', and verify the locations of the spaceball files. GLUT/Tk will still work when there is no spaceball.

Unix

If you have the Spaceware driver installed and would like to compile in spaceball support, look in glut-3.7/lib/glut/Makefile for the line that defines CFLAGS, which starts with "CFLAGS =" and insert "-DUSE_SPACEWARE". GLUT/Tk will still work when there is no spaceball.
Run make to create the modified GLUT library. You may get a few warnings, and some of the GLUT sample applications might fail to compile or link, but the important thing for GLUT is that everything in "glut-3.7/lib/glut" is made without errors. You can use "make -k," if desired, to continue past any errors in the sample applications to make the rest of them.

Windows

If the compiler or linker can't find some of the header or library files they need, verify that you completed the previous step correctly.
Install the modified GLUT/Tk header and library files in appropriate library and header directories.

Windows

This was done automatically by the previous step, unless it failed. It copied "lib/glut/gluttk32.dll" to your Windows system directory, either "C:/windows/system" or "C:/winnt/system32," and copied the header and library files to the Cygwin directories "/usr/include/GL" and "/usr/lib."

Unix

You can use the header (glut-3.7/include/GL/glut.h) and library (glut-3.7/lib/glut/libglut.a) files where they are, with the appropriate compiler and linker options, or copy them to the "include/GL" and "lib" subdirectories of a standard location, like "/usr/local" or even "/usr" on some Linux systems.
Generate and install the Tcl module. This is done differently depending on whether you are using Windows or Unix.
Windows
Make the Cygwin makefile the default by copying "Makefile.cygwin" to "Makefile." Use "make" to compile and install the Tcl module. It tries to find the Microsoft Platform SDK, and Tcl/Tk, and tries to extract the Tcl minor version number from tclConfig.sh. If it fails, you might need to edit "Makefile" to help it find the MSPSDK or Tcl/Tk.
```
   cd ../tcl
   cp Makefile.cygwin Makefile
   make
   make install
```
Unix
Configure, build, and install the Tcl module, gluttk-tclmod1.0.so. If "configure" fails, you might need to specify options, like "--enable-gcc," or "--with-tclinclude=..." Type "./configure --help" for a complete list of options and brief descriptions. You may need to be root in order to install the module. E.g.,
```
   cd ../tcl
   ./configure
   make
   su
   make install
```
Try compiling and executing the example program in the gluttk/example directory.
Windows
Make the Cygwin makefile the default by copying "Makefile.cygwin" to "Makefile." Use "make" to compile and install the Tcl module. If it fails, you might need to edit "Makefile" to help it find the Microsoft Platform SDK.
```
   cd ../example
   cp Makefile.cygwin Makefile
   make
```
Unix
Make the Unix makefile the default by copying "Makefile.unix" to "Makefile". This makefile is for Unix systems using GNU make and GCC. You need to modify it if you want to use another compiler, and you might need to rewrite it to use a different make.
```
   cd ../example
   cp Makefile.unix Makefile
   make
```

Back to GLUT/Tk Home

Page last modified: 12 February 2003