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