]> git.saurik.com Git - wxWidgets.git/blame - wxPython/docs/BUILD.txt
wx.lib.mixins.listctrl: Patches from Toni Brkic:
[wxWidgets.git] / wxPython / docs / BUILD.txt
CommitLineData
d14a1e28
RD
1Building wxPython 2.5 for Development and Testing
2=================================================
3
e8a71fa0 4This file describes how I build wxWidgets and wxPython while doing
d14a1e28
RD
5development and testing, and is meant to help other people that want
6to do the same thing. I'll assume that you are using either a CVS
e8a71fa0 7snapshot from http://wxWidgets.org/snapshots/, a checkout from CVS, or
4efdef2c 8one of the released wxPython-src-2.5.* tarballs. I'll also assume that
d11c3d64
RD
9you know your way around your system, the compiler, etc. and most
10importantly, that you know what you are doing! ;-)
7d3000f8
RD
11
12If you want to also install the version of wxPython you build to be in
13your site-packages dir and be your default version of wxPython, then a
14few additional steps are needed, and you may want to use slightly
2e957aae
RD
15different options. See the INSTALL_ document for more details. If
16you only use the instructions in this BUILD_ document file then you
17will end up with a separate installation of wxPython and you can
18switch back and forth between this and the release version that you
19may already have installed.
20
21.. _INSTALL: INSTALL.html
22.. _BUILD: BUILD.html
7d3000f8 23
4efdef2c
RD
24If you want to make changes to any of the ``*.i`` files, (SWIG
25interface definition files,) or to regenerate the extension sources or
26renamer modules, then you will need an up to date version of SWIG,
27plus some patches. Get the sources for version 1.3.22, and then apply
28the patches in wxPython/SWIG and then build SWIG like normal. See the
29README.txt in the wxPython/SWIG dir for details about each patch and
30also info about those that may already have been applied to the SWIG
31sources. If you install this build of SWIG to a location that is not
32on the PATH (so it doesn't interfere with an existing SWIG install for
33example) then you can set a setup.py command-line variable named SWIG
34to be the full path name of the executable and the wxPython build will
35use it. See below for an example.
d14a1e28 36
2e957aae 37In the text below I'll use WXDIR with environment variable syntax
4efdef2c 38(either $WXDIR or %WXDIR%) to refer to the top level directory where
2e957aae
RD
39your wxWidgerts and wxPython sources are located. It will equate to
40whereever you checked out the wxWidgets module from CVS, or untarred
4efdef2c 41the wxPython-src tarball to. You can either substitute the $WXDIR text
2e957aae
RD
42below with your actual dir, or set the value in the environment and
43use it just like you see it below.
d14a1e28 44
b14395e4
RD
45If you run into what appears to be compatibility issues between
46wxWidgets and wxPython while building wxPython, be sure you are using
4efdef2c
RD
47the wxWidgets sources included with the wxPython-src tarball or the
48CVS snapshot, and not a previously installed version or a version
b14395e4
RD
49installed from one of the standard wxWidgets installers. With the
50"unstable" releases (have a odd-numbered minor release value, where
51the APIs are allowed to change) there are often significant
52differences between the W.X.Y release of wxWidgets and the W.X.Y.Z
53release of wxPython.
54
d14a1e28
RD
55
56
7d3000f8
RD
57Building on Unix-like Systems (e.g. Linux and OS X)
58---------------------------------------------------
d14a1e28 59
7d3000f8 60These platforms are built almost the same way while in development
d14a1e28 61so I'll combine the descriptions about their build process here.
e8a71fa0 62First we will build wxWidgets and install it to an out of the way
d14a1e28
RD
63place, then do the same for wxPython.
64
65
e8a71fa0
RD
661. Create a build directory in the main wxWidgets dir, and configure
67 wxWidgets. If you want to have multiple builds with different
d14a1e28
RD
68 configure options, just use different subdirectories. I normally
69 put the configure command in a script named ".configure" in each
70 build dir so I can easily blow away everything in the build dir and
71 rerun the script without having to remember the options I used
72 before::
73
8c1a4666 74 cd $WXDIR
7f997e3f
RD
75 mkdir bld
76 cd bld
77 ../configure --prefix=/opt/wx/2.5 \
78 --with-gtk \
79 --with-opengl \
7f997e3f
RD
80 --enable-debug \
81 --enable-geometry \
82 --enable-sound --with-sdl \
83 --enable-display \
8c1a4666 84 --disable-debugreport \
7f997e3f 85
d14a1e28
RD
86
87 On OS X of course you'll want to use --with-mac instead of
5924e48d
RD
88 --with-gtk.
89
4efdef2c
RD
90 **NOTE**: Due to a recent change there is currently a dependency
91 problem in the multilib builds of wxWidgets on OSX, so I have
92 switched to using a monolithic build. That means that all of the
93 core wxWidgets code is placed in in one shared library instead of
94 several. wxPython can be used with either mode, so use whatever
95 suits you on Linux and etc. but use monolithic on OSX. To switch
eac928f0
RD
96 to the monolithic build of wxWidgets just add this configure flag::
97
8c1a4666 98 --enable-monolithic \
eac928f0 99
4efdef2c
RD
100 By default GTK2 will be selected if its development pacakge is
101 installed on your build system. To force the use of GTK 1.2.x
102 instead add this flag::
5924e48d 103
8c1a4666 104 --disable-gtk2 \
5924e48d 105
4efdef2c
RD
106 To make the wxWidgets build be unicode enabled (strongly
107 recommended if you are building with GTK2) then add the following.
108 When wxPython is unicode enabled then all strings that are passed
109 to wx functions and methods will first be converted to unicode
110 objects, and any 'strings' returned from wx functions and methods
111 will actually be unicode objects.::
7f997e3f 112
7f997e3f 113 --enable-unicode \
d14a1e28
RD
114
115 Notice that I used a prefix of /opt/wx/2.5. You can use whatever
7d3000f8
RD
116 path you want, such as a path in your HOME dir or even one of the
117 standard prefix paths such as /usr or /usr/local if you like, but
118 using /opt this way lets me easily have multiple versions and ports
e8a71fa0
RD
119 of wxWidgets "installed" and makes it easy to switch between them,
120 without impacting any versions of wxWidgets that may have been
7d3000f8
RD
121 installed via an RPM or whatever. For the rest of the steps below
122 be sure to also substitute "/opt/wx/2.5" with whatever prefix you
123 choose for your build.
124
125 If you want to use the image and zlib libraries included with
e8a71fa0 126 wxWidgets instead of those already installed on your system, (for
7d3000f8
RD
127 example, to reduce dependencies on 3rd party libraries) then you
128 can add these flags to the configure command::
129
130 --with-libjpeg=builtin \
131 --with-libpng=builtin \
132 --with-libtiff=builtin \
133 --with-zlib=builtin \
134
135
e8a71fa0
RD
1362. To build and install wxWidgets you could just use the "make"
137 command but there are other libraries besides the main wxWidgets
7d3000f8
RD
138 libs that also need to be built so again I make a script to do it
139 all for me so I don't forget anything. This time it is called
5f8d3b6c 140 ".make" (I use the leading "." so when I do ``rm -r *`` in my build
7d3000f8 141 dir I don't lose my scripts too.) This is what it looks like::
d14a1e28
RD
142
143 make $* \
144 && make -C contrib/src/gizmos $* \
4efdef2c 145 && make -C contrib/src/stc $*
d14a1e28
RD
146
147 So you just use .make as if it where make, but don't forget to set
148 the execute bit on .make first!::
149
150 .make
7f997e3f 151 .make install
d14a1e28
RD
152
153 When it's done you should have an installed set of files under
e8a71fa0
RD
154 /opt/wx/2.5 containing just wxWidgets. Now to use this version of
155 wxWidgets you just need to add /opt/wx/2.5/bin to the PATH and set
d14a1e28
RD
156 LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH on OS X) to /opt/wx/2.5/lib.
157
158
1593. I also have a script to help me build wxPython and it is checked in
2e957aae
RD
160 to the CVS as wxWidgets/wxPython/b, but you probably don't want to
161 use it as it's very cryptic and expects that you want to run SWIG,
162 so if you don't have the latest patched up version of SWIG then
163 you'll probably get stuck. So I'll just give the raw commands
164 instead.
d14a1e28
RD
165
166 We're not going to install the development version of wxPython with
167 these commands, so it won't impact your already installed version
168 of the latest release. You'll be able test with this version when
169 you want to, and use the installed release version the rest of the
653d2f0c 170 time. If you want to install the development version please read
7d3000f8
RD
171 INSTALL.txt.
172
173 If you have more than one version of Python on your system then be
174 sure to use the version of Python that you want to use when running
175 wxPython programs to run the setup.py commands below. I'll be
176 using python2.3.
d14a1e28
RD
177
178 Make sure that the first wx-config found on the PATH is the one you
2e957aae 179 installed above, and then change to the $WXDIR/wxPython dir and
d14a1e28
RD
180 run the this command::
181
2e957aae 182 cd $WXDIR/wxPython
7f997e3f 183 python2.3 setup.py build_ext --inplace --debug
d14a1e28 184
7d3000f8
RD
185 If your new wx-config script is not on the PATH, or there is some
186 other version of it found first, then you can add this to the
187 command line to ensure your new one is used instead::
188
7f997e3f 189 WX_CONFIG=/opt/wx/2.5/bin/wx-config
7d3000f8 190
5924e48d
RD
191 By default setup.py will assume that you built wxWidgets to use
192 GTK2. If you built wxWidgets to use GTK 1.2.x then you should add
193 this flag to the command-line::
194
8c1a4666 195 WXPORT=gtk
5924e48d 196
df73e099 197 If you would like to do a Unicode enabled build (all strings sent
5924e48d 198 to or retruned from wx functions are Unicode objects) and your
551d48ed 199 wxWidgets was built with unicode enabled then add this flag::
d14a1e28 200
5924e48d 201 UNICODE=1
d14a1e28
RD
202
203 If you are wanting to have the source files regenerated with swig,
204 then you need to turn on the USE_SWIG flag and optionally tell it
205 where to find the new swig executable, so add these flags::
206
7f997e3f 207 USE_SWIG=1 SWIG=/opt/swig/bin/swig
d14a1e28 208
644e1683
RD
209 If you get errors about being unable to find libGLU, wxGLCanvas
210 being undeclared, or something similar then you can add
55deb208
RD
211 BUILD_GLCANVAS=0 to the setup.py command line to disable the
212 building of the glcanvas module.
7d3000f8 213
d14a1e28 214 When the setup.py command is done you should have fully populated
2e957aae
RD
215 wxPython and wx packages locally in $WXDIR/wxPython/wxPython and
216 $WXDIR/wxPython/wx, with all the extension modules (``*.so`` files)
217 located in the wx package.
d14a1e28
RD
218
219
653d2f0c 2204. To run code with the development version of wxPython, just set the
2e957aae
RD
221 PYTHONPATH to the wxPython dir located in the source tree. For
222 example::
d14a1e28 223
2e957aae
RD
224 export LD_LIBRARY_PATH=/opt/wx/2.5/lib
225 export PYTHONPATH=$WXDIR/wxPython
226 cd $WXDIR/wxPython/demo
7f997e3f 227 python2.3 demo.py
d14a1e28 228
7d3000f8
RD
229 OS X NOTE: You need to use "pythonw" on the command line to run
230 wxPython applications. This version of the Python executable is
231 part of the Python Framework and is allowed to interact with the
d11c3d64 232 display. You can also double click on a .py or a .pyw file from
2e957aae 233 the finder (assuming that the PythonLauncher app is associated with
7d3000f8
RD
234 these file extensions) and it will launch the Framework version of
235 Python for you. For information about creating Applicaiton Bundles
236 of your wxPython apps please see the wiki and the mail lists.
237
238 SOLARIS NOTE: If you get unresolved symbol errors when importing
239 wxPython and you are running on Solaris and building with gcc, then
240 you may be able to work around the problem by uncommenting a bit of
241 code in setup.py and building again. Look for 'SunOS' in setup.py
242 and uncomment the block containing it. The problem is that Sun's ld
243 does not automatically add libgcc to the link step.
d14a1e28
RD
244
245
246
247
248Building on Windows
249-------------------
250
251The Windows builds currently require the use of Microsoft Visual C++.
252Theoretically, other compilers (such as mingw32 or the Borland
253compilers) can also be used but I've never done the work to make that
254happen. If you want to try that then first you'll want to find out if
255there are any tricks that have to be done to make Python extension
256modules using that compiler, and then make a few changes to setup.py
34621cc5 257to accommodate that. (And send the patches to me.) If you plan on
d14a1e28
RD
258using VisualStudio.Net (a.k.a. MSVC 7.1) keep in mind that you'll also
259have to build Python and any other extension modules that you use with
2e957aae 260that compiler because a different version of the C runtime library is
d14a1e28 261used. The Python executable that comes from PythonLabs and the
7d3000f8 262wxPython extensions that I distribute are built with MSVC 6 with all
2e957aae
RD
263the Service Packs applied. This policy will change with Python 2.4
264and MSVC 7.1 will be used starting with that version.
d14a1e28 265
653d2f0c 266If you want to build a debuggable version of wxWidgets and wxPython you
d14a1e28
RD
267will need to have also built a debug version of Python and any other
268extension modules you need to use. You can tell if you have them
269already if there is a _d in the file names, for example python_d.exe
270or python23_d.dll. If you don't need to trace through the C/C++ parts
271of the code with the debugger then building the normal (or hybrid)
272version is fine, and you can use the regular python executables with
273it.
274
4efdef2c
RD
275Starting with 2.5.3.0 wxPython can be built for either the monlithic
276or the multi-lib wxWidgets builds. (Monolithic means that all the
277core wxWidgets code is in one DLL, and multi-lib means that the core
278code is divided into multiple DLLs.) To select which one to use
279specify the MONOLITHIC flag for both the wxWidgets build and the
280wxPython build as shown below, setting it to either 0 or 1.
281
d14a1e28 282Just like the unix versions I also use some scripts to help me build
a8dc2317
RD
283wxWidgets, but I use some non-standard stuff to do it. So if you have
284bash (cygwin or probably MSYS too) or 4NT plus unix-like cat and sed
285programs then there is a copy of my wxWidgets build scripts in
286%WXDIR%\\wxPython\\distrib\\msw. Just copy them to
287%WXDIR%\\build\\msw and you can use them to do your build, otherwise
288you can do everything by hand as described below. But if you do work
289by hand and something doesn't seem to be working correctly please
290refer to the build scripts to see what may need to be done
291differently.
292
64316568 293The \*.btm files are for 4NT and the others are for bash. They are::
a8dc2317 294
8c1a4666
RD
295 .make/.make.btm Builds the main lib and the needed contribs
296 .mymake/.mymake.btm Builds just one lib, use by .make
297 .makesetup.mk A makefile that will copy and edit setup.h
298 as needed for the different types of builds
a8dc2317
RD
299
300Okay. Here's what you've been waiting for, the instructions! Adapt
301accordingly if you are using the bash shell.
d14a1e28 302
e8a71fa0 3031. Set an environment variable to the root of the wxWidgets source
2e957aae 304 tree. This is used by the makefiles::
d14a1e28 305
2e957aae 306 set WXWIN=%WXDIR%
d14a1e28 307
b14395e4 3082. Copy setup0.h to setup.h::
d14a1e28 309
2e957aae 310 cd %WXDIR%\include\wx\msw
7f997e3f 311 copy setup0.h setup.h
d14a1e28 312
7d3000f8 313
a8dc2317 3143. Edit %WXDIR%\\include\\wx\\msw\\setup.h and change a few settings::
d14a1e28 315
7f997e3f
RD
316 wxDIALOG_UNIT_COMPATIBILITY 0
317 wxUSE_DEBUG_CONTEXT 1
318 wxUSE_MEMORY_TRACING 1
319 wxUSE_DIALUP_MANAGER 0
320 wxUSE_GLCANVAS 1
321 wxUSE_POSTSCRIPT 1
322 wxUSE_AFM_FOR_POSTSCRIPT 0
323 wxUSE_DISPLAY 1
8c1a4666 324 wxUSE_DEBUGREPORT 0
a8dc2317
RD
325
326 If you are using my build scripts then a few more settings will be
327 changed and then a copy of setup.h is placed in a subdir of
328 %WXWIN%\\lib\vc_dll. If you are doing it by hand and making a
329 UNICODE build, then also change these::
330
331 wxUSE_UNICODE 1
8c1a4666 332 wxUSE_UNICODE_MSLU 1
a8dc2317
RD
333
334 If you are doing a "hybrid" build (which is the same as the
335 binaries that I release) then also change these::
336
337 wxUSE_MEMORY_TRACING 0
338 wxUSE_DEBUG_CONTEXT 0
339
d14a1e28 340
b14395e4 3414. Make sure that %WXDIR%\\lib\\vc_dll directory is on the PATH. The
312cca17
RD
342 wxWidgets DLLs will end up there as part of the build and so you'll
343 need it on the PATH for them to be found at runtime.
d14a1e28 344
7d3000f8 345
a8dc2317
RD
3465. Change to the %WXDIR%\\build\\msw directory
347
8c1a4666 348 cd %WXDIR%\\build\\msw
d14a1e28 349
7d3000f8 350
a8dc2317
RD
3516. If using my scripts then use the .make.btm command to build
352 wxWidgets. It needs one command-line parameter which controls what
353 kind of build(s) to do. Use one of the following::
d14a1e28 354
7f997e3f
RD
355 debug Build debug version
356 hybrid Build hybrid version
357 both Both debug and hybrid
358 debug-uni Build a debug unicode library
359 hybrid-uni Hybrid unicode (see the pattern yet? ;-)
360 both-uni and finally both unicode libraries
d14a1e28
RD
361
362 For example::
363
364 .make hybrid
365
a8dc2317
RD
366 You can also pass additional command line parameters as needed and
367 they will all be passed on to the nmake commands, for example to
368 clean up the build::
7d3000f8
RD
369
370 .make hybrid clean
371
a8dc2317
RD
372 If *not* using my scripts then you can do it by hand by directly
373 executing nmake with a bunch of extra command line parameters.
374 The base set are::
375
8c1a4666 376 -f makefile.vc OFFICIAL_BUILD=1 SHARED=1 MONOLITHIC=1 USE_OPENGL=1
a8dc2317
RD
377
378 If doing a debug build then add::
379
380 BUILD=debug
381
382 otherwise add these::
383
384 DEBUG_FLAG=1 CXXFLAGS=/D__NO_VC_CRTDBG__ WXDEBUGFLAG=h BUILD=release
385
386 If doing a Unicode build then add these flags::
387
388 UNICODE=1 MSLU=1
389
390 Now, from the %WXDIR%\\build\\msw directory run nmake with your
391 selection of command-line flags as described above. Repeat this
392 same command from the following directories in order to build the
393 contrib libraries::
394
8c1a4666
RD
395 %WXDIR%\contrib\build\gizmos
396 %WXDIR%\contrib\build\stc
a8dc2317 397
d14a1e28 398
a8dc2317
RD
3997. When that is all done it will have built the main wxWidgets DLLs
400 and also some of the contribs DLLs. There should be a ton of DLLs
401 and lots of lib files and other stuff in %WXDIR%\\lib\\vc_dll.
d14a1e28
RD
402
403
4048. Building wxPython on Windows is very similar to doing it for the
405 unix systems. We're not going to install the development version
406 of wxPython with these commands, so it won't impact your already
7d3000f8
RD
407 installed version of the latest release. You'll be able to test
408 with this version when you want to, and use the installed release
d14a1e28 409 version the rest of the time. If you ever do want to install the
653d2f0c 410 development version please refer to INSTALL.txt.
d14a1e28 411
b14395e4 412 Change to the %WXDIR%\\wxPython dir and run the this command,
a8dc2317 413 making sure that you use the version of python that you want to
4efdef2c
RD
414 build for (if you have more than one on your system) and to match
415 the MONOLITHIC flag with how you built wxWidgets::
d14a1e28 416
2e957aae 417 cd %WXDIR%\wxPython
4efdef2c 418 python setup.py build_ext --inplace MONOLITHIC=1
d14a1e28
RD
419
420 If you are wanting to have the source files regenerated with swig,
421 then you need to turn on the USE_SWIG flag and optionally tell it
422 where to find the new swig executable, so add these flags::
423
7f997e3f 424 USE_SWIG=1 SWIG=e:\projects\SWIG-cvs\swig.exe
d14a1e28 425
e8a71fa0 426 If you built a Unicode version of wxWidgets and want to also build
7d3000f8
RD
427 the Unicode version of wxPython then add this flag::
428
429 UNICODE=1
430
e8a71fa0 431 If you have a debug version of Python and wxWidgets and want to
d14a1e28 432 build a debug version of wxPython too, add the --debug flag to the
8eda5e35
RD
433 command line. You should then end up with a set of ``*_d.pyd``
434 files in the wx package and you'll have to run ``python_d.exe`` to
435 use them. The debug and hybrid(release) versions can coexist.
d14a1e28 436
d1a6e2b7 437 When the setup.py command is done you should have fully populated
2e957aae
RD
438 wxPython and wx packages locally in %WXDIR%/wxPython/wxPython and
439 %WXDIR%/wxPython/wx, with all the extension modules (``*.pyd``
8eda5e35 440 files) located in the wx package.
d14a1e28
RD
441
442
653d2f0c 4439. To run code with the development version of wxPython, just set the
d14a1e28
RD
444 PYTHONPATH to the wxPython dir in the CVS tree. For example::
445
2e957aae 446 set PYTHONPATH=%WXDIR%\wxPython
8c1a4666 447 cd %WXDIR\wxPython\demo
7f997e3f 448 python demo.py
d14a1e28 449
7d3000f8 450