| 1 | Building wxPython on Win32 |
| 2 | -------------------------- |
| 3 | |
| 4 | |
| 5 | Building wxPython for use on win32 systems is a fairly simple process |
| 6 | consisting of just a few steps. However depending on where you get |
| 7 | your sources from and what your desired end result is, there are |
| 8 | several permutations of those steps. At a high level the basic steps |
| 9 | are: |
| 10 | |
| 11 | 1. Get the wxWindows sources |
| 12 | 2. Build the wxWindows DLL |
| 13 | 3. Get the wxPython sources |
| 14 | 4. Build and Install wxPython |
| 15 | |
| 16 | We'll go into more detail of each of these steps below, but first a |
| 17 | few bits of background information on tools. |
| 18 | |
| 19 | I use a tool called SWIG (http://www.swig.org) to help generate the |
| 20 | C++ sources used in the wxPython extension module. However you don't |
| 21 | need to have SWIG unless you want to modify the *.i files. If you do |
| 22 | you'll want to have version 1.1-883 of SWIG and you'll need to apply |
| 23 | the patches and updates in wxPython/SWIG and rebuild it. Then you'll |
| 24 | need to change a flag in the setup.py script as described below so the |
| 25 | wxPython build process will use SWIG if needed. |
| 26 | |
| 27 | I use the new Python Distutils tool to build wxPython. It is included |
| 28 | with Python 2.0, but if you want to use Python 1.5.2 or 1.6 then |
| 29 | you'll need to download and install Distutils 1.0 from |
| 30 | http://www.python.org/sigs/distutils-sig/ |
| 31 | |
| 32 | I use Microsoft Visual C++ 6.0 (5.0 with the service packs should work |
| 33 | also) to compile the wxPython C++ sources. Since I am using Distutils |
| 34 | it should be easier now to build with other win32 compilers such as |
| 35 | the free mingw32 or Borland compilers, but I havn't tried them yet. |
| 36 | If anybody wants to try it I'll take any required patches for the |
| 37 | setup script and for these instructions. |
| 38 | |
| 39 | And now on to the fun stuff... |
| 40 | |
| 41 | |
| 42 | |
| 43 | 1. Get the wxWindows sources |
| 44 | ---------------------------- |
| 45 | |
| 46 | A. There are a few possible ways to get sources for wxWindows. You |
| 47 | can download a released version from http://wxwindows.org/ or you |
| 48 | can get current development sources from the CVS server. (Some |
| 49 | information about annonymous CVS access is at |
| 50 | http://wxwindows.org/cvs.htm.) The advantage of using CVS is that |
| 51 | you can easily update as soon as the developers check in new |
| 52 | sources or fixes. The advantage of using a released version is |
| 53 | that it usually has had more testing done. You can decide which |
| 54 | method is best for you. |
| 55 | |
| 56 | B. You'll usually want to use wxWindows sources that have the same |
| 57 | version number as the wxPython sources you are using. (Another |
| 58 | advantage of using CVS is that you'll get both at the same time.) |
| 59 | |
| 60 | C. Once you get the sources be sure to put them in a path without a |
| 61 | space in it (i.e., NOT c:\Program Files\wx) and set an environment |
| 62 | variable named WXWIN to this directory. For example: |
| 63 | |
| 64 | mkdir \wx2 |
| 65 | cd \wx2 |
| 66 | unzip wxMSW-2.2.2.zip |
| 67 | set WXWIN=c:\wx2 |
| 68 | |
| 69 | You'll probably want to add that last line to your autoexec.bat or |
| 70 | System Properties depending on the type of system you are on. |
| 71 | |
| 72 | D. Change to the wx2\include\wx\msw directory and copy setup0.h to |
| 73 | setup.h and then edit setup.h. This is how you control which parts |
| 74 | of wxWindows are compiled into or left out of the build, simply by |
| 75 | turning options on or off. At a minimum you should set the |
| 76 | following: |
| 77 | |
| 78 | wxUSE_NEW_GRID 1 |
| 79 | wxUSE_GLOBAL_MEMORY_OPERATORS 0 |
| 80 | wxUSE_LIBTIFF 1 |
| 81 | wxDIALOG_UNIT_COMPATIBILITY 0 |
| 82 | |
| 83 | I also turn off the following as they are not currently used in |
| 84 | wxPython. There are probably others that can be turned off to |
| 85 | help save space, but I havn't investigated all the potential |
| 86 | configurations yet. Please note that wxPython doesn't (yet) check |
| 87 | these flags for its own build, so if you turn off something that |
| 88 | wxPython expects then you'll get link errors later on. |
| 89 | |
| 90 | wxUSE_DIALUP_MANAGER 0 |
| 91 | wxUSE_DYNLIB_CLASS 0 |
| 92 | wxUSE_DOC_VIEW_ARCHITECTURE 0 |
| 93 | wxUSE_PLOT 0 |
| 94 | wxUSE_POSTSCRIPT_ARCHITECTURE_IN_MSW 0 |
| 95 | |
| 96 | |
| 97 | ** NEW ** |
| 98 | Be sure that wxUSE_GLCANVAS is defined to be 0 as wxPython now |
| 99 | keeps its own copy of the glcanvas sources and expects that it is |
| 100 | not in the main library. This is done to reduce the number of |
| 101 | dependant DLLs on the core library and therefore help reduce |
| 102 | startup time. |
| 103 | |
| 104 | |
| 105 | |
| 106 | 2. Build the wxWindows DLL |
| 107 | --------------------------- |
| 108 | |
| 109 | A. Although MSVC project files are provided I always use the makefiles |
| 110 | to build wxWindows because by default the flags are compatible with |
| 111 | Python, (and I make sure they stay that way.) You would have to |
| 112 | edit the project files a bit to make it work otherwise. |
| 113 | |
| 114 | B. There are three different types of wxWindows DLLs that can be |
| 115 | produced by the VC makefile simply by providing a flag on the nmake |
| 116 | command-line, I call the three types DEBUG, FINAL, and HYBRID. |
| 117 | (The last one is brand new, you'll need my version of the 2.2.2 |
| 118 | sources to get the HYBRID capability.) Here are some more details: |
| 119 | |
| 120 | DEBUG Specified with "FINAL=0" and produces a DLL named |
| 121 | wx[version]d.dll. This DLL is compiled with full |
| 122 | debugging information and with the __WXDEBUG__ set which |
| 123 | enables some debugging-only code in wxWindows such as |
| 124 | assertions and failure log messages. The /MDd flag is |
| 125 | used which means that it is linked with the debugging |
| 126 | version of the C runtime library and also that you must |
| 127 | use the debugging version of Python, (python_d.exe and |
| 128 | pythonXX_d.dll) which also means that all extensions |
| 129 | loaded by Python should also have the _d in the name. |
| 130 | With this option you can use the MSVC debugger to trace |
| 131 | though the Python interpreter, as well as the code for the |
| 132 | wxPython extension and the wxWindows DLL. |
| 133 | |
| 134 | FINAL Specified with "FINAL=1" and produces a DLL named |
| 135 | wx[version].dll. This DLL is compiled with optimizations |
| 136 | turned on and without debugging information and without |
| 137 | __WXDEBUG__. The /MD flag is used which means that you |
| 138 | can use this version with the standard python.exe. This |
| 139 | is the version that I use when making the binary installer |
| 140 | for win32. |
| 141 | |
| 142 | HYBRID Specified with "FINAL=hybrid" and produces a DLL named |
| 143 | wx[version]h.dll. This DLL is almost the same as the |
| 144 | DEBUG version except the /MD flag is used which means that |
| 145 | you can use the standard python.exe but you still get the |
| 146 | debugging info and the __WXDEBUG__ code enabled. With the |
| 147 | debugger you can trace through the the code for the |
| 148 | wxPython extension and the wxWindows DLL, but not the |
| 149 | Python interpreter. You might use this version when you |
| 150 | want to deploy a wxPython app with the __WXDEBUG__ code |
| 151 | enabled. I use this mode most of the time during |
| 152 | development simply because it's easier than having to |
| 153 | remember to type python_d all the time. |
| 154 | |
| 155 | Since different DLL names and object file directories are used you |
| 156 | can build all three types if you like. |
| 157 | |
| 158 | C. Change to the wx2\src\msw directory and type the following command, |
| 159 | using the value for FINAL that you want: |
| 160 | |
| 161 | nmake -f makefile.vc dll pch FINAL=hybrid |
| 162 | |
| 163 | Your machine will then crunch away for possibly a long time, |
| 164 | depending on your hardware, and when it's done you should have a |
| 165 | DLL and some library files in \wx2\lib. |
| 166 | |
| 167 | D. You'll either need to add \wx2\lib to the PATH or copy the DLL file |
| 168 | to a directory already on the PATH so the DLL can be found at runtime. |
| 169 | |
| 170 | E. You can test your build by changing to one of the directories under |
| 171 | \wx2\samples or \wx2\demos and typing (using the right FINAL flag): |
| 172 | |
| 173 | nmake -f makefile.vc FINAL=hybrid WXUSINGDLL=1 |
| 174 | |
| 175 | and then executing the resulting .exe file. |
| 176 | |
| 177 | |
| 178 | |
| 179 | 3. Get the wxPython sources |
| 180 | --------------------------- |
| 181 | |
| 182 | A. You have the same options (and same advantages/disadvantages) for |
| 183 | getting the wxPython source, either a released snapshot or from |
| 184 | CVS. The released version file is named wxPython-[version].tar.gz |
| 185 | and is available at http://wxpython.org/download.php. You can use |
| 186 | WinZip to unpack it if you don't have tar and gzip. If you want to |
| 187 | use CVS you'll find wxPython in the wxWindows CVS tree (see above) |
| 188 | in the wxWindows/wxPython directory. |
| 189 | |
| 190 | |
| 191 | |
| 192 | 4. Build and Install wxPython |
| 193 | ----------------------------- |
| 194 | |
| 195 | A. As mentioned previouslly, wxPython is built with the standard |
| 196 | Python Distutils tool. If you are using Python 2.0c1 or later you |
| 197 | are all set, otherwise you need to download and install Distutils |
| 198 | 1.0 from http://www.python.org/sigs/distutils-sig/. |
| 199 | |
| 200 | B. Change to the root wxPython directory and look at the setup.py |
| 201 | file. This is the script that configures and defines all the |
| 202 | information that Distutils needs to build wxPython. There are some |
| 203 | options near the begining of the script that you may want or need |
| 204 | to change based on what options you have selected up to this point, |
| 205 | (type of DLL built, sources from tar.gz or from CVS, etc.) You can |
| 206 | either change these flags directly in setup.py or supply them on |
| 207 | the command-line. |
| 208 | |
| 209 | BUILD_GLCANVAS Set to zero if you don't want to build the |
| 210 | Open GL canvas extension module. |
| 211 | |
| 212 | BUILD_OGL Set to zero if you don't want to build the |
| 213 | Object Graphics Library extension module. |
| 214 | |
| 215 | BUILD_STC Set to zero if you don't want to build the |
| 216 | wxStyledTextCtrl (the Scintilla wrapper) |
| 217 | extension module. |
| 218 | |
| 219 | USE_SWIG If you have edited any of the *.i files you |
| 220 | will need to set this flag to non-zero so SWIG |
| 221 | will be executed to regenerate the wrapper C++ |
| 222 | and shadow python files. |
| 223 | |
| 224 | IN_CVS_TREE If you are using the CVS version of the |
| 225 | wxWindows and wxPython sources then you will |
| 226 | need to set this flag to non-zero. This is |
| 227 | needed because some source files from the |
| 228 | wxWindows tree are copied to be under the |
| 229 | wxPython tree in order to keep Distutils happy. |
| 230 | With this flag set then setup.py will |
| 231 | automatically keep these copied sources up to |
| 232 | date if the original version is ever updated. |
| 233 | If you are using the tar.gz version of the |
| 234 | Python sources then these copied sources are |
| 235 | already present in your source tree. |
| 236 | |
| 237 | |
| 238 | C. To build and install wxPython you simply need to execute the |
| 239 | setup.py script. If you have more than one version of Python |
| 240 | installed, be sure to execute setup.py with the version you want to |
| 241 | build wxPython for. |
| 242 | |
| 243 | Depending on what kind of wxWindows DLL you built there are |
| 244 | different command-line parameters you'll want to pass to setup (in |
| 245 | addition to possibly one or more of the above): |
| 246 | |
| 247 | FINAL: python setup.py install |
| 248 | |
| 249 | DEBUG: python setup.py build --debug install |
| 250 | |
| 251 | HYBRID: python setup.py HYBRID=1 install |
| 252 | |
| 253 | |
| 254 | D. At this point you should be able to change into the wxPython\demo |
| 255 | directory and run the demo: |
| 256 | |
| 257 | python demo.py |
| 258 | |
| 259 | E. If you would like to make a test build that doesn't overwrite the |
| 260 | installed version of wxPython you can do so with one of these |
| 261 | commands instead of the install command above: |
| 262 | |
| 263 | FINAL: python setup.py build_ext --inplace |
| 264 | |
| 265 | DEBUG: python setup.py build_ext --debug --inplace |
| 266 | |
| 267 | HYBRID: python setup.py HYBRID=1 build_ext --inplace |
| 268 | |
| 269 | This will build the wxPython package in the local wxPython |
| 270 | directory instead of installing it under your Python installation. |
| 271 | To run using this test version just add the base wxPython source |
| 272 | directory to the PYTHONPATH: |
| 273 | |
| 274 | set PYTHONPATH=c:\wx2\wxPython |
| 275 | cd c:\wx2\wxPython\demo |
| 276 | python demo.py |
| 277 | |
| 278 | |
| 279 | That's all folks! |
| 280 | |
| 281 | |
| 282 | ----------------- |
| 283 | robin@alldunn.com |
| 284 | |