Phoenix/packaging

How to use the Phoenix snapshot build
=====================================

Hello, and welcome to the Phoenix snapshot build. If you are not
interested in Phoenix or do not know what Phoenix is, you may want to
exit the plane now and find a ticketing agent to help you get to the
correct package.

This tarball is basically a dump of the 'wx' package after a build has
been done, probably by one of the buildbot's build slaves. To use it
instead of Classic wxPython you will need to do a little tweaking to
your environment, which we will describe here. There are likely other
solutions that would work just as well, feel free to use something
else if you prefer.


Virtualenv
----------

One of the easiest ways to try out new Python modules without
impacting those that are already installed for other projects is to
use the virtualenv (or similar) tool to create a new stock python
environment with only the additional packages that you need, plus this
Phoenix test snapshot.  We highly recommend the use of such a tool to
avoid unexpected interactions with other packages.


Help Python find Phoenix
------------------------

All the usual suspects apply here.  You can simply add this folder to
your PYTHONPATH environment variable.  Or you can add a phoenix.pth
file to some place already on the sys.path which contains the path to
this folder.  Or you can even copy the wx folder into the
site-packages folder in your virtualenv.


Help Phoenix find wxWidgets
---------------------------

The Phoenix extension modules need to load the dynamic libraries that
contain the wxWidgets code for the platform.  For the Windows platform
nothing extra should be needed because the system will automatically
look for the DLLs in the same folder that the extension modules are
located in.

For Mac OSX there should also not be anything extra needed to help Phoenix
find the wxWidgets dynamic libraries because the install names have been
modified to use @loader_path so they can find the libraries in the same
folder as the extension modules.

For Unix-like systems like Linux the locations that are searched for the
dynamic libraries can be controlled by setting the LD_LIBRARY_PATH
environment variable. Basically you just need to set that variable to the
path of the wx package, for example if you're in the folder where this README
is located, then you can do something like this::

    export LD_LIBRARY_PATH=`pwd`/wx

The phoenix_environ.sh shell script included with this build can help
you do that, just be sure to use the "source" command so the variables
in the current shell's environment will be modified.

It is also possible to embed the path that the dynamic library should
be loaded from directly into the extension module.  For now at least
this is left as an exercise for the reader.  Look for the chrpath tool.