MAC-OSX.txt

HOW TO BUILD VISUAL USING CARBON
Install XcodeTools from the optional materials on the Mac installation DVD.
Installing XcodeTools automatically installs the large number of individual
components also listed on the DVD.

Install a 32-bit Python for the Mac ("MacPython") from python.org.
There is already a /usr/bin/python that at the moment is up to date, but
because this isn't always the case, and because the Python community seems to
strongly prefer it, we will base Visual on MacPython, which is /usr/local/bin/python.

VPython for the Mac is based on the Carbon framework because it proved impossible
to use Cocoa, due to threading issues. Unfortunately, Carbon is not supported
for 64-bit applications, so if and when no 32-bit version of Python is available
it may be necessary to revert to a Unix/X-windows solution, with the disadvantage
of not having the standard Mac look and feel.

CREATING A VPYTHON INSTALLER
See the information in src/mac/PackageMaker/packaging.txt

PYTHON INSTALLERS
The standard Python installers at python.org for the Mac install into
   /Library/Frameworks/Python.framework/Versions/

For Python 2.x, the installer modified .profile to add the newly installed Python
to the application search PATH. The installer also added or changed a link
   /Library/Frameworks/Python.framework/Versions/Current
to point to the newly installed Python. However, the Python 3.x installer does
NOT modify .profile or Current.

For the makefile to pick out the correct Python framework in building Visual, you need
to create or modify /Library/Frameworks/Python.framework/Versions/Current. Assume
that the new Python is in /Library/Frameworks/Python.framework/Versions/3.1:
   cd /Library/Frameworks/Python.framework/Versions
   (if necessary, "sudo rm Current" if there already is one)
   sudo ln -s 3.1 Current

