The purpose of this file is to fully document the installation

procedure for VPython from source on all supported platforms.

Table of Contents:

I: Prerequisites

II: Configuration

III: Building

IV: Final Installation

V: Troubleshooting

I. Prerequisites:

Most or all of these may be provided by your operating system

distributor. In every case, you must have the "developer" version

of the packages to ensure that the required header files are

available.

See the file MSWINDOWS.txt for details on how to build Visual on Windows.

This file is maintained in CVS at sourceforge.

GNU g++ version 3.2.x or >= 3.3.1 (3.4.6 reccomended) (gcc.gnu.org).

Python 2.2.x or 2.3.x or 2.4.x or 2.5.x (www.python.org), including

the development (dev) package.

numpy (numpy.sourceforge.net).

An implementation of OpenGL.

The Boost C++ libraries version 1.31 and higher (1.33.1 reccomended)

(www.boost.org). Note that 1.31 is required if you are using Python

2.3 or higher, and is recommended in any case due to getting much

better error messages. 1.32.0 or higher is required if you want to use

GNU G++ 3.4.0 or higher to build the suite.

Specifically, you need libboost-python-dev and libboost-threads-dev.

The autoconf, automake, libtool, and pkg-config packages.

gtkmm (www.gtkmm.org), which depends on gtk2 (www.gtk.org)

gtkglext and gtkglextmm 1.2.x (gtkglext.sourceforge.net).

To install gtkglextmm:

1) Download the bz2 file.

2) Unpack the file: tar -xjf gtkglextmm-1.2.0.tar.bz2

3) cd to the unpacked directory

4) ./configure

5) make

6) sudo make install

libglademm (there may be a package, or www.gtkmm.org).

Apple OSX (Version 10.2.x) WARNING: This is woefully out of date

- Go to www.apple.com/macosx/features/x11/download and download

both X11 and the X11 SDK.

- Install fink from fink.sourceforge.net. Answer 'y' when asked

about adding a line to ~/.cshrc. You do not need to run

'dselect'.

- In a terminal editor run the following:

rehash

sudo apt-get update

sudo apt-get install pkgconfig gtk+ gtkglarea python22

rehash

which python2.2 (Verify this reports /sw/bin/python2.2)

Install GCC from source using version 3.3.1 or higher. First

install the Apple Developer's Tools (called XCode in 10.3)

including an installation of GCC 3.3. Download and unpack

the sources for GCC from gcc.gnu.org. This creates a directory

named like 'gcc-3.3.3'. Make a new directory alongside this

directory, such as 'buildgcc3.3.3'. cd into the new directory and

run:

`../gcc-3.3.3/configure --enable-languages=c,c++ --disable-shared \

--enable-version-specific-runtime-libs --program-suffix=-3.3.3 \

--enable-threads=posix`

Build the new compiler with `make bootstrap`. Optionally, to save

some disk space, build with `make CXXFLAGS=-O2`, instead.

install the compiler with `sudo make install`

Download

OpenGL is provided with the standard OS installation.

# TODO: include directions for building Boost.Python on OSX(gulp).

II. Configuration

On most systems, configuration should be automatic. Just run './configure'.

However, configure also provides a large number of options and is sensitive to

several environment variables to properly configure VPython for unique use cases.

Additionally, it is a good idea to build VPython in a directory separate from the

source tree. Just run configure with the fully-qualified path to it, eg (from a

directory alongside visual-2.9) `../visual-2.9/configure`

Run `configure --help` for the complete list of options and brief descriptions.

If you have multiple versions of Python installed, and the one named 'python' that

is first on your PATH (identified with `which python`) is not the one you want to

build Visual for, specify the correct interpreter by setting the PYTHON

environment variable to the desired interpreter's full path.

If you have multiple versions of GNU G++ installed, and the default is inadequate

for VPython, specify the correct one by setting the CXX environment variable to

its fully-qualified path.

If you are using G++ 3.3.x on Darwin, you must set the CXXFLAGS environment

variable to include "-finline-functions". You should also include "-O2". All of

these options must be separated by whitespace.

You should generally supply the --prefix option to cause Visual to be installed to

the same prefix that Python is installed (default is /usr/local).

On Linux, do this: which python

Make a note of the prefix preceding /bin/python, typically /usr or /usr/local.

(a) If prefix is /usr/local, execute

../visual-x.x.x/configure

(b) If prefix is something else, and Visual can go into prefix/lib/python/site-packages, execute

../visual-x.x.x/configure --prefix=prefix

or (b) is not appropriate, specify both the particular Python and where to install Visual:

PYTHON=/somewhere1/bin/python ../visual-x.x.x/configure --prefix=/somewhere2

If "somewhere1" and "somewhere2" are different, you must also add the "somewhere2"

directory to Python's module search path. For details, at www.python.org read section 4.1

(Modifying Python's Search Path) in the section Installing Python Modules of the Python

on-line documentation.

If you are only building VPython once, you may pass the option

--disable-dependancy-tracking to make the build itself go a little faster.

If your GNOME libraries are installed in a non-standard location (such as

/sw in OSX fink, or /opt/gnome in SUSE), you must set the CPPFLAGS

environment variable to -I/other_prefix/include to ensure that you pick up

the gtkglarea header files.

Compling a prebuilt binary for MS Windows is configured with (in MSYS):

PYTHON=/c/Python25/python.exe CXXFLAGS="-O2 -march=i686" ./configure

NOTE: The variable MSC_VER is apparently set only by the Visual Studio

build procedure created by Arthur Siegel in early 2007 but not currently used.

The prebuilt binary for Apple OSX is configured with (in Bash):

CXX=/usr/local/bin/g++-3.3.3 CXXFLAGS="-O2 -finline-functions" \

PYTHON=/sw/bin/python CPPFLAGS=-I/sw/include ../visual-2.9/configure \

--prefix=/sw

Another interesting configuration is to install VPython into a prefix other than

the same prefix that Python is installed in. This may be useful to test your

VPython programs with different versions of Visual on the same system

simultaneously. After choosing an approprate prefix, such as /home/jonathan, run

configure as normally but specify the PYTHONPATH environment variable to be

[prefix]/lib/python2.5/site-packages, replacing python2.5 with python2.2 if that

is your interpreter. You must create this PYTHONPATH directory if it does not

already exist.

III. Build

Just run 'make'.

Optionally, you may override the following variables by

specifying them in the form VARIABLE=value as arguments to make:

LDFLAGS, LIBS, CXXFLAGS, and CPPFLAGS affect options passed to the linker,

compiler, and preprocessor, respectively.

DESTDIR may be used to prepend DESTDIR to the 'prefix' specified when running

configure. This option is mostly useful to binary redistributors of VPython.

If you want debugging symbols in your build (adds roughly 70 MB of data to the

final object file), you must manually edit cvisual/Makefile and remove `-g0` from

the CXXFLAGS variable.

The Makefiles support the following targets:

all: (the default) compiles all the required software

clean: deletes files created by the compiler

distclean: deletes all files created by the configure and make programs. This

option is useful if you want to start over from a clean source tree.

install: copies all required files in the locations specified by configure

install-strip: Performs the 'install' target and strips the final object files.

It also makes getting a backtrace impossible on most platforms.

IV. Install

You must have write privileges to the installation directory to proceed. Unless

you are installing into your home directory, that generally means becoming root

with a program like `sudo` or `su`. Just run `sudo make install`.

On MS Windows, you CANNOT use "make install".

Instead, you need to install innosetup (www.jrsoftware.org/isinfo.php).

1) Make sure that C:\Python25\Lib\idlelib\config-main.def has edit startup and

autosave set to 1 and that help is set for Visual before building the package.

2) Double-click MakeVPython.iss in the make directory.

3) Near the start of the file, update AppVerName if necessary.

4) Do Build > Compile to produce a Windows installer.

5) Run the installer, then run compilevisual.py from the Visual source package to

Python-compile all the Visual .py files (produces .pyc files).

6) Run inno setup again, but uncomment the line that copies .pyc files.

This produces a Windows installer that can be used by an administrator to

install a fully-compiled Visual into a protected area that users can't write

to. Without this second inno setup to get the .pyc files, every user would

have to recompile some of the site-packages/visual/*.py files. No big deal,

but nicer to have these files already compiled.

Alternatively, you may run 'make install-strip' to install a somewhat smaller

executable.

V: Troubleshooting

The single most likely cause of an error in the build is that one or more

develoment header files could not be found. VPython logs its configuration stage

in config.log, and its build stage in src/build.log. If the build fails you

must read src/build.log to see what happened. In the event that you cannot

solve the problem, compress config.log and src/build.log and include them with

your request for assistance to visualpython-users@lists.sourceforge.net.

But before you do that, it is a good idea to read the archives of the mailing list

since someone else has probably worked through your problem already.