]> git.saurik.com Git - wxWidgets.git/blame - docs/gtk/install.txt
minor cleanup (doc typos fixed, removed tabs)
[wxWidgets.git] / docs / gtk / install.txt
CommitLineData
e8332ccf
JS
1wxWidgets 2.5 for GTK+ installation
2-----------------------------------
8e1e6fac 3
b55a176b 4IMPORTANT NOTE:
8e1e6fac 5
b55a176b
JS
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
fc2171bd 12 When sending bug reports tell us what version of wxWidgets you are
b55a176b 13 using (including the beta) and what compiler on what system. One
e8332ccf 14 example: wxGTK 2.6.0, gcc 2.95.4, Redhat 6.2
b55a176b
JS
15
16* The simplest case
17-------------------
c98f0421 18
fc2171bd 19If you compile wxWidgets on Linux for the first time and don't like to read
91b8de8d 20install instructions just do (in the base dir):
c98f0421 21
e8332ccf
JS
22> mkdir buildgtk
23> cd buildgtk
24> ../configure --with-gtk
9b61f868
RR
25> make
26> su <type root password>
27> make install
28> ldconfig
29> exit
034be888 30
e8332ccf 31Afterwards you can continue with:
9b61f868
RR
32
33> make
34> su <type root password>
35> make install
36> ldconfig
37> exit
4dcaf11a 38
e8332ccf
JS
39(If you don't do the 'make install' part, you can still
40use the libraries from the buildgtk directory, but they
41will not be available to other users.)
42
fc2171bd 43If you want to remove wxWidgets on Unix you can do this:
8e1e6fac 44
9b61f868
RR
45> su <type root password>
46> make uninstall
47> ldconfig
48> exit
cf7a7e13 49
e8332ccf
JS
50Note that by default, GTK+ 2 is used. GTK+ 1 can be specified
51with --disable-gtk2.
52
53* The Unicode case
54------------------
0dd6e08c 55
75fcbf8e
VS
56wxGTK has support for the new version 2.0.X of GTK+ since version 2.4.0.
57This means that wxGTK apps can now make use Unicode as the underlying encoding
58for all text operations. This is a very fundamental change and will need time
e8332ccf 59to stabilize, so be careful. After installing a recent version of GTK+
75fcbf8e 602.0, do this
0dd6e08c 61
e8332ccf
JS
62> mkdir buildgtk
63> cd buildgtk
64> ../configure --with-gtk --enable-gtk2 --enable-unicode
0dd6e08c
RR
65> make
66> su <type root password>
67> make install
68> ldconfig
69> exit
70
71If you are adventurous, you can install the FcConfig 2.0 package
72and the Pango library from CVS (or a very recent snapshot from
73the upcoming 1.2 series) and set do "export GDK_USE_XFT=1" so
74that the display as well as the printing code will use render
75using the same FreeType code even for Far Eastern encodings.
76
77Expect problems.
78
2b62ab35
RR
79* The expert case
80-----------------
81
fc2171bd 82If you want to do some more serious cross-platform programming with wxWidgets,
e8332ccf
JS
83such as for GTK+ and Motif, you can now build two complete libraries and use
84them concurrently. To do this, create a separate directory for each build
fc2171bd 85of wxWidgets - you may also want to create different versions of wxWidgets
2e1e7f9d 86and test them concurrently. Most typically, this would be a version configured
2b5f62a0 87with --enable-debug and one without. Note, that only one build can
e8332ccf
JS
88currently be installed with 'make install', so you'd have to use local version of
89the library for that purpose.
2edb0bde 90
e8332ccf 91For building three versions (one GTK+, one Motif and a debug version of the GTK
51d55e1c 92source) you'd do this:
2b62ab35
RR
93
94md buildmotif
95cd buildmotif
96../configure --with-motif
97make
98cd ..
99
100md buildgtk
101cd buildgtk
102../configure --with-gtk
103make
104cd ..
105
106md buildgtkd
107cd buildgtkd
2b5f62a0 108../configure --with-gtk --enable-debug
2b62ab35
RR
109make
110cd ..
111
b55a176b
JS
112* The simplest errors
113---------------------
2a29700e 114
2e1e7f9d
VZ
115For any configure errors: please look at config.log file which was generated
116during configure run, it usually contains some useful information.
117
e8332ccf 118configure reports, that you don't have GTK+ 1.2 installed although you are
2e1e7f9d 119very sure you have. Well, you have installed it, but you also have another
e8332ccf 120version of the GTK+ installed, which you may need to remove including other
2e1e7f9d
VZ
121versions of glib (and its headers). Or maybe you installed it in non default
122location and configure can't find it there, so please check that your PATH
123variable includes the path to the correct gtk-config. Also check that your
124LD_LIBRARY_PATH or equivalent variable contains the path to GTK+ libraries if
125they were installed in a non default location.
126
127You get errors from make: please use GNU make instead of the native make
fc2171bd 128program. Currently wxWidgets can be built only with GNU make, BSD make and
2e1e7f9d
VZ
129Solaris make. Other versions might work or not (any which don't have VPATH
130support definitely won't).
131
132You get errors during compilation: The reason is that you probably have a
b55a176b
JS
133broken compiler. GCC 2.8 and earlier versions and egcs are likely to cause
134problems due to incomplete support for C++ and optimisation bugs. Best to use
135GCC 2.95 or later.
2e1e7f9d
VZ
136
137You get immediate segfault when starting any sample or application: This is
138either due to having compiled the library with different flags or options than
139your program - typically you might have the __WXDEBUG__ option set for the
b55a176b
JS
140library but not for your program - or due to using a compiler with optimisation
141bugs.
2e1e7f9d
VZ
142
143Linker complains about missing PROIO_yy_flex_alloc and similar symbols: you
144probably have an old version of flex, 2.5.4 is recommended.
3502e687 145
b55a176b
JS
146* The simplest program
147----------------------
2a29700e 148
b55a176b 149Now create your super-application myfoo.cpp and compile anywhere with
cf7a7e13 150
b55a176b 151g++ myfoo.cpp `wx-config --libs --cxxflags` -o myfoo
c98f0421
RR
152
153* General
b55a176b 154---------
c98f0421 155
fc2171bd 156The Unix variants of wxWidgets use GNU configure. If you have problems with
b55a176b 157your make use GNU make instead.
c98f0421 158
2e1e7f9d 159If you have general problems with installation, read my homepage at
c98f0421 160
b55a176b 161 http://wesley.informatik.uni-freiburg.de/~wxxt/
2e1e7f9d
VZ
162
163for newest information. If you still don't have any success, please send a bug
164report to one of our mailing lists (see my homepage) INCLUDING A DESCRIPTION OF
b55a176b
JS
165YOUR SYSTEM AND YOUR PROBLEM, SUCH AS YOUR VERSION OF GTK, WXGTK, WHAT
166DISTRIBUTION YOU USE AND WHAT ERROR WAS REPORTED. I know this has no effect,
167but I tried...
c98f0421
RR
168
169* GUI libraries
b55a176b 170---------------
c98f0421 171
e8332ccf 172wxWidgets/GTK+ requires the GTK+ library to be installed on your system. It has
2edb0bde 173to be a stable version, preferably version 1.2.10 (at least 1.2.3 is required,
2e1e7f9d 1741.2.7 is strongly recommended).
91b8de8d 175
e8332ccf 176You can get the newest version of the GTK+ from the GTK+ homepage at:
c98f0421 177
c98f0421 178 http://www.gtk.org
2e1e7f9d
VZ
179
180We also mirror GTK+ at my ftp site. You'll find information about downloading
91b8de8d 181at my homepage.
2e1e7f9d 182
c98f0421 183* Additional libraries
b55a176b 184----------------------
c98f0421 185
fc2171bd 186wxWidgets/Gtk requires a thread library and X libraries known to work with
b55a176b
JS
187threads. This is the case on all commercial Unix-Variants and all
188Linux-Versions that are based on glibc 2 except RedHat 5.0 which is broken in
75fcbf8e
VS
189many aspects. As of writing this, virtually all Linux distributions have
190correct glibc 2 support.
58614078 191
2e1e7f9d
VZ
192You can disable thread support by running
193
194./configure --disable-threads
58614078 195make
034be888 196su <type root password>
8710cf5c 197make install
034be888
RR
198ldconfig
199exit
2e1e7f9d 200
91b8de8d 201* Building wxGTK on OS/2
b55a176b 202------------------------
c98f0421 203
91b8de8d 204Please send comments and question about the OS/2 installation
d21c1b56 205to Stefan Neis <Stefan.Neis@t-online.de> and patches to
fc2171bd 206the wxWidgets mailing list.
c98f0421 207
d21c1b56
SN
208In the following list, the version numbers indicate the configuration that
209was actually used by myself, newer version should cause no problems and
210even older ones are expected to work most of the time.
c98f0421 211
d21c1b56
SN
212You'll need OS/2 Warp (4.51) or eCS(1.0), X-Free86/2 (3.3.6 or newer),
213GTK+ (1.2.5 or newer), emx (0.9d fix 4), flex (2.5.4), yacc (1.8) or
214bison (1.25), a Unix like shell (pdksh-5.2.14 or ash), Autoconf (2.57),
215GNU file utilities (3.13), GNU text utilities (1.19),
216GNU shell utilites (1.12), m4 (1.4), sed (2.05), grep (2.0), Awk (3.0.3),
217GNU Make (3.75).
91b8de8d 218
d21c1b56
SN
219Preferably, you should have Posix/2 installed and C(PLUS)_INCLUDE_PATH and
220LIBRARY_PATH set up accordingly, however, wxGTK will even work without it.
221Presence of Posix/2 will be auto-detected.
ea0dbf30 222
d21c1b56
SN
223Open an OS/2 prompt and switch to the directory above.
224Set MAKESHELL (and depending on your installation also INSTALL, for me
225it tends to try to use the system's tcpip\pcomos\install.exe which causes
226problems...) to a Unix like shell, e.g.
227SET MAKESHELL=ash
228
229Be warned that depending on the precise version of your make, the
230variable that needs to be set might be MAKE_SHELL instead of MAKESHELL.
231If you have a really deficient version of GNU make, it might even be
232necessary to set SHELL or even COMSPEC to a unix like shell as well.
233
234Notice that the delivered configure scripts are fully OS/2 aware, so you
235can simply run
236 ash -c "configure --with-gtk"
237and make and possibly make install as described above.
9f2d09aa 238
91b8de8d 239* Building wxGTK on SGI
b55a176b 240-----------------------
c98f0421
RR
241
242Using the SGI native compilers, it is recommended that you
2e1e7f9d 243also set CFLAGS and CXXFLAGS before running configure. These
c98f0421
RR
244should be set to :
245
2e1e7f9d 246CFLAGS="-mips3 -n32"
c98f0421
RR
247CXXFLAGS="-mips3 -n32"
248
2e1e7f9d
VZ
249This is essential if you want to use the resultant binaries
250on any other machine than the one it was compiled on. If you
251have a 64bit machine (Octane) you should also do this to ensure
252you don't accidently build the libraries as 64bit (which is
c98f0421
RR
253untested).
254
255The SGI native compiler support has only been tested on Irix 6.5.
256
91b8de8d 257* Create your configuration
b55a176b 258---------------------------
91b8de8d
RR
259
260Usage:
2e1e7f9d 261 ./configure options
91b8de8d
RR
262
263If you want to use system's C and C++ compiler,
264set environment variables CC and CCC as
265
2e1e7f9d 266 % setenv CC cc
b55a176b
JS
267 % setenv CXX CC
268 % ./configure [options]
91b8de8d 269
c98f0421
RR
270to see all the options please use:
271
2e1e7f9d 272 ./configure --help
c98f0421 273
fc2171bd
JS
274It is recommended to build wxWidgets in another directory (maybe a
275subdirectory of your wxWidgets installation) as this allows you to
2e1e7f9d
VZ
276have multiple configurations (for example, debug and release or GTK
277and Motif) simultaneously.
c98f0421
RR
278
279
280* General options
b55a176b 281-----------------
c98f0421 282
77c85c2b
RR
283Given below are the commands to change the default behaviour,
284i.e. if it says "--disable-threads" it means that threads
285are enabled by default.
286
cf7a7e13
RR
287Normally, you won't have to choose a toolkit, because when
288you download wxGTK, it will default to --with-gtk etc. But
2e1e7f9d 289if you use all of our CVS repository you have to choose a
cf7a7e13 290toolkit. You must do this by running configure with either of:
c98f0421 291
e8332ccf 292 --with-gtk Use the GIMP ToolKit (GTK+). Default.
2e1e7f9d
VZ
293
294 --with-motif Use either Motif or Lesstif
295 Configure will look for both.
c98f0421
RR
296
297The following options handle the kind of library you want to build.
298
2e1e7f9d 299 --disable-threads Compile without thread support.
c98f0421 300
2e1e7f9d 301 --disable-shared Do not create shared libraries, but
4b6b4dfc 302 build static libraries instead.
bbeb6c2b 303
fc2171bd 304 --enable-monolithic Build wxWidgets as single library instead
75fcbf8e 305 of as several smaller libraries (which is
fc2171bd 306 the default since wxWidgets 2.5.0).
75fcbf8e 307
2e1e7f9d
VZ
308 --disable-optimise Do not optimise the code. Can
309 sometimes be useful for debugging
4b6b4dfc
RR
310 and is required on some architectures
311 such as Sun with gcc 2.8.X which
312 would otherwise produce segvs.
c98f0421 313
e8332ccf
JS
314 --enable-unicode Enable Unicode support.
315
316 --enable-gtk2 Compiling using GTK+ 2 (the default).
317
2e1e7f9d
VZ
318 --enable-profile Add profiling info to the object
319 files. Currently broken, I think.
320
321 --enable-no_rtti Enable compilation without creation of
322 C++ RTTI information in object files.
323 This will speed-up compilation and reduce
4b6b4dfc 324 binary size.
2e1e7f9d
VZ
325
326 --enable-no_exceptions Enable compilation without creation of
327 C++ exception information in object files.
328 This will speed-up compilation and reduce
4b6b4dfc
RR
329 binary size. Also fewer crashes during the
330 actual compilation...
2e1e7f9d
VZ
331
332 --enable-no_deps Enable compilation without creation of
333 dependency information.
334
2edb0bde
VZ
335 --enable-permissive Enable compilation without checking for strict
336 ANSI conformance. Useful to prevent the build
337 dying with errors as soon as you compile with
2e1e7f9d
VZ
338 Solaris' ANSI-defying headers.
339
340 --enable-mem_tracing Add built-in memory tracing.
341
342 --enable-dmalloc Use the dmalloc memory debugger.
343 Read more at www.letters.com/dmalloc/
344
345 --enable-debug_info Add debug info to object files and
346 executables for use with debuggers
347 such as gdb (or its many frontends).
348
349 --enable-debug_flag Define __DEBUG__ and __WXDEBUG__ when
fc2171bd 350 compiling. This enable wxWidgets' very
4b6b4dfc
RR
351 useful internal debugging tricks (such
352 as automatically reporting illegal calls)
353 to work. Note that program and library
2e1e7f9d 354 must be compiled with the same debug
4b6b4dfc 355 options.
c98f0421 356
2b5f62a0
VZ
357 --enable-debug Same as --enable-debug_info and
358 --enable-debug_flag together. Unless you have
359 some very specific needs, you should use this
360 option instead of --enable-debug_info/flag ones
361 separately.
362
c98f0421 363* Feature Options
b55a176b 364-----------------
c98f0421 365
3cdda6cd
RR
366When producing an executable that is linked statically with wxGTK
367you'll be surprised at its immense size. This can sometimes be
fc2171bd 368drastically reduced by removing features from wxWidgets that
3cdda6cd
RR
369are not used in your program. The most relevant such features
370are
371
2e1e7f9d 372 --with-odbc Enables ODBC code. This is disabled
cc977e5f 373 by default because iODBC is under the
2e1e7f9d 374 L-GPL license which is less liberal than
fc2171bd 375 wxWidgets license.
2e1e7f9d
VZ
376
377 --without-libpng Disables PNG image format code.
378
379 --without-libjpeg Disables JPEG image format code.
380
381 --without-libtiff Disables TIFF image format code.
382
75fcbf8e
VS
383 --without-expat Disable XML classes based on Expat parser.
384
2e1e7f9d
VZ
385 --disable-pnm Disables PNM image format code.
386
387 --disable-gif Disables GIF image format code.
388
389 --disable-pcx Disables PCX image format code.
390
391 --disable-iff Disables IFF image format code.
392
393 --disable-resources Disables the use of *.wxr type resources.
394
395 --disable-threads Disables threads. Will also disable sockets.
396
397 --disable-sockets Disables sockets.
398
399 --disable-dnd Disables Drag'n'Drop.
400
401 --disable-clipboard Disables Clipboard.
402
2edb0bde 403 --disable-serial Disables object instance serialisation.
2e1e7f9d
VZ
404
405 --disable-streams Disables the wxStream classes.
406
407 --disable-file Disables the wxFile class.
408
409 --disable-textfile Disables the wxTextFile class.
410
411 --disable-intl Disables the internationalisation.
412
413 --disable-validators Disables validators.
414
415 --disable-accel Disables accelerators support.
416
3cdda6cd
RR
417Apart from disabling certain features you can very often "strip"
418the program of its debugging information resulting in a significant
419reduction in size.
c98f0421 420
75fcbf8e
VS
421Please see the output of "./configure --help" for comprehensive list
422of all configurable options.
423
424
c98f0421 425* Compiling
b55a176b 426-----------
c98f0421
RR
427
428The following must be done in the base directory (e.g. ~/wxGTK
cf7a7e13 429or ~/wxWin or whatever)
c98f0421 430
2e1e7f9d 431Now the makefiles are created (by configure) and you can compile
8710cf5c 432the library by typing:
c98f0421 433
2e1e7f9d 434 make
c98f0421 435
8710cf5c 436make yourself some coffee, as it will take some time. On an old
2e1e7f9d 437386SX possibly two weeks. During compilation, you'll get a few
3cdda6cd 438warning messages depending in your compiler.
c98f0421 439
51d55e1c 440If you want to be more selective, you can change into a specific
2edb0bde 441directory and type "make" there.
c98f0421 442
2edb0bde 443Then you may install the library and its header files under
cf7a7e13
RR
444/usr/local/include/wx and /usr/local/lib respectively. You
445have to log in as root (i.e. run "su" and enter the root
446password) and type
447
2e1e7f9d 448 make install
c98f0421 449
fc2171bd 450You can remove any traces of wxWidgets by typing
c98f0421 451
8e1e6fac 452 make uninstall
2e1e7f9d 453
3cdda6cd 454If you want to save disk space by removing unnecessary
c98f0421
RR
455object-files:
456
2e1e7f9d 457make clean
c98f0421 458
3cdda6cd 459in the various directories will do the work for you.
c98f0421
RR
460
461* Creating a new Project
462--------------------------
463
f3cb6592
RR
4641) The first way uses the installed libraries and header files
465automatically using wx-config
466
b55a176b 467g++ myfoo.cpp `wx-config --cxxflags --libs` -o myfoo
f3cb6592
RR
468
469Using this way, a make file for the minimal sample would look
470like this
471
cc977e5f 472CC = gcc
f3cb6592
RR
473
474minimal: minimal.o
2e1e7f9d 475 $(CC) -o minimal minimal.o `wx-config --libs`
f3cb6592
RR
476
477minimal.o: minimal.cpp mondrian.xpm
b55a176b 478 $(CC) `wx-config --cxxflags` -c minimal.cpp -o minimal.o
f3cb6592 479
2e1e7f9d 480clean:
f3cb6592
RR
481 rm -f *.o minimal
482
483This is certain to become the standard way unless we decide
2edb0bde 484to stick to tmake.
f3cb6592 485
fc2171bd 486If your application uses only some of wxWidgets libraries, you can
75fcbf8e
VS
487specify required libraries when running wx-config. For example,
488`wx-config --libs=html,core` will only output link command to link
489with libraries required by core GUI classes and wxHTML classes. See
490the manual for more information on the libraries.
491
2e1e7f9d 4922) The other way creates a project within the source code
fc2171bd 493directories of wxWidgets. For this endeavour, you'll need
79144b8a
RR
494GNU autoconf version 2.14 and add an entry to your Makefile.in
495to the bottom of the configure.in script and run autoconf
496and configure before you can type make.
cf7a7e13 497
91b8de8d 498----------------------
c98f0421
RR
499
500In the hope that it will be useful,
501
510fc784
RR
502 Robert Roebling
503