INSTALLING MODULES NEEDED BY VISUAL
Next you need to install numpy. You may find an installer for it. Otherwise:
Download the source for numpy and unpack it (http://www.scipy.org/Download).
In the numpy directory, execute "sudo python setup.py install".
This installs the numpy module which includes needed header files.

You need to copy into /Library/Frameworks/Python.framework/Versions/X.Y/lib/pythonX.Y/site-packages
the git folders vis, visual, and vidle from the git site-packages folder. If you're building for
Python 3.x, copy vidle3 to vidle.

For Visual 5.3 and later, you need the Python modules FontTools, ttfquery, and Polygon.
Be sure to get ttfquery 1.0.4 or later.
Polygon is available at http://polygon.origo.ethz.ch/download
Currently, use the Polygon 2.0.1 binary for Python 2.6, which works with Python 27;
I have not succeeded in building Polygon from source. Nor did I succeed with Python 3.1
but got a Mac binary from the Polygon maintainer Joerg Raedler <joerf@j-raedler.de>.
This also works with Python 3.2.
	
Note The following copyright notice applies to the Polygon module when included in
the VPython distribution concerning Polygon:

"This distribution contains code from the GPC Library, and/or code 
resulting from the use of the GPC Library. This usage has been 
authorized by The University of Manchester, on the understanding 
that the GPC-related features are used only in the context of this 
distribution. It is not permitted to extract the GPC code from the 
distribution as the basis for commercial exploitation, unless a 
GPC Commercial Use Licence is obtained from The University of 
Manchester, contact: http://www.cs.man.ac.uk/~toby/gpc/".

BUILD VISUAL
Copy into 

You need Boost libraries for the Mac. See below for how to build the Boost libraries.

In src/mac, execute sudo make setup.
This creates a build directory mbuild parallel to the git files.

In the mbuild directory, execute "sudo make" to build Visual.
This creates cvisual.so. To install it, run "sudo make install".

In site-packages/vidle, you can execute "python MacBuildApp.py build" to build an app to drive VIDLE,
an updated alternative to the IDLE shipped with Python. However, the resulting launcher seems
to be not very robust and the resulting launcher has been modified and is found in
src/mac/PackageMaker/VIDLE_launcher.zip. 
For more details, see src/mac/PackageMaker/packaging.txt.

Run compilevisual.py (top of git files) to compile all Visual Python files.

Another option to compile all of the .py files in a directory is this:
	import compileall
	compileall.compile_dir("mylib", force=1)

CREATE INSTALLER
In src/mac/PackageMaker is an Apple PackageMaker project file, a Welcome text file
for creating a VPython installer for the Mac, and instructions in packaging.txt.

Be sure to set the project status to require OSX 10.4 and above.

BUILDING BOOST LIBRARIES
The Boost libraries were built by downloading the source.

Be sure to set up the link /Library/Frameworks/Python.framework/Versions/Current as discussed
above before attempting to build the Boost libraries.

The Python 3.2 installer places the Python includes in
/Library/Frameworks/Python.framework/Versions/3.2/include/python3.2m instead of ....python3.2.
This leads to a failure in building the Boost libraries. You need to make a copy of
include/python3.2m -> include/python3.2 in order for the following procedure to work.

cd to the Boost directory and execute
./bootstrap.sh --with-toolset=gcc --with-python-version=3.2 --with-python-root=/Library/Frameworks/Python.framework/Versions/3.2 --with-python=python3.2 --with-libraries=python,signals,thread

to create the bjam tool and project-config.jam.

Run the new python in a terminal and see what compiler was used to build it. If it was 4.0, do this:
   In the file project-config.jam, change "using gcc ;" to "using gcc : 4.0 : g++-4.0 ;"
If it was 4.2, do this:
   In the file project-config.jam, change "using gcc ;" to "using gcc : 4.2 : g++-4.2 ;"
The purpose is to build Boost libraries using the same compiler used to build Python and Visual.
Early versions of Python distributed at python.org used 4.0, later ones 4.2. 

Now execute ./bjam to build the Boost libraries for 32-bit Python.

The files you want will be in stage/lib. Move the following files to  dependencies/boost_files/mac_libs:
libboost_python.a
libboost_signals.a
libboost_thread.a
Also move the boost folder to dependencies/boost_files/boost

(Note that address-model=32 architecture=x86 instruction-set=i386 can be used with bjam to force 32-bit compilation.)

Up to and including Python3.1, the Python executoable was built for ppc and i386.

------------------------------------------------------
Obsolete, of historical interest only: HOW TO BUILD VISUAL 4 ON Apple OSX using GTK2 (Version 10.4.x)

If you find gaps in this information, please tell Bruce_Sherwood@ncsu.edu.

Make sure X11 and Xcode are installed (found on the installation DVD).
X11 is automatically installed on 10.5.
	
To do a clean install of fink (www.finkproject.org), I deleted /sw and started from scratch.
Install fink from fink.sourceforge.net. Probably best to install from source?
I use Fink Commander as a GUI to fink, but you can use the command line.

Create a file in your home directory named ".profile" with these contents:
test -r /sw/bin/init.sh && . /sw/bin/init.sh

Start up a new terminal program, which will read the .profile file with the effect that
/sw/bin will be on your application search path.
	
Use fink to install the components listed for Linux in INSTALL.txt (details repeated here).
	
	If you're not using Fink Commander (and despite its graphic user interface there are
	hints that maybe it is buggy), on a command line you say for example "fink install python25".
	
	Execute fink selfupdate to get the latest packages. (You may need to invoke /sw/bin/fink.)
	
	Install numpy-py25, which also installs python25.
	(2008/4/2 on OSX 10.5; accepted the choice "db44-aes-shlibs: Shared Libraries for db44-aes")

	Currently (Jan. 2008) you will find 10 entries for Boost libraries; if using Fink Commander
	you need to expand the package name field wide enough to be able to see the full names,
	as you want the Boost libraries for Python 2.5.
	
	Install boost1.34.python25, boost1.34.systempython, and boost1.34.nopython.
	(You can say fink install boost1.34.python25 boost1.34.systempython boost1.34.nopython)
	
	Next install gtkmm2.4-dev, which installs many other packages on which it depends, including
	gtk+2, glib, glibmm, libsig++, atk, pango, expat1, libpng3,
	automake, autoconf, libtool, pkgconfig 
	
	Next, install these libraries:
	libglademm2.4 (also installs libglademm2.4-shlibs)
	
	cairomm1 (also installs cairomm1-shlibs, freetype219, freetype219-shlibs etc; takes a LONG time)
	
	gtkglextmm (also installs gtkglextmm-shlibs, gtkglext1, gtkglext1-shlibs)
	
	Need freetype2, but freetype219 and freetype219-shlibs are installed instead (by cairomm1).
	Because this does not put freetype2.pc into the usual place (/sw/lib/pkgconfig),
	PKG_CONFIG_PATH is set in the configure script to find it.

You can test the pkgconfig machinery by executing the following:
	   pkg-config --libs pango (or /sw/bin/pkg-config --libs pango)
The output should be -L/sw/lib -lpango-1.0 -lm -lgobject-2.0 -lgmodule-2.0 -lglib-2.0 -lintl -liconv 

Next cd into the vpython-core2 directory and execute chmod +x autogen.sh, then ./autogen.sh	   
Here is what happens when I run autogen.sh: 
/sw/share/aclocal/gtkglextmm-1.2.m4:225: warning: 
          underquoted definition of AC_GTKGLEXTMM_SUPPORTS_MULTIHEAD
  run info '(automake)Extending aclocal'
  or see http://sources.redhat.com/automake/automake.html#Extending-aclocal
configure.ac: installing `./missing'
Completed successfully

Apparently the warning about AC_GTKGLEXTMM_SUPPORTS_MULTIHEAD isn't fatal, as it was possible
to build Visual.
	
After important help from Martin Costabel, I was able to make, install, and run successfully.
I placed this file in a build directory at the same level as vpython-core2:
#!/bin/sh -ex
export CPPFLAGS="-Wno-long-double"
export PKG_CONFIG_PATH=/sw/lib/fontconfig2/lib/pkgconfig:/sw/lib/xft2/lib/pkgconfig:/sw/lib/freetype219/lib/pkgconfig
export PYTHON=/sw/bin/python2.5
export CXXFLAGS="-O2 -g -finline-functions"
export CFLAGS='-O3 -g ' 
../vpython-core2/configure --prefix=/sw --disable-dependency-tracking

If you call this file config.txt, in the build directory you need to execute
   chmod +x config.txt
to make the file be executable by "./config.txt".
	
Before making a change to src/Makefile.in, I got a message about possible mismatch of versions, 
as though when I build against /sw/bin/python2.5 and then run /sw/bin/python2.5 the system thinks 
these are different pythons. Martin Costabel commented:

"I am getting this, too, when using the dynamic boost-python library, but not with the static 
libboost_python-mt.a. This is certainly a bug with the libboost_python-mt.dylib, but I haven't 
yet found a combination of build flags to build it correctly, in particular in a way that would 
also work on OSX 10.5."

Following his suggestion, I put Mac-specific code into src/Makefile.in to link to these other
libraries. But then I got this error message in the link phase of the make:

/usr/bin/ld: table of contents for archive: /sw/lib/libboost_python-mt.a is out of date; rerun ranlib(1) (can't load from it) 

So I executed ranlib /sw/lib/libboost_python-mt.a, redid the make, executed make install, and it worked.

When there looked to be a Boost problem, tried building Boost libraries from scratch:

./configure --prefix=/sw --with-libraries=python,thread --with-python=/sw/bin/python2.5
   (This creates user-config.jam)
make
   (apparently equivalent to bjam --user-config=user-config.jam --with-python --with-thread)
sudo make install
There's a name issue; the boost includes need to be available at /sw/include/boost, so do this:
cd /sw/include/boost_1_34_1
sudo cp -r boost /sw/include
I don't understand how /sw/include/boost is found. Looking at our src/build.log, I don't see
anything that specifies we should look generally in /sw/include. Yet when boost is buried in
boost_1_34_1, we don't find header files, and when it is unburied into /sw/include/boost we do.

After a successfull make and "make install" invoking dynamic libraries,
copy these new boost files to /sw/lib/python2.5/site-packages:
bin.v2/libs/python/build/darwin/release/libboost_python-1_34_1.dylib
bin.v2/libs/python/build/darwin/release/threading-multi/libboost_python-mt-1_34_1.dylib
bin.v2/libs/thread/build/darwin/release/threading-multi/libboost_thread-mt-1_34_1.dylib

But cvisual can't find a dylib:

Traceback (most recent call last):
  File "/sw/lib/python2.5/site-packages/visual/examples/bounce2.py", line 1, in <module>
    from visual import *
  File "/sw/lib/python2.5/site-packages/visual/__init__.py", line 140, in <module>
    import cvisual
ImportError: dlopen(/sw/lib/python2.5/site-packages/cvisualmodule.so, 2): Library not loaded: bin.v2/libs/python/build/darwin/release/libboost_python-1_34_1.dylib
  Referenced from: /sw/lib/python2.5/site-packages/cvisualmodule.so
  Reason: image not found
  
I think I've seen stuff on the web about problems with locating dylibs.

Tried changing src/Makefile.in to use only static boost libraries:

  ifeq ($(PYTHON_PLATFORM),darwin)
    # Special rules for OSX
    CVISUAL_LIBS += $(filter-out $(_FILTER_OUT), $(GTK_LIBS) \
       $(GTHREAD_LIBS) /sw/lib/libboost_python-mt.a /sw/lib/libboost_thread-mt.a)

This happened on the make:

/usr/bin/ld: table of contents for archive: /sw/lib/libboost_python-mt.a is out of date; rerun ranlib(1) (can't load from it)
/usr/bin/ld: table of contents for archive: /sw/lib/libboost_thread-mt.a is out of date; rerun ranlib(1) (can't load from it)

So I did this:

bruce-sherwoods-computer:~/Documents/workspace/build brucesherwood$ cd /sw/lib
bruce-sherwoods-computer:/sw/lib brucesherwood$ sudo ranlib libboost_python-mt.a
Password:
bruce-sherwoods-computer:/sw/lib brucesherwood$ sudo ranlib libboost_thread-mt.a
ranlib: file: libboost_thread-mt.a(tss_hooks.o) has no symbols
ranlib: file: libboost_thread-mt.a(tss_dll.o) has no symbols
ranlib: file: libboost_thread-mt.a(tss_pe.o) has no symbols
bruce-sherwoods-computer:/sw/lib brucesherwood$ 

-----------------
Unsuccessful approach
bjam --prefix=/sw --toolset=darwin --with-python-version=2.5 --with-thread stage

Copy the directory named "boost" to /sw/include.

> cp stage/lib/libboost_thread-mt.a /sw/lib
> cp bin.v2/libs/python/build/darwin/release/link-static/threading-multi/libboost_python-mt-1_34_1.a /sw/lib/libboost_python.a

After a successfull make and "make install" invoking dynamic libraries,
copied these new boost files to /sw/lib/python2.5/site-packages:
stage/lib/libboost_thread-mt-1_34_1.dylib
bin.v2/libs/python/build/darwin/release/libboost_python-1_34_1.dylib
bin.v2/libs/python/build/darwin/release/threading-multi/libboost_python-mt-1_34_1.dylib

This attempt didn't help. Still get "Fatal Python error: Interpreter not initialized (version mismatch?).
Is it possible that bjam worked against an old version of Python? Maybe /user/bin/python (which is the
one I see with "which python" and which is version 2.3.5)? No reason bjam should look for python in /sw.