wxPython/BUILD.unix.txt

   1 Building wxPython on Unix or Unix-like Systems
   2 ----------------------------------------------
   3
   4 The basic steps for building wxPython for Unix or Unix-like systems
   5 are:
   6
   7      1. Compile and/or install glib and gtk+
   8      2. Compile and/or install wxGTK
   9      3. Compile and install wxPython
  10
  11 We'll go into more detail of each of these steps below, but first a
  12 few bits of background information on tools.
  13
  14 I use a tool called SWIG (http://www.swig.org) to help generate the
  15 C++ sources used in the wxPython extension module.  However you don't
  16 need to have SWIG unless you want to modify the *.i files.  I've made
  17 several modifications to SWIG specific to wxPython's needs and so the
  18 modified sources are included in the wx CVS at .../wxPython/wxSWIG.
  19 If you need to modify the *.i files for wxPython then change to this
  20 directory and run:
  21
  22       configure
  23       make
  24
  25 (Do not run "make install" as wxswig is run in-place.)  You'll then
  26 need to change a flag in the setup.py script as described below so the
  27 wxPython build process will use SWIG if needed.
  28
  29 I use the new Python Distutils tool to build wxPython.  It is included
  30 with Python 2.0, but if you want to use Python 1.5.2 or 1.6 then
  31 you'll need to download and install Distutils 1.0 from
  32 http://www.python.org/sigs/distutils-sig/
  33
  34 Okay, now on the the fun stuff...
  35
  36
  37 1. Compile and/or install glib and gtk+
  38 ---------------------------------------
  39
  40 A. First of all, check and see if you've already got glib/gtk+ on your
  41    system, all the Linux distributions I know of come with it, at
  42    least as an option.  Look for libglib.* and libgtk.* in your system's
  43    standard library directories.  You'll also need the headers and
  44    config scripts in order to build things that use glib/gtk.  Try
  45    running gtk-config:
  46
  47            gtk-config --version
  48
  49    If you have version 1.2.5 or better then you're all set.  You can
  50    skip to step #2.
  51
  52 B. If your system has a binary package mechanism, (RPMs, debs,
  53    whatever...) check and see if binaries for glib abd gtk+ are
  54    available.  Be sure to get the runtime library package as well as
  55    the development package, if they are separate.  Install them with
  56    your package tool, and skip to step #2.
  57
  58 C. If all else fails, you can get the source code for glib and gtk+ at
  59    http://www.gtk.org/.  Fetch the latest of each in the 1.2.x
  60    series.  Compile and install each of them like this:
  61
  62             gzip -d [package].tar.gz | tar xvf -
  63             cd [package]
  64             ./configure
  65             make
  66             make install
  67
  68    The last step will probably have to be done as root.  Also, if your
  69    system needs anything done to update the dynamic loader for shared
  70    libraries, (such as running ldconfig on Linux) then do it after
  71    each library is installed.
  72
  73
  74
  75 2. Compile and/or install wxGTK
  76 -------------------------------
  77
  78 A. You can find the sources and RPMs for wxGTK at
  79    http://wxwindows.org/, just follow the download links from the
  80    nevigation panel.  You can also check out a current snapshot of the
  81    sources from the CVS server.  (Some information about annonymous
  82    CVS access is at http://wxwindows.org/cvs.htm.)  The advantage of
  83    using CVS is that you can easily update as soon as the developers
  84    check in new sources or fixes.  The advantage of using a released
  85    version is that it usually has had more thorough testing done.  You
  86    can decide which method is best for you.
  87
  88 B. You'll usually want to use a version of wxGTK that has the same
  89    version number as the wxPython sources you are using.  (Another
  90    advantage of using CVS is that you'll get both at the same time.)
  91
  92 C. If using the RPMs be sure to get both the wxGTK and wxGTK-devel
  93    RPMs (at a minimum) and then install them as root.
  94
  95         rpm -Uhv wxGTK-2.2.2-0.i386.rpm wxGTK-devel-2.2.2-0.i386.rpm
  96
  97 D. If using the sources (either from the tarball or from CVS) then
  98    configure it like this:
  99
 100         cd wxWindows   # or whatever your top-level directory is called
 101         mkdir build
 102         cd build
 103         ../configure --with-gtk
 104
 105    There are gobs and gobs of options for the configure script, run
 106    ../configure --help to see them all.  I'll describe some that I find
 107    useful here.
 108
 109    If you have OpenGL or compatible libraries installed, then add the
 110    --with-opengl flag.
 111
 112    If you are on Solaris and are using a recent version of GCC, then
 113    you'll probably want to add the --enable-permissive flag so the
 114    compiler won't barf on your broken X11 header files.
 115
 116    To make a debugging version of wxGTK, add the --enable-debug flag.
 117    This sets the -g flag for the compiler and also activates some
 118    special debugging code in wxWindows by defining the __WXDEBUG__
 119    macro.  You'll get some extra asserts, failure logging, etc.
 120
 121    To make a static library and not make a shared library, use the
 122    --disable-shared and --enable-static flags.
 123
 124    NOTE: It has been discovered that some pre-built distributions of
 125    Python are built with options that can cause incompatibilities
 126    between wxPython and wxGTK.  Typically these are things like large
 127    file support on the platforms that have it.  This causes some basic
 128    types, like off_t, to be typedef'd differently causing the C++
 129    method signatures to be incompatible and giving link errors.  The
 130    way to fix this is to activate these same settings in the wxGTK
 131    build, usually by looking at the flags and options used in
 132    compiling wxPython that are different from the options used on
 133    wxGTK compiles.  For example, on SuSE doing the following before
 134    running wxGTK's configure seems to take care of it:
 135
 136    export CFLAGS="-D_FILE_OFFSET_BITS=64 -DHAVE_LARGEFILE_SUPPORT"
 137    export CXXFLAGS=$CFLAGS
 138
 139
 140 E. Now just compile and install.  You need to use GNU make, so if your
 141    system has something else get GNU make and build and install it and
 142    use it instead of your system's default make command.
 143
 144        make
 145        make install
 146
 147    The last step will probably have to be done as root.  Also, if your
 148    system needs anything done to update the dynamic loader for shared
 149    libraries, (such as running ldconfig on Linux) then do it now.
 150
 151 F. You can test your build by changing to one of the directories under
 152    build/samples or build/demos, running make and then running the
 153    executable that is built.
 154
 155
 156
 157 3. Compile and install wxPython
 158 -------------------------------
 159
 160 A. You have the same options (and same advantages/disadvantages) for
 161    getting the wxPython source, either a released snapshot or from
 162    CVS.  The released version file is named wxPython-[version].tar.gz
 163    and is available at http://wxpython.org/download.php.  If you want
 164    to use CVS you'll find wxPython in the wxWindows CVS tree (see
 165    above) in the wxWindows/wxPython directory.
 166
 167 B. As mentioned previouslly, wxPython is built with the standard
 168    Python Distutils tool.  If you are using Python 2.0 or later you
 169    are all set, otherwise you need to download and install Distutils
 170    1.0 from http://www.python.org/sigs/distutils-sig/.
 171
 172    On Unix systems Distutils figures out what commands and flags to
 173    use for the compiler and linker by looking in the Makefile that was
 174    used to build Python itself.  Most of the time this works okay.  If
 175    it doesn't, there doesn't seem to be a way to override the values
 176    that Distutils uses without hacking either Distutils itself, or
 177    Python's Makefile.  (Complain to the distutils-sig about this
 178    please.)  For example, on a Solaris system I had to edit
 179    /usr/local/lib/python1.5/config/Makefile and replace
 180
 181          LDSHARED=ld -G
 182
 183    with
 184
 185          LDSHARED=gcc -G
 186
 187    This particular problem has been fixed in Python 1.6 and beyond,
 188    but there may be similar issues on other platforms.
 189
 190    While we're on the subject of how Python was built... Since
 191    wxPython is a C++ extension some platforms and/or compilers will
 192    require that the Python executable was linked with the C++ linker
 193    in order for everything to work correctly.  If you build and
 194    install Python yourself then this is easy to take care of,
 195    otherwise you may have to mess with binary packages or bribe your
 196    system administrator...
 197
 198    In my case on Solaris wxPython applications would core dump on
 199    exit.  The core file indicated that the fault happened after
 200    _exit() was called and the run-time library was trying to execute
 201    cleanup code.  After relinking the Python executable the problem
 202    went away.  To build Python to link with the C++ linker do this:
 203
 204          cd Python-2.0      # wherever the root of the source tree is
 205          rm python          # in case it's still there from an old build
 206          make LINKCC=g++    # or whatever your C++ command is
 207          make install
 208
 209
 210 C. Change to the root wxPython directory and look at the setup.py
 211    file.  This is the script that configures and defines all the
 212    information that Distutils needs to build wxPython.  There are some
 213    options near the begining of the script that you may want or need
 214    to change based on your system and what options you have selected
 215    up to this point, (sources from tar.gz or from CVS, etc.)  You can
 216    either change these flags directly in setup.py or supply them on
 217    the command-line.
 218
 219         BUILD_GLCANVAS Set to zero if you don't want to build the
 220                        Open GL canvas extension module.  If you don't
 221                        have OpenGL or compatible libraries then you'll
 222                        need to set this to zero.
 223
 224              BUILD_OGL Set to zero if you don't want to build the
 225                        Object Graphics Library extension module.
 226
 227              BUILD_STC Set to zero if you don't want to build the
 228                        wxStyledTextCtrl (the Scintilla wrapper)
 229                        extension module.
 230
 231               USE_SWIG If you have edited any of the *.i files you
 232                        will need to set this flag to non-zero so SWIG
 233                        will be executed to regenerate the wrapper C++
 234                        and shadow python files.
 235
 236            IN_CVS_TREE If you are using the CVS version of the
 237                        wxWindows and wxPython sources then you will
 238                        need to set this flag to non-zero.  This is
 239                        needed because some source files from the
 240                        wxWindows tree are copied to be under the
 241                        wxPython tree in order to keep Distutils happy.
 242                        With this flag set then setup.py will
 243                        automatically keep these copied sources up to
 244                        date if the original version is ever updated.
 245                        If you are using the tar.gz version of the
 246                        Python sources then these copied sources are
 247                        already present in your source tree.
 248
 249
 250 D. To build and install wxPython you simply need to execute the
 251    setup.py script.  If you have more than one version of Python
 252    installed, be sure to execute setup.py with the version you want to
 253    build wxPython for.  Depending on the permissions on your
 254    site-packages directory you may need to be root to run the install
 255    command.
 256
 257          python setup.py build
 258          python setup.py install
 259
 260 E. At this point you should be able to change into the wxPython/demo
 261    directory and run the demo:
 262
 263          python demo.py
 264
 265 F. If you would like to make a test build that doesn't overwrite the
 266    installed version of wxPython you can do so with this command
 267    instead of the install command above:
 268
 269          python setup.py build_ext --inplace
 270
 271    This will build the wxPython package in the local wxPython
 272    directory instead of installing it under your Python installation.
 273    To run using this test version just add the base wxPython source
 274    directory to the PYTHONPATH:
 275
 276          export PYTHONPATH=~/projects/wxWindows/wxPython
 277          # or whatever is required for your shell
 278          cd ~/projects/wxWindows/wxPython/demo
 279          python demo.py
 280
 281
 282 That's all folks!
 283
 284
 285 -----------------
 286 robin@alldunn.com