]> git.saurik.com Git - wxWidgets.git/blob - docs/x11/install.txt
Allow building with GCC 2.95.
[wxWidgets.git] / docs / x11 / install.txt
1 wxWidgets 2.5 for X11 installation
2 ----------------------------------
3
4 IMPORTANT NOTE:
5
6 If you experience problems installing, please re-read these
7 instructions and other related files (todo.txt, bugs.txt and
8 osname.txt for your platform if it exists) carefully before
9 mailing wxwin-users or the author. Preferably, try to fix the
10 problem first and then send a patch to the author.
11
12 When sending bug reports tell us what version of wxWidgets you are
13 using (including the beta) and what compiler on what system. One
14 example: wxX11 2.5.4, gcc 2.95.4, Redhat 6.2
15
16 First steps
17 -----------
18
19 - Download wxX11-x.y.z.tgz, where x.y.z is the version number.
20 Download documentation in a preferred format, such as
21 wxWidgets-HTML.zip or wxWidgets-PDF.zip.
22
23 - Make a directory such as ~/wx and unarchive the files into this
24 directory.
25
26 - It is recommended that you install bison and flex; using yacc
27 and lex may require tweaking of the makefiles. You also need
28 libXpm if you want to have XPM support in wxWidgets (recommended).
29
30 - You can now use configure to build wxWidgets and the samples.
31
32 Using configure is the recommended way to build the library. If it doesn't
33 work for you for whatever reason, please report it (together with detailed
34 information about your platform and the (relevant part of) contents of
35 config.log file) to wx-dev@lists.wxwindows.org.
36
37 COMPILING USING CONFIGURE
38 =========================
39
40 * The simplest case
41 -------------------
42
43 If you compile wxWidgets on Linux for the first time and don't like to read
44 install instructions just do (in the base dir):
45
46 > ./configure --with-x11
47 > make
48 > su <type root password>
49 > make install
50 > ldconfig
51 > exit
52
53 Afterwards you can continue with
54
55 > make
56 > su <type root password>
57 > make install
58 > ldconfig
59 > exit
60
61 If you want to remove wxWidgets on Unix you can do this:
62
63 > su <type root password>
64 > make uninstall
65 > ldconfig
66 > exit
67
68 * The expert case
69 -----------------
70
71 If you want to do some more serious cross-platform programming with wxWidgets,
72 such as for GTK and X11, you can now build two complete libraries and use
73 them concurrently. For this end, you have to create a directory for each build
74 of wxWidgets - you may also want to create different versions of wxWidgets
75 and test them concurrently. Most typically, this would be a version configured
76 with --enable-debug_flag and one without. Note, that only one build can
77 currently be installed, so you'd have to use local version of the library for
78 that purpose.
79
80 For building three versions (one GTK, one X11 and a debug version of the GTK
81 source) you'd do this:
82
83 md buildx11
84 cd buildx11
85 ../configure --with-x11
86 make
87 cd ..
88
89 md buildgtk
90 cd buildgtk
91 ../configure --with-gtk
92 make
93 cd ..
94
95 md buildgtkd
96 cd buildgtkd
97 ../configure --with-gtk --enable-debug_flag
98 make
99 cd ..
100
101 * The simplest errors
102 ---------------------
103
104 You get errors during compilation: The reason is that you probably have a
105 broken compiler. GCC 2.8 and earlier versions and egcs are likely to cause
106 problems due to incomplete support for C++ and optimisation bugs. Best to use
107 GCC 2.95 or later.
108
109 You get immediate segfault when starting any sample or application: This is
110 either due to having compiled the library with different flags or options than
111 your program - typically you might have the __WXDEBUG__ option set for the
112 library but not for your program - or due to using a compiler with optimisation
113 bugs.
114
115 * The simplest program
116 ----------------------
117
118 Now create your super-application myfoo.cpp and compile anywhere with
119
120 g++ myfoo.cpp `wx-config --libs --cxxflags` -o myfoo
121
122 * General
123 ---------
124
125 The Unix variants of wxWidgets use GNU configure. If you have problems with
126 your make use GNU make instead.
127
128 If you have general problems with installation, see the wxWidgets website at
129
130 http://www.wxwidgets.org/
131
132 for newest information. If you still don't have any success, please send a bug
133 report to one of our mailing lists (see my homepage) INCLUDING A DESCRIPTION OF
134 YOUR SYSTEM AND YOUR PROBLEM, SUCH AS YOUR VERSION OF X, WHAT DISTRIBUTION
135 YOU USE AND WHAT ERROR WAS REPORTED. I know this has no effect, but I tried...
136
137 * GUI libraries
138 ---------------
139
140 wxWidgets/X11 requires the X11 library to be installed on your system.
141
142 * Additional libraries
143 ----------------------
144
145 wxWidgets/X11 requires a thread library and X libraries known to work with
146 threads. This is the case on all commercial Unix-Variants and all
147 Linux-Versions that are based on glibc 2 except RedHat 5.0 which is broken in
148 many aspects. As of writing this, virtually all Linux distributions have
149 +correct glibc 2 support.
150
151 You can disable thread support by running
152
153 ./configure --disable-threads
154 make
155 su <type root password>
156 make install
157 ldconfig
158 exit
159
160 * Building wxX11 on OS/2
161 ------------------------
162
163 Please send comments and question about the OS/2 installation
164 to Stefan Neis <Stefan.Neis@t-online.de> and patches to
165 the wxWidgets mailing list.
166
167 In the following list, the version numbers indicate the configuration that
168 was actually used by myself, newer version should cause no problems and
169 even older ones are expected to work most of the time.
170
171 You'll need OS/2 Warp (4.51) or eCS(1.0), X-Free86/2 (3.3.6 or newer),
172 emx (0.9d fix 4), flex (2.5.4), yacc (1.8) or bison (1.25),
173 a Unix like shell (pdksh-5.2.14 or ash), Autoconf (2.57), GNU file
174 utilities (3.13), GNU text utilities (1.19), GNU shell utilites (1.12),
175 m4 (1.4), sed (2.05), grep (2.0), Awk (3.0.3), GNU Make (3.75).
176
177 Preferably, you should have Posix/2 installed and C(PLUS)_INCLUDE_PATH and
178 LIBRARY_PATH set up accordingly, however, wxGTK will even work without it.
179 Presence of Posix/2 will be auto-detected.
180
181 Open an OS/2 prompt and switch to the directory above.
182 Set MAKESHELL (and depending on your installation also INSTALL, for me
183 it tends to try to use the system's tcpip\pcomos\install.exe which causes
184 problems...) to a Unix like shell, e.g.
185 SET MAKESHELL=ash
186
187 Be warned that depending on the precise version of your make, the
188 variable that needs to be set might be MAKE_SHELL instead of MAKESHELL.
189 If you have a really deficient version of GNU make, it might even be
190 necessary to set SHELL or even COMSPEC to a unix like shell as well.
191
192 Notice that the delivered configure scripts are fully OS/2 aware, so you
193 can simply run
194 ash -c "configure --with-x11"
195 and make and possibly make install as described above.
196
197 To verify X11 installation, configure will try to compile a
198 sample program that requires X headers/libraries to be either
199 available via C_INCLUDE_PATH and LIBRARY_PATH or you need to
200 explicitly set CFLAGS prior to running configure.
201
202 * Building wxX11 on SGI
203 -----------------------
204
205 Using the SGI native compilers, it is recommended that you
206 also set CFLAGS and CXXFLAGS before running configure. These
207 should be set to :
208
209 CFLAGS="-mips3 -n32"
210 CXXFLAGS="-mips3 -n32"
211
212 This is essential if you want to use the resultant binaries
213 on any other machine than the one it was compiled on. If you
214 have a 64bit machine (Octane) you should also do this to ensure
215 you don't accidently build the libraries as 64bit (which is
216 untested).
217
218 The SGI native compiler support has only been tested on Irix 6.5.
219
220 * Create your configuration
221 ---------------------------
222
223 Usage:
224 ./configure [options]
225
226 If you want to use system's C and C++ compiler,
227 set environment variables CXX and CC as
228
229 % setenv CC cc
230 % setenv CXX CC
231 % ./configure [options]
232
233 to see all the options please use:
234
235 ./configure --help
236
237 The basic philosophy is that if you want to use different
238 configurations, like a debug and a release version,
239 or use the same source tree on different systems,
240 you have only to change the environment variable OSTYPE.
241 (Sadly this variable is not set by default on some systems
242 in some shells - on SGI's for example). So you will have to
243 set it there. This variable HAS to be set before starting
244 configure, so that it knows which system it tries to
245 configure for.
246
247 Configure will complain if the system variable OSTYPE has
248 not been defined. And Make in some circumstances as well...
249
250
251 * General options
252 -----------------
253
254 Given below are the commands to change the default behaviour,
255 i.e. if it says "--disable-threads" it means that threads
256 are enabled by default.
257
258 You have to add --with-x11 on platforms, where X11 is
259 not the default (on Linux, configure will default to GTK).
260
261 --with-x11 Use X11.
262
263 The following options handle the kind of library you want to build.
264
265 --disable-threads Compile without thread support. Threads
266 support is also required for the
267 socket code to work.
268
269 --disable-shared Do not create shared libraries.
270
271 --enable-monolithic Build wxWidgets as single library instead
272 of as several smaller libraries (which is
273 the default since wxWidgets 2.5.0).
274
275 --disable-optimise Do not optimise the code. Can
276 sometimes be useful for debugging
277 and is required on some architectures
278 such as Sun with gcc 2.8.X which
279 would otherwise produce segvs.
280
281 --enable-profile Add profiling info to the object
282 files. Currently broken, I think.
283
284 --enable-no_rtti Enable compilation without creation of
285 C++ RTTI information in object files.
286 This will speed-up compilation and reduce
287 binary size.
288
289 --enable-no_exceptions Enable compilation without creation of
290 C++ exception information in object files.
291 This will speed-up compilation and reduce
292 binary size. Also fewer crashes during the
293 actual compilation...
294
295 --enable-no_deps Enable compilation without creation of
296 dependency information.
297
298 --enable-permissive Enable compilation without checking for strict
299 ANSI conformance. Useful to prevent the build
300 dying with errors as soon as you compile with
301 Solaris' ANSI-defying headers.
302
303 --enable-mem_tracing Add built-in memory tracing.
304
305 --enable-dmalloc Use the dmalloc memory debugger.
306 Read more at www.letters.com/dmalloc/
307
308 --enable-debug_info Add debug info to object files and
309 executables for use with debuggers
310 such as gdb (or its many frontends).
311
312 --enable-debug_flag Define __DEBUG__ and __WXDEBUG__ when
313 compiling. This enable wxWidgets' very
314 useful internal debugging tricks (such
315 as automatically reporting illegal calls)
316 to work. Note that program and library
317 must be compiled with the same debug
318 options.
319
320 * Feature Options
321 -----------------
322
323 Many of the configure options have been thoroughly tested
324 in wxWidgets snapshot 6, but not yet all (ODBC not).
325
326 When producing an executable that is linked statically with wxX11
327 you'll be surprised at its immense size. This can sometimes be
328 drastically reduced by removing features from wxWidgets that
329 are not used in your program. The most relevant such features
330 are
331
332 --without-libpng Disables PNG image format code.
333
334 --without-libjpeg Disables JPEG image format code.
335
336 { --without-odbc Disables ODBC code. Not yet. }
337
338 --without-expat Disable XML classes based on Expat parser.
339
340 --disable-resources Disables the use of *.wxr type
341 resources.
342
343 --disable-threads Disables threads. Will also
344 disable sockets.
345
346 --disable-sockets Disables sockets.
347
348 --disable-dnd Disables Drag'n'Drop.
349
350 --disable-clipboard Disables Clipboard.
351
352 --disable-serial Disables object instance serialisation.
353
354 --disable-streams Disables the wxStream classes.
355
356 --disable-file Disables the wxFile class.
357
358 --disable-textfile Disables the wxTextFile class.
359
360 --disable-intl Disables the internationalisation.
361
362 --disable-validators Disables validators.
363
364 --disable-accel Disables accel.
365
366 Apart from disabling certain features you can very often "strip"
367 the program of its debugging information resulting in a significant
368 reduction in size.
369
370 Please see the output of "./configure --help" for comprehensive list
371 of all configurable options.
372
373
374 * Compiling
375 -----------
376
377 The following must be done in the base directory (e.g. ~/wxX11
378 or whatever)
379
380 Now the makefiles are created (by configure) and you can compile
381 the library by typing:
382
383 make
384
385 make yourself some coffee, as it will take some time. On an old
386 386SX possibly two weeks. During compilation, you'll get a few
387 warning messages depending in your compiler.
388
389 If you want to be more selective, you can change into a specific
390 directory and type "make" there.
391
392 Then you may install the library and its header files under
393 /usr/local/include/wx and /usr/local/lib respectively. You
394 have to log in as root (i.e. run "su" and enter the root
395 password) and type
396
397 make install
398
399 You can remove any traces of wxWidgets by typing
400
401 make uninstall
402
403 If you want to save disk space by removing unnecessary
404 object-files:
405
406 make clean
407
408 in the various directories will do the work for you.
409
410 * Creating a new Project
411 ------------------------
412
413 1) The first way uses the installed libraries and header files
414 automatically using wx-config
415
416 g++ myfoo.cpp `wx-config --libs` `wx-config --cxxflags` -o myfoo
417
418 Using this way, a make file for the minimal sample would look
419 like this
420
421 CXX = g++
422
423 minimal: minimal.o
424 $(CXX) -o minimal minimal.o `wx-config --libs`
425
426 minimal.o: minimal.cpp mondrian.xpm
427 $(CXX) `wx-config --cxxflags` -c minimal.cpp -o minimal.o
428
429 clean:
430 rm -f *.o minimal
431
432 This is certain to become the standard way unless we decide
433 to stick to tmake.
434
435 If your application uses only some of wxWidgets libraries, you can
436 specify required libraries when running wx-config. For example,
437 `wx-config --libs=html,core` will only output link command to link
438 with libraries required by core GUI classes and wxHTML classes. See
439 the manual for more information on the libraries.
440
441 2) The other way creates a project within the source code
442 directories of wxWidgets. For this endeavour, you'll need
443 GNU autoconf version 2.14 and add an entry to your Makefile.in
444 to the bottom of the configure.in script and run autoconf
445 and configure before you can type make.
446
447 * Further notes by Julian Smart
448 -------------------------------
449
450 - You may find the following script useful for compiling wxX11,
451 especially if installing from zips (which don't preserve file
452 permissions). Make this script executable with the command
453 chmod a+x makewxx11.
454
455 -------:x-----Cut here-----:x-----
456 # makewxx11
457 # Sets permissions (in case we extracted wxX11 from zip files)
458 # and makes wxX11.
459 # Call from top-level wxWidgets directory.
460 # Note that this uses standard (but commonly-used) configure options;
461 # if you're feeling brave, you may wish to compile with threads:
462 # if they're not supported by the target platform, they will be disabled
463 # anyhow
464 # -- Julian Smart
465 chmod a+x configure config.sub config.guess
466 ./configure --with-x11 --with-shared --with-debug_flag --with-debug_info --enable-debug --without-threads --without-sockets --without-odbc
467 make
468 -------:x-----Cut here-----:x-----
469
470 This script will build wxX11 using shared libraries. If you want to build
471 a static wxWidgets library, use --disable-shared.
472
473 Troubleshooting
474 ---------------
475
476 - Solaris compilation with gcc: if the compiler has problems with the variable
477 argument functions, try putting the gcc fixinclude file paths early in the
478 include path.
479
480 - If you operator-related compile errors or strange memory problems
481 (for example in deletion of string arrays), set wxUSE_GLOBAL_MEMORY_OPERATORS
482 and wxUSE_MEMORY_TRACING to 0 in setup.h, and recompile.
483
484 - If you get an internal compiler error in gcc, turn off optimisations.
485
486 - Some compilers, such as Sun C++, may give a lot of warnings about
487 virtual functions being hidden. Please ignore these, it's correct C++ syntax.
488 If you find any incorrect instances, though, such as a
489 missing 'const' in an overridden function, please let us know.
490
491 Other Notes
492 -----------
493
494 - Debugging mode is switched on by default in the makefiles, but using
495 configure will create a release build of the library by default: it's
496 recommended to use --with-debug_info and --with-debug_flag configure
497 switches while developing your application. To compile in non-debug
498 mode, remove the -D__WXDEBUG__ switch in make.env (or if using the
499 configure system, change --with-debug_flag to --without-debug_flag
500 and --with-debug_info to --without-debug_info in the makewxx11
501 script).
502
503 Bug reports
504 -----------
505
506 Please send bug reports with a description of your environment,
507 compiler and the error message(s) to the wxwin-developers mailing list at:
508
509 wx-dev@lists.wxwindows.org
510
511 Julian Smart, Robert Roebling and Vadim Zeitlin, February 2002.
512