Tweaks to work around wxMac bugs

[wxWidgets.git] / wxPython / docs / INSTALL.txt

Installing wxPython 2.5 from Source
===================================


This document will describe the few differences and additions to the
content in the BUILD_ document for installing wxPython built from
source.  Please follow the intstructions both in this file and in
BUILD_ to perform this task.  Where there is overlap the items
described here will take precedence for doing installations.

.. _BUILD: BUILD.html




Installing on Unix-like Systems (not OS X)
------------------------------------------

1. When building wxWidgets you need to decide if you want it to be a
   private copy only accessed by wxPython, or if you would like it to
   be installed in a stanard location such as /usr.  Or perhaps you
   already have a version of wxWidgets installed on your system (such
   as from an RPM) and you want wxPython to use that version too.  If
   so then you'll want to ensure that the flags and options used to
   build the installed version are compatible with wxPython.  


2. If you do decide to build and install your own wxWidgets then there
   are a few tweaks to the configure flags described in BUILD.txt that
   you will probably want to make.  Instead of --enable-debug use
   this configure flag::

		      --enable-optimize \

   Normally I also use the following flag in order to have wxWidgets
   runtime assertions turned into Python exceptions where possible.
   It does add extra code to the build but probably not enough to
   worry about it.  However if you want to get as lean a build as
   possible you can leave it out, but if your code does something bad
   then instead of exceptions you'll likely get a crash::

		      --enable-debug_flag \

   If you are building a private copy of wxWidgets (IOW, not installed
   in a standard library location) then it can be kind of a hassle to
   always have to set the LD_LIBRARY_PATH variable so wxPython can
   find the wxWidgets shared libraries.  You can hard code the library
   path into the binaries by using the rpath option when configuring
   wxWidgets.  For example::

                     --enable-rpath=/opt/wx/2.5/lib \

   SOLARIS NOTE: The --enable-rpath option may cause problems when
   using wxGTK on Solaris when compiling wxPython as described below.
   The woraround is to not use --enable-rpath flag for configure, but
   in that case all wxPython applications *must* have the
   LD_LIBRARY_PATH set to include $WXPREF/lib, or you can use the
   'crle' program to modify the runtime linking environment.  If this
   is the only installation of wxGTK on the system then you can use a
   system library path for prefix and not have to worry about it at
   all.


3. Build and install wxGTK as described in BUILD.txt.


4. In addition to building wxPython as described in BUILD.txt, you can
   install it to Python's site-packages dir, as well as some scripts
   into the same bin dir used by Python by using this command::

	python2.3 setup.py install

   If you would like to install to some place besides the prefix where
   Python is installed, (such as to your home directory) then you can
   add "--root=<path>" after the "install" command.  This will use
   <path> as the prefix and will install scripts to a bin subdir and
   the wxPython packages to a lib subdir.  To use wxPython like this
   you'll need to ensure that the directory containing wxPython is
   contained in the PYTHONPATH environment variable.
   



Installing on OS X
------------------

Installing wxPython on OS X is nearly the same as the Unix
instructions above, except for a few small, but important details:

1. The --enable-rpath configure option is not needed since the path to
   the wxWidgets dylibs will automatically be encoded into the
   extension modules when they are built.  If you end up moving the
   wxWidgets dynlibs to some other location (such as inside the .app
   bundle of your applicaiton for distribution to other users,) then
   you will need to set DYLD_LIBRARY_PATH to this location so the
   dylibs can be found at runtime.

2. Depending on the version of OS X Python may be installed in
   different locations.  On 10.2 (Jaguar) you need to download and
   install MacPython-OSX-2.3 from http://www.python.org/ and the
   Python Framework will then be installed in /Library/Frameworks.  On
   10.3 (Panther) Apple supplies the Python Framework as part of the
   OS install, but it will be located in /System/Library/Frameworks
   instead.  However, on Panther the site-packages dir is sym-linked
   to /Library/Python/2.3 so the wxPython packages will end up there,
   although they will still be visible from site-packages.  If you are
   building distributions of wxPython to be installed on other
   machines be careful to install to /Library/Python/2.3.  To
   complicate things further, the Jaguar version, or a custom build
   you do yourself will end up in /Library/Frameworks even on
   Panther...

3. You need to use pythonw at the command line or PythonLauncher app
   to run wxPython apps, otherwise the app will not be able to fully
   use the GUI display.





Installing on Windows
---------------------

1. Build wxWidgets and wxPython as described in BUILD.txt.  If you
   would rather have a version without the code that turns runtime
   assertions into Python exceptions, then use "release" instead of
   "hybrid" when building wxWidgets and add "FINAL=1" to the setup.py
   command line.

2. Install wxPython like this.  Remember to add any additional flags
   you added for the build such as UNICODE or USE_SWIG::

      python setup.py install


3. Copy the wxWidgets DLLs to the wx package directory so they can be
   found at runtime by the extension modules without requiring that
   they be installed on the PATH::

	copy %WXWIN%\lib\vc_dll\wx*h_*.dll c:\Python23\Lib\site-packages\wx