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