]> git.saurik.com Git - wxWidgets.git/blame - wxPython/docs/BUILD.txt
Get/SetTitle only for wxTopLevelWindow (wxMGL part).
[wxWidgets.git] / wxPython / docs / BUILD.txt
CommitLineData
4d8a3275 1Building wxPython 2.6 for Development and Testing
d14a1e28
RD
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
4d8a3275 8one of the released wxPython-src-2.6.* 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,
2a13beb3 27plus some patches. Get the sources for version 1.3.24, and then apply
4efdef2c
RD
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
2a13beb3 39your wxWidgets and wxPython sources are located. It will equate to
2e957aae 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
4d8a3275 77 ../configure --prefix=/opt/wx/2.6 \
7f997e3f 78 --with-gtk \
d2b6cc23 79 --with-gnomeprint \
7f997e3f 80 --with-opengl \
7f997e3f
RD
81 --enable-debug \
82 --enable-geometry \
83 --enable-sound --with-sdl \
84 --enable-display \
8c1a4666 85 --disable-debugreport \
7f997e3f 86
d14a1e28
RD
87
88 On OS X of course you'll want to use --with-mac instead of
d2b6cc23 89 --with-gtk and --with-gnomeprint.
5924e48d 90
4efdef2c
RD
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
eac928f0
RD
97 to the monolithic build of wxWidgets just add this configure flag::
98
8c1a4666 99 --enable-monolithic \
eac928f0 100
d2b6cc23 101 By default GTK 2.x will be used for the build. If you would rather
558282a8
RD
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::
5924e48d 104
558282a8 105 --with-gtk=1 \
5924e48d 106
4efdef2c
RD
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.::
7f997e3f 113
7f997e3f 114 --enable-unicode \
d14a1e28 115
4d8a3275 116 Notice that I used a prefix of /opt/wx/2.6. You can use whatever
7d3000f8
RD
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
e8a71fa0
RD
120 of wxWidgets "installed" and makes it easy to switch between them,
121 without impacting any versions of wxWidgets that may have been
7d3000f8 122 installed via an RPM or whatever. For the rest of the steps below
4d8a3275 123 be sure to also substitute "/opt/wx/2.6" with whatever prefix you
7d3000f8
RD
124 choose for your build.
125
126 If you want to use the image and zlib libraries included with
e8a71fa0 127 wxWidgets instead of those already installed on your system, (for
7d3000f8
RD
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
e8a71fa0
RD
1372. To build and install wxWidgets you could just use the "make"
138 command but there are other libraries besides the main wxWidgets
7d3000f8
RD
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
5f8d3b6c 141 ".make" (I use the leading "." so when I do ``rm -r *`` in my build
7d3000f8 142 dir I don't lose my scripts too.) This is what it looks like::
d14a1e28
RD
143
144 make $* \
2e5aa9c4 145 && make -C contrib/src/animate $* \
d14a1e28 146 && make -C contrib/src/gizmos $* \
4efdef2c 147 && make -C contrib/src/stc $*
d14a1e28
RD
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
7f997e3f 153 .make install
d14a1e28
RD
154
155 When it's done you should have an installed set of files under
4d8a3275
RD
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.
d14a1e28
RD
159
160
1613. I also have a script to help me build wxPython and it is checked in
2e957aae
RD
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.
d14a1e28
RD
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
653d2f0c 172 time. If you want to install the development version please read
7d3000f8
RD
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.
d14a1e28
RD
179
180 Make sure that the first wx-config found on the PATH is the one you
2e957aae 181 installed above, and then change to the $WXDIR/wxPython dir and
d14a1e28
RD
182 run the this command::
183
2e957aae 184 cd $WXDIR/wxPython
7f997e3f 185 python2.3 setup.py build_ext --inplace --debug
d14a1e28 186
7d3000f8
RD
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
4d8a3275 191 WX_CONFIG=/opt/wx/2.6/bin/wx-config
7d3000f8 192
5924e48d
RD
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
8c1a4666 197 WXPORT=gtk
5924e48d 198
df73e099 199 If you would like to do a Unicode enabled build (all strings sent
5924e48d 200 to or retruned from wx functions are Unicode objects) and your
551d48ed 201 wxWidgets was built with unicode enabled then add this flag::
d14a1e28 202
5924e48d 203 UNICODE=1
d14a1e28
RD
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
7f997e3f 209 USE_SWIG=1 SWIG=/opt/swig/bin/swig
d14a1e28 210
644e1683
RD
211 If you get errors about being unable to find libGLU, wxGLCanvas
212 being undeclared, or something similar then you can add
55deb208
RD
213 BUILD_GLCANVAS=0 to the setup.py command line to disable the
214 building of the glcanvas module.
7d3000f8 215
d14a1e28 216 When the setup.py command is done you should have fully populated
2e957aae
RD
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.
d14a1e28
RD
220
221
653d2f0c 2224. To run code with the development version of wxPython, just set the
2e957aae
RD
223 PYTHONPATH to the wxPython dir located in the source tree. For
224 example::
d14a1e28 225
4d8a3275 226 export LD_LIBRARY_PATH=/opt/wx/2.6/lib
2e957aae
RD
227 export PYTHONPATH=$WXDIR/wxPython
228 cd $WXDIR/wxPython/demo
7f997e3f 229 python2.3 demo.py
d14a1e28 230
7d3000f8
RD
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
d11c3d64 234 display. You can also double click on a .py or a .pyw file from
2e957aae 235 the finder (assuming that the PythonLauncher app is associated with
7d3000f8
RD
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
6c6b312c 243 code in config.py and building again. Look for 'SunOS' in config.py
7d3000f8
RD
244 and uncomment the block containing it. The problem is that Sun's ld
245 does not automatically add libgcc to the link step.
d14a1e28
RD
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
34621cc5 259to accommodate that. (And send the patches to me.) If you plan on
d14a1e28
RD
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
2e957aae 262that compiler because a different version of the C runtime library is
d14a1e28 263used. The Python executable that comes from PythonLabs and the
7d3000f8 264wxPython extensions that I distribute are built with MSVC 6 with all
2e957aae
RD
265the Service Packs applied. This policy will change with Python 2.4
266and MSVC 7.1 will be used starting with that version.
d14a1e28 267
653d2f0c 268If you want to build a debuggable version of wxWidgets and wxPython you
d14a1e28
RD
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
4efdef2c
RD
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
d14a1e28 284Just like the unix versions I also use some scripts to help me build
a8dc2317
RD
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
64316568 295The \*.btm files are for 4NT and the others are for bash. They are::
a8dc2317 296
8c1a4666
RD
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
a8dc2317
RD
301
302Okay. Here's what you've been waiting for, the instructions! Adapt
303accordingly if you are using the bash shell.
d14a1e28 304
e8a71fa0 3051. Set an environment variable to the root of the wxWidgets source
2e957aae 306 tree. This is used by the makefiles::
d14a1e28 307
2e957aae 308 set WXWIN=%WXDIR%
d14a1e28 309
b14395e4 3102. Copy setup0.h to setup.h::
d14a1e28 311
2e957aae 312 cd %WXDIR%\include\wx\msw
7f997e3f 313 copy setup0.h setup.h
d14a1e28 314
7d3000f8 315
a8dc2317 3163. Edit %WXDIR%\\include\\wx\\msw\\setup.h and change a few settings::
d14a1e28 317
7f997e3f
RD
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
8c1a4666 326 wxUSE_DEBUGREPORT 0
a8dc2317
RD
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
8c1a4666 334 wxUSE_UNICODE_MSLU 1
a8dc2317
RD
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
d14a1e28 342
b14395e4 3434. Make sure that %WXDIR%\\lib\\vc_dll directory is on the PATH. The
312cca17
RD
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.
d14a1e28 346
7d3000f8 347
a8dc2317
RD
3485. Change to the %WXDIR%\\build\\msw directory
349
8c1a4666 350 cd %WXDIR%\\build\\msw
d14a1e28 351
7d3000f8 352
a8dc2317
RD
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::
d14a1e28 356
7f997e3f
RD
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
d14a1e28
RD
363
364 For example::
365
366 .make hybrid
367
a8dc2317
RD
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::
7d3000f8
RD
371
372 .make hybrid clean
373
a8dc2317
RD
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
2a13beb3 378 nmake -f makefile.vc OFFICIAL_BUILD=1 SHARED=1 MONOLITHIC=1 USE_OPENGL=1
a8dc2317
RD
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
2e5aa9c4 397 %WXDIR%\contrib\build\animate
8c1a4666
RD
398 %WXDIR%\contrib\build\gizmos
399 %WXDIR%\contrib\build\stc
a8dc2317 400
d14a1e28 401
a8dc2317
RD
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.
d14a1e28
RD
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
7d3000f8
RD
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
d14a1e28 412 version the rest of the time. If you ever do want to install the
653d2f0c 413 development version please refer to INSTALL.txt.
d14a1e28 414
b14395e4 415 Change to the %WXDIR%\\wxPython dir and run the this command,
a8dc2317 416 making sure that you use the version of python that you want to
4efdef2c
RD
417 build for (if you have more than one on your system) and to match
418 the MONOLITHIC flag with how you built wxWidgets::
d14a1e28 419
2e957aae 420 cd %WXDIR%\wxPython
4efdef2c 421 python setup.py build_ext --inplace MONOLITHIC=1
d14a1e28
RD
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
7f997e3f 427 USE_SWIG=1 SWIG=e:\projects\SWIG-cvs\swig.exe
d14a1e28 428
e8a71fa0 429 If you built a Unicode version of wxWidgets and want to also build
7d3000f8
RD
430 the Unicode version of wxPython then add this flag::
431
432 UNICODE=1
433
e8a71fa0 434 If you have a debug version of Python and wxWidgets and want to
d14a1e28 435 build a debug version of wxPython too, add the --debug flag to the
8eda5e35
RD
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.
d14a1e28 439
d1a6e2b7 440 When the setup.py command is done you should have fully populated
2e957aae
RD
441 wxPython and wx packages locally in %WXDIR%/wxPython/wxPython and
442 %WXDIR%/wxPython/wx, with all the extension modules (``*.pyd``
8eda5e35 443 files) located in the wx package.
d14a1e28
RD
444
445
653d2f0c 4469. To run code with the development version of wxPython, just set the
d14a1e28
RD
447 PYTHONPATH to the wxPython dir in the CVS tree. For example::
448
2e957aae 449 set PYTHONPATH=%WXDIR%\wxPython
8c1a4666 450 cd %WXDIR\wxPython\demo
7f997e3f 451 python demo.py
d14a1e28 452
7d3000f8 453