]> git.saurik.com Git - wxWidgets.git/blame - wxPython/docs/BUILD.txt
Check for errors after unicode conversions
[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
7d3000f8 8one of the released wxPythonSrc-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
8eda5e35 24If you want to make changes to any of the ``*.i`` files, (SWIG interface
7d3000f8
RD
25definition files,) or to regenerate the extension sources or renamer
26modules, then you will need an up to date version of SWIG. Either get
27and build the current CVS version, or version 1.3.20, and then apply
28the patches in wxPython/SWIG. See the README.txt in that dir for
29details about each patch and also info about those that may already
30have been applied to the SWIG sources. If you install this build of
31SWIG to a location that is not on the PATH (so it doesn't interfere
32with an existing SWIG install for example) then you can set a setup.py
d14a1e28
RD
33command-line variable named SWIG to be the full path name of the
34executable and the wxPython build will use it. See below for an
35example.
36
2e957aae
RD
37In the text below I'll use WXDIR with environment variable syntax
38(either $WXDIR or %WXDIR%) to refer to the top level directory were
39your wxWidgerts and wxPython sources are located. It will equate to
40whereever you checked out the wxWidgets module from CVS, or untarred
41the wxPythonSrc 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.
d14a1e28
RD
44
45
46
7d3000f8
RD
47Building on Unix-like Systems (e.g. Linux and OS X)
48---------------------------------------------------
d14a1e28 49
7d3000f8 50These platforms are built almost the same way while in development
d14a1e28 51so I'll combine the descriptions about their build process here.
e8a71fa0 52First we will build wxWidgets and install it to an out of the way
d14a1e28
RD
53place, then do the same for wxPython.
54
55
e8a71fa0
RD
561. Create a build directory in the main wxWidgets dir, and configure
57 wxWidgets. If you want to have multiple builds with different
d14a1e28
RD
58 configure options, just use different subdirectories. I normally
59 put the configure command in a script named ".configure" in each
60 build dir so I can easily blow away everything in the build dir and
61 rerun the script without having to remember the options I used
62 before::
63
2e957aae 64 cd $WXDIR
7f997e3f
RD
65 mkdir bld
66 cd bld
67 ../configure --prefix=/opt/wx/2.5 \
68 --with-gtk \
69 --with-opengl \
70 --disable-monolithic \
71 --enable-debug \
72 --enable-geometry \
73 --enable-sound --with-sdl \
74 --enable-display \
75
d14a1e28
RD
76
77 On OS X of course you'll want to use --with-mac instead of
96d37ab5 78 --with-gtk. For GTK2 and unicode add::
7f997e3f
RD
79
80 --enable-gtk2 \
81 --enable-unicode \
d14a1e28
RD
82
83 Notice that I used a prefix of /opt/wx/2.5. You can use whatever
7d3000f8
RD
84 path you want, such as a path in your HOME dir or even one of the
85 standard prefix paths such as /usr or /usr/local if you like, but
86 using /opt this way lets me easily have multiple versions and ports
e8a71fa0
RD
87 of wxWidgets "installed" and makes it easy to switch between them,
88 without impacting any versions of wxWidgets that may have been
7d3000f8
RD
89 installed via an RPM or whatever. For the rest of the steps below
90 be sure to also substitute "/opt/wx/2.5" with whatever prefix you
91 choose for your build.
92
93 If you want to use the image and zlib libraries included with
e8a71fa0 94 wxWidgets instead of those already installed on your system, (for
7d3000f8
RD
95 example, to reduce dependencies on 3rd party libraries) then you
96 can add these flags to the configure command::
97
98 --with-libjpeg=builtin \
99 --with-libpng=builtin \
100 --with-libtiff=builtin \
101 --with-zlib=builtin \
102
103
e8a71fa0
RD
1042. To build and install wxWidgets you could just use the "make"
105 command but there are other libraries besides the main wxWidgets
7d3000f8
RD
106 libs that also need to be built so again I make a script to do it
107 all for me so I don't forget anything. This time it is called
8eda5e35 108 ".make" (I use the leading ". so when I do ``rm -r *`` in my build
7d3000f8 109 dir I don't lose my scripts too.) This is what it looks like::
d14a1e28
RD
110
111 make $* \
112 && make -C contrib/src/gizmos $* \
113 && make -C contrib/src/ogl CXXFLAGS="-DwxUSE_DEPRECATED=0" $* \
114 && make -C contrib/src/stc $* \
115 && make -C contrib/src/xrc $*
116
117 So you just use .make as if it where make, but don't forget to set
118 the execute bit on .make first!::
119
120 .make
7f997e3f 121 .make install
d14a1e28
RD
122
123 When it's done you should have an installed set of files under
e8a71fa0
RD
124 /opt/wx/2.5 containing just wxWidgets. Now to use this version of
125 wxWidgets you just need to add /opt/wx/2.5/bin to the PATH and set
d14a1e28
RD
126 LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH on OS X) to /opt/wx/2.5/lib.
127
128
1293. I also have a script to help me build wxPython and it is checked in
2e957aae
RD
130 to the CVS as wxWidgets/wxPython/b, but you probably don't want to
131 use it as it's very cryptic and expects that you want to run SWIG,
132 so if you don't have the latest patched up version of SWIG then
133 you'll probably get stuck. So I'll just give the raw commands
134 instead.
d14a1e28
RD
135
136 We're not going to install the development version of wxPython with
137 these commands, so it won't impact your already installed version
138 of the latest release. You'll be able test with this version when
139 you want to, and use the installed release version the rest of the
7d3000f8
RD
140 time. If do want to install the development verison please read
141 INSTALL.txt.
142
143 If you have more than one version of Python on your system then be
144 sure to use the version of Python that you want to use when running
145 wxPython programs to run the setup.py commands below. I'll be
146 using python2.3.
d14a1e28
RD
147
148 Make sure that the first wx-config found on the PATH is the one you
2e957aae 149 installed above, and then change to the $WXDIR/wxPython dir and
d14a1e28
RD
150 run the this command::
151
2e957aae 152 cd $WXDIR/wxPython
7f997e3f 153 python2.3 setup.py build_ext --inplace --debug
d14a1e28 154
7d3000f8
RD
155 If your new wx-config script is not on the PATH, or there is some
156 other version of it found first, then you can add this to the
157 command line to ensure your new one is used instead::
158
7f997e3f 159 WX_CONFIG=/opt/wx/2.5/bin/wx-config
7d3000f8 160
d14a1e28
RD
161 If you are building with GTK2 then add the following flags to the
162 command line::
163
7f997e3f 164 WXPORT=gtk2 UNICODE=1
d14a1e28
RD
165
166 If you are wanting to have the source files regenerated with swig,
167 then you need to turn on the USE_SWIG flag and optionally tell it
168 where to find the new swig executable, so add these flags::
169
7f997e3f 170 USE_SWIG=1 SWIG=/opt/swig/bin/swig
d14a1e28 171
7d3000f8
RD
172 If you get errors about wxGLCanvas or being unable to find libGLU
173 or something like that then you can add BUILD_GLCANVAS=0 to the
174 setup.py command line to disable the building of the glcanvas
175 module.
176
d14a1e28 177 When the setup.py command is done you should have fully populated
2e957aae
RD
178 wxPython and wx packages locally in $WXDIR/wxPython/wxPython and
179 $WXDIR/wxPython/wx, with all the extension modules (``*.so`` files)
180 located in the wx package.
d14a1e28
RD
181
182
1834. To run code with the development verison of wxPython, just set the
2e957aae
RD
184 PYTHONPATH to the wxPython dir located in the source tree. For
185 example::
d14a1e28 186
2e957aae
RD
187 export LD_LIBRARY_PATH=/opt/wx/2.5/lib
188 export PYTHONPATH=$WXDIR/wxPython
189 cd $WXDIR/wxPython/demo
7f997e3f 190 python2.3 demo.py
d14a1e28 191
7d3000f8
RD
192 OS X NOTE: You need to use "pythonw" on the command line to run
193 wxPython applications. This version of the Python executable is
194 part of the Python Framework and is allowed to interact with the
d11c3d64 195 display. You can also double click on a .py or a .pyw file from
2e957aae 196 the finder (assuming that the PythonLauncher app is associated with
7d3000f8
RD
197 these file extensions) and it will launch the Framework version of
198 Python for you. For information about creating Applicaiton Bundles
199 of your wxPython apps please see the wiki and the mail lists.
200
201 SOLARIS NOTE: If you get unresolved symbol errors when importing
202 wxPython and you are running on Solaris and building with gcc, then
203 you may be able to work around the problem by uncommenting a bit of
204 code in setup.py and building again. Look for 'SunOS' in setup.py
205 and uncomment the block containing it. The problem is that Sun's ld
206 does not automatically add libgcc to the link step.
d14a1e28
RD
207
208
209
210
211Building on Windows
212-------------------
213
214The Windows builds currently require the use of Microsoft Visual C++.
215Theoretically, other compilers (such as mingw32 or the Borland
216compilers) can also be used but I've never done the work to make that
217happen. If you want to try that then first you'll want to find out if
218there are any tricks that have to be done to make Python extension
219modules using that compiler, and then make a few changes to setup.py
220to accomodate that. (And send the patches to me.) If you plan on
221using VisualStudio.Net (a.k.a. MSVC 7.1) keep in mind that you'll also
222have to build Python and any other extension modules that you use with
2e957aae 223that compiler because a different version of the C runtime library is
d14a1e28 224used. The Python executable that comes from PythonLabs and the
7d3000f8 225wxPython extensions that I distribute are built with MSVC 6 with all
2e957aae
RD
226the Service Packs applied. This policy will change with Python 2.4
227and MSVC 7.1 will be used starting with that version.
d14a1e28 228
e8a71fa0 229If you want to build a debugable version of wxWidgets and wxPython you
d14a1e28
RD
230will need to have also built a debug version of Python and any other
231extension modules you need to use. You can tell if you have them
232already if there is a _d in the file names, for example python_d.exe
233or python23_d.dll. If you don't need to trace through the C/C++ parts
234of the code with the debugger then building the normal (or hybrid)
235version is fine, and you can use the regular python executables with
236it.
237
238Just like the unix versions I also use some scripts to help me build
e8a71fa0 239wxWidgets, but I use some non-standard stuff to do it. So if you want
2e957aae 240to use my scripts you'll need to get a copy or 4DOS or 4NT from
d14a1e28
RD
241http://www.jpsoft.com/ and also a copy of unix-like cat and sed
242programs. You can also do by hand what my scripts are doing, but
2e957aae
RD
243there are alot of steps involved and I won't be going into details
244here. There is a copy of my build scripts in %WXDIR%\wxPython\distrib\msw
245that you can use for reference (if you don't use them directly) for
246adapting these instructions to your specific needs. The directions
247below assume that you are using my scripts.
d14a1e28
RD
248
249
e8a71fa0 2501. Set an environment variable to the root of the wxWidgets source
2e957aae 251 tree. This is used by the makefiles::
d14a1e28 252
2e957aae 253 set WXWIN=%WXDIR%
d14a1e28
RD
254
2552. Copy setup0.h to setup.h
256
2e957aae 257 cd %WXDIR%\include\wx\msw
7f997e3f 258 copy setup0.h setup.h
d14a1e28 259
7d3000f8 260
2e957aae 2613. Edit %WXDIR%\include\wx\msw\setup.h and change a few settings.
7d3000f8
RD
262 Some of them are changed by my build scripts depending on the type
263 of build (debug/hybrid, unicode/ansi). I change a few of the other
264 defaults to have these values::
d14a1e28 265
7f997e3f
RD
266 wxDIALOG_UNIT_COMPATIBILITY 0
267 wxUSE_DEBUG_CONTEXT 1
268 wxUSE_MEMORY_TRACING 1
269 wxUSE_DIALUP_MANAGER 0
270 wxUSE_GLCANVAS 1
271 wxUSE_POSTSCRIPT 1
272 wxUSE_AFM_FOR_POSTSCRIPT 0
273 wxUSE_DISPLAY 1
274
d14a1e28 275
2e957aae 2764. Make sure that %WXDIR%\lib\vc_dll directory is on the PATH. The
312cca17
RD
277 wxWidgets DLLs will end up there as part of the build and so you'll
278 need it on the PATH for them to be found at runtime.
d14a1e28 279
7d3000f8 280
2e957aae
RD
2815. Change to the %WXDIR%\build\msw directory and copy my build scripts
282 there from their default location in %WXDIR%\wxPython\distrib\msw
283 if they are not present already.
d14a1e28 284
7d3000f8 285
e8a71fa0 2866. Use the .make.btm command to build wxWidgets. It needs one
d14a1e28
RD
287 command-line parameter which controls what kind of build(s) to do.
288 Use one of the following::
289
7f997e3f
RD
290 debug Build debug version
291 hybrid Build hybrid version
292 both Both debug and hybrid
293 debug-uni Build a debug unicode library
294 hybrid-uni Hybrid unicode (see the pattern yet? ;-)
295 both-uni and finally both unicode libraries
d14a1e28
RD
296
297 For example::
298
299 .make hybrid
300
7d3000f8
RD
301 You can also pass additional command line parameters as needed and
302 they will all be passed on to the nmake commands, for example to
303 clean up the build::
304
305 .make hybrid clean
306
d14a1e28 307
e8a71fa0 3087. When that is done it will have built the main wxWidgets DLLs and
7d3000f8
RD
309 also some of the contribs DLLs. There should be a ton of DLLs in
310 %WXDIR%\bin and lots of lib files and other stuff in
311 %WXDIR%\lib\vc_dll.
d14a1e28
RD
312
313
3148. Building wxPython on Windows is very similar to doing it for the
315 unix systems. We're not going to install the development version
316 of wxPython with these commands, so it won't impact your already
7d3000f8
RD
317 installed version of the latest release. You'll be able to test
318 with this version when you want to, and use the installed release
d14a1e28 319 version the rest of the time. If you ever do want to install the
7d3000f8 320 development verison please refer to INSTALL.txt.
d14a1e28 321
2e957aae 322 Change to the %WXDIR%\wxPython dir and run the this command,
7d3000f8
RD
323 makeing sure that you use the version of python that you want to
324 build for (if you have more than one on your system)::
d14a1e28 325
2e957aae 326 cd %WXDIR%\wxPython
7f997e3f 327 python setup.py build_ext --inplace
d14a1e28
RD
328
329 If you are wanting to have the source files regenerated with swig,
330 then you need to turn on the USE_SWIG flag and optionally tell it
331 where to find the new swig executable, so add these flags::
332
7f997e3f 333 USE_SWIG=1 SWIG=e:\projects\SWIG-cvs\swig.exe
d14a1e28 334
e8a71fa0 335 If you built a Unicode version of wxWidgets and want to also build
7d3000f8
RD
336 the Unicode version of wxPython then add this flag::
337
338 UNICODE=1
339
e8a71fa0 340 If you have a debug version of Python and wxWidgets and want to
d14a1e28 341 build a debug version of wxPython too, add the --debug flag to the
8eda5e35
RD
342 command line. You should then end up with a set of ``*_d.pyd``
343 files in the wx package and you'll have to run ``python_d.exe`` to
344 use them. The debug and hybrid(release) versions can coexist.
d14a1e28 345
d1a6e2b7 346 When the setup.py command is done you should have fully populated
2e957aae
RD
347 wxPython and wx packages locally in %WXDIR%/wxPython/wxPython and
348 %WXDIR%/wxPython/wx, with all the extension modules (``*.pyd``
8eda5e35 349 files) located in the wx package.
d14a1e28
RD
350
351
3529. To run code with the development verison of wxPython, just set the
353 PYTHONPATH to the wxPython dir in the CVS tree. For example::
354
2e957aae
RD
355 set PYTHONPATH=%WXDIR%\wxPython
356 cd %WXDIR\wxPython\demo
7f997e3f 357 python demo.py
d14a1e28 358
7d3000f8 359