]> git.saurik.com Git - wxWidgets.git/blob - docs/motif/install.txt
updated legalese regarding libtiff, libjpeg
[wxWidgets.git] / docs / motif / install.txt
1 wxWindows 2.1 for Motif 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 wxWindows you are
13 using (including the beta) and what compiler on what system. One
14 example: wxMotif 2.1 beta 6, egcs 1.1.1, Redhat 5.0
15
16 First steps
17 -----------
18
19 - Prerequisites: Motif 1.2 or above, or Lesstif
20 (not yet tested). Motif 2.0 and above may also be suitable.
21
22 - Download the appropriate .tgz archive, or alternatively the files
23 wx2_x_y_gen.zip and wx2_x_y_mot.zip. Download documentation in a
24 preferred format, such as wx2_x_y_htm.zip or wx2_x_y_pdf.zip.
25
26 - Make a directory such as ~/wx and unarchive the files into this
27 directory. If using the zip archives, use the -a option if available
28 to convert the ASCII files to Unix format. Don't worry about files being
29 overwritten: they should be identical anyway.
30
31 (See http://www.cdrom.com/pub/infozip/ if you don't have zip/unzip
32 already installed. Zip isn't the same as gzip!)
33
34 - It is recommended that you install bison and flex; using yacc
35 and lex may require tweaking of the makefiles. You also need
36 libXpm (see comments in the Notes section below) if you want to have
37 XPM support in wxWindows (recommended).
38
39 - You now have the option of using the configure-based system, or the simple
40 makefile system.
41
42 Using configure is the recommended way to build the library. If it doesn't
43 work for you for whatever reason, please report it (together with detailed
44 information about your platform and the (relevant part of) contents of
45 config.log file) to wxwin-developers@wx.dent.med.uni-muenchen.de.
46
47 COMPILING USING CONFIGURE
48 =========================
49
50 * The most simple case
51 -----------------------
52
53 If you compile wxWindows on Linux for the first time and don't like to read
54 install instructions just do (in the base dir):
55
56 > ./configure --with-motif
57 > make
58 > su <type root password>
59 > make install
60 > ldconfig
61 > exit
62
63 Afterwards you can continue with
64
65 > make
66 > su <type root password>
67 > make install
68 > ldconfig
69 > exit
70
71 If you want to remove wxWindows on Unix you can do this:
72
73 > su <type root password>
74 > make uninstall
75 > ldconfig
76 > exit
77
78 * The expert case
79 -----------------
80
81 If you want to do some more serious cross-platform programming with wxWindows,
82 such as for GTK and Motif, you can now build two complete libraries and use
83 them concurretly. For this end, you have to create a directory for each build
84 of wxWindows - you may also want to create different versions of wxWindows
85 and test them concurrently. Most typically, this would be a version configured
86 with --enable-debug_flag and one without. Note, that only one build can currently
87 be installed, so you'd have to use local version of the library for that purpose.
88 For building three versions (one GTK, one Motif and a debug version of the GTK
89 source) you'd do this:
90
91 md buildmotif
92 cd buildmotif
93 ../configure --with-motif
94 make
95 cd ..
96
97 md buildgtk
98 cd buildgtk
99 ../configure --with-gtk
100 make
101 cd ..
102
103 md buildgtkd
104 cd buildgtkd
105 ../configure --with-gtk --enable-debug_flag
106 make
107 cd ..
108
109 * The most simple errors
110 ------------------------
111
112 You get errors during compilation: The reason is that you probably have a broken
113 compiler, which includes almost everything that is called gcc. If you use gcc 2.8
114 you have to disable optimsation as the compiler will give up with an internal
115 compiler error.
116
117 If there is just any way for you to use egcs, use egcs. We cannot fix gcc.
118
119 You get immediate segfault when starting any sample or application: This is either
120 due to having compiled the library with different flags or options than your program -
121 typically you might have the __WXDEBUG__ option set for the library but not for your
122 program - or due to using a broken compiler (and its optimisation) such as GCC 2.8.
123
124 * The most simple program
125 -------------------------
126
127 Now create your super-application myfoo.app and compile anywhere with
128
129 g++ myfoo.cpp `wx-config --libs --cflags` -o myfoo
130
131 * General
132 -----------------------
133
134 The Unix variants of wxWindows use GNU configure. If you have problems with your
135 make use GNU make instead.
136
137 If you have general problems with installation, read my homepage at
138
139 http://wesley.informatik.uni-freiburg.de/~wxxt
140
141 for newest information. If you still don't have any success, please send a bug
142 report to one of our mailing lists (see my homepage) INCLUDING A DESCRIPTION OF
143 YOUR SYSTEM AND YOUR PROBLEM, SUCH AS YOUR VERSION OF GTK, WXGTK, WHAT DISTRIBUTION
144 YOU USE AND WHAT ERROR WAS REPORTED. I know this has no effect, but I tried...
145
146 * GUI libraries
147 -----------------------
148
149 wxWindows/Motif requires the Motif library to be installed on your system. As
150 an alternative, you may also use the free library "lesstif" which implements
151 most of the Motif API without the licence restrictions of Motif.
152
153 You can get the newest version of the Lesstif from the lesstif homepage at:
154
155 http://www.lesstif.org
156
157 * Additional libraries
158 -----------------------
159
160 wxWindows/Motif requires a thread library and X libraries known to work with threads.
161 This is the case on all commercial Unix-Variants and all Linux-Versions that are
162 based on glibc 2 except RedHat 5.0 which is broken in many aspects. As of writing
163 this, these Linux distributions have correct glibc 2 support:
164
165 - RedHat 5.1
166 - Debian 2.0
167 - Stampede
168 - DLD 6.0
169 - SuSE 6.0
170
171 You can disable thread support by running
172
173 ./configure "--disable-threads"
174 make
175 su <type root password>
176 make install
177 ldconfig
178 exit
179
180 NB: DO NOT COMPILE WXGTK WITH GCC AND THREADS, SINCE ALL PROGRAMS WILL
181 CRASH UPON START-UP! Just always use egcs and be happy.
182
183 * Building wxGTK on OS/2
184 --------------------------
185
186 Please send comments and question about the OS/2 installation
187 to Andrea Venturoli <a.ventu@flashnet.it> and patches to
188 the wxWindows mailing list.
189
190 You'll need OS/2 Warp (4.00FP#6), X-Free86/2 (3.3.3 or newer),
191 Lesstif (0.89.1 or newer), emx (0.9d fix 1), flex (2.5.4),
192 yacc (1.8), unix like shell, e.g. korn shell (5.2.13),
193 Autoconf (2.13), GNU file utilities (3.6),
194 GNU text utilities (1.3), GNU shell utilites (1.12), m4 (1.4),
195 sed (2.05), grep (2.0), Awk (3.0.3), GNU Make (3.76.1).
196
197 Open an OS/2 prompt and switch to the directory above.
198 First set some global environment variables we need:
199
200 SET CXXFLAGS=-Zmtd -D__ST_MT_ERRNO__
201 SET CFLAGS=-Zmtd -D__ST_MT_ERRNO__
202 SET OSTYPE=OS2X
203 SET COMSPEC=sh
204
205 Notice you can choose whatever you want, if you don't like OS2X.
206
207 Now, run autoconf in the main directory and in the samples, demos
208 and utils subdirectory. This will generate the OS/2 specific
209 versions of the configure scripts. Now run
210 configure --with-motif
211 as described above.
212
213 To verify Lesstif installation, configure will try to compile a
214 sample program that requires X headers/libraries to be either
215 available via C_INCLUDE_PATH and LIBRARY_PATH or you need to
216 explicitly set CFLAGS prior to running configure.
217
218 If you have pthreads library installed, it will be autodetected
219 and the library will be compiled with thread-support.
220
221 Note that configure assumes your flex will generate files named
222 "lexyy.c", not "lex.yy.c". If you have a version which does
223 generate "lex.yy.c", you need to manually change the generated
224 makefile.
225
226 * Building wxMotif on SGI
227 --------------------------
228
229 Using the SGI native compilers, it is recommended that you
230 also set CFLAGS and CXXFLAGS before running configure. These
231 should be set to :
232
233 CFLAGS="-mips3 -n32"
234 CXXFLAGS="-mips3 -n32"
235
236 This is essential if you want to use the resultant binaries
237 on any other machine than the one it was compiled on. If you
238 have a 64bit machine (Octane) you should also do this to ensure
239 you don't accidently build the libraries as 64bit (which is
240 untested).
241
242 The SGI native compiler support has only been tested on Irix 6.5.
243
244 * Create your configuration
245 -----------------------------
246
247 Usage:
248 ./configure options
249
250 If you want to use system's C and C++ compiler,
251 set environment variables CC and CCC as
252
253 % setenv CC cc
254 % setenv CCC CC
255 % ./configure options
256
257 to see all the options please use:
258
259 ./configure --help
260
261 The basic philosophy is that if you want to use different
262 configurations, like a debug and a release version,
263 or use the same source tree on different systems,
264 you have only to change the environment variable OSTYPE.
265 (Sadly this variable is not set by default on some systems
266 in some shells - on SGI's for example). So you will have to
267 set it there. This variable HAS to be set before starting
268 configure, so that it knows which system it tries to
269 configure for.
270
271 Configure will complain if the system variable OSTYPE has
272 not been defined. And Make in some circumstances as well...
273
274
275 * General options
276 -------------------
277
278 Given below are the commands to change the default behaviour,
279 i.e. if it says "--disable-threads" it means that threads
280 are enabled by default.
281
282 Many of the confiugre options have been thoroughly tested
283 in wxWindows snapshot 6, but not yet all (ODBC not).
284
285 You have to add --with-motif on platforms, where Motif is
286 not the default (on Linux, configure will deafult to GTK).
287
288 --without-gtk Don't use the GIMP ToolKit (GTK)
289
290 --with-motif Use either Motif or Lesstif
291 Configure will look for both.
292
293 The following options handle the kind of library you want to build.
294
295 --disable-threads Compile without thread support. Threads
296 support is also required for the
297 socket code to work.
298
299 --disable-shared Do not create shared libraries.
300
301 --disable-optimise Do not optimise the code. Can
302 sometimes be useful for debugging
303 and is required on some architectures
304 such as Sun with gcc 2.8.X which
305 would otherwise produce segvs.
306
307 --enable-profile Add profiling info to the object
308 files. Currently broken, I think.
309
310 --enable-no_rtti Enable compilation without creation of
311 C++ RTTI information in object files.
312 This will speed-up compilation and reduce
313 binary size.
314
315 --enable-no_exceptions Enable compilation without creation of
316 C++ exception information in object files.
317 This will speed-up compilation and reduce
318 binary size. Also fewer crashes during the
319 actual compilation...
320
321 --enable-no_deps Enable compilation without creation of
322 dependency information.
323
324 --enable-permissive Enable compilation without creation of
325 giving erros as soon as you compile with
326 Solaris ANSI-defying headers...
327
328 --enable-mem_tracing Add built-in memory tracing.
329
330 --enable-dmalloc Use the dmalloc memory debugger.
331 Read more at www.letters.com/dmalloc/
332
333 --enable-debug_info Add debug info to object files and
334 executables for use with debuggers
335 such as gdb (or its many frontends).
336
337 --enable-debug_flag Define __DEBUG__ and __WXDEBUG__ when
338 compiling. This enable wxWindows' very
339 useful internal debugging tricks (such
340 as automatically reporting illegal calls)
341 to work. Note that program and library
342 must be compiled with the same debug
343 options.
344
345 * Feature Options
346 -------------------
347
348 Many of the confiugre options have been thoroughly tested
349 in wxWindows snapshot 6, but not yet all (ODBC not).
350
351 When producing an executable that is linked statically with wxGTK
352 you'll be surprised at its immense size. This can sometimes be
353 drastically reduced by removing features from wxWindows that
354 are not used in your program. The most relevant such features
355 are
356
357 --without-libpng Disables PNG image format code.
358
359 --without-libjpeg Disables JPEG image format code.
360
361 { --without-odbc Disables ODBC code. Not yet. }
362
363 --disable-resources Disables the use of *.wxr type
364 resources.
365
366 --disable-threads Disables threads. Will also
367 disable sockets.
368
369 --disable-sockets Disables sockets.
370
371 --disable-dnd Disables Drag'n'Drop.
372
373 --disable-clipboard Disables Clipboard.
374
375 --disable-serial Disables object instance serialiasation.
376
377 --disable-streams Disables the wxStream classes.
378
379 --disable-file Disables the wxFile class.
380
381 --disable-textfile Disables the wxTextFile class.
382
383 --disable-intl Disables the internationalisation.
384
385 --disable-validators Disables validators.
386
387 --disable-accel Disables accel.
388
389 Apart from disabling certain features you can very often "strip"
390 the program of its debugging information resulting in a significant
391 reduction in size.
392
393 * Compiling
394 -------------
395
396 The following must be done in the base directory (e.g. ~/wxGTK
397 or ~/wxWin or whatever)
398
399 Now the makefiles are created (by configure) and you can compile
400 the library by typing:
401
402 make
403
404 make yourself some coffee, as it will take some time. On an old
405 386SX possibly two weeks. During compilation, you'll get a few
406 warning messages depending in your compiler.
407
408 If you want to be more selective, you can change into a specific
409 directiry and type "make" there.
410
411 Then you may install the library and it's header files under
412 /usr/local/include/wx and /usr/local/lib respectively. You
413 have to log in as root (i.e. run "su" and enter the root
414 password) and type
415
416 make install
417
418 You can remove any traces of wxWindows by typing
419
420 make uninstall
421
422 If you want to save disk space by removing unnecessary
423 object-files:
424
425 make clean
426
427 in the various directories will do the work for you.
428
429 * Creating a new Project
430 --------------------------
431
432 1) The first way uses the installed libraries and header files
433 automatically using wx-config
434
435 g++ myfoo.cpp `wx-config --libs` `wx-config --cflags` -o myfoo
436
437 Using this way, a make file for the minimal sample would look
438 like this
439
440 CC = g++
441
442 minimal: minimal.o
443 $(CC) -o minimal minimal.o `wx-config --libs`
444
445 minimal.o: minimal.cpp mondrian.xpm
446 $(CC) `wx-config --cflags` -c minimal.cpp -o minimal.o
447
448 clean:
449 rm -f *.o minimal
450
451 This is certain to become the standard way unless we decide
452 to sitch to tmake.
453
454 2) The other way creates a project within the source code
455 directories of wxWindows. For this endeavour, you'll need
456 GNU autoconf version 2.14 and add an entry to your Makefile.in
457 to the bottom of the configure.in script and run autoconf
458 and configure before you can type make.
459
460 * Further notes by Julian Smart
461 ---------------------------------
462
463 - You may find the following script useful for compiling wxMotif,
464 especially if installing from zips (which don't preserve file
465 permissions). Make this script executable with the command
466 chmod a+x makewxmotif.
467
468 -------:x-----Cut here-----:x-----
469 # makewxmotif
470 # Sets permissions (in case we extracted wxMotif from zip files)
471 # and makes wxMotif.
472 # Call from top-level wxWindows directory.
473 # Note that this uses standard (but commonly-used) configure options;
474 # if you're feeling brave, you may wish to compile with threads:
475 # if they're not supported by the target platform, they will be disabled
476 # anyhow
477 # -- Julian Smart
478 chmod a+x configure config.sub config.guess
479 ./configure --with-shared --with-motif --without-gtk --with-debug_flag --with-debug_info --enable-debug --without-threads --without-sockets --without-odbc
480 make
481 -------:x-----Cut here-----:x-----
482
483 This script will build wxMotif using shared libraries. If you want to build
484 a static wxWindows library, use --disable-shared.
485
486 COMPILING USING MAKEFILES
487 =========================
488
489 - Copy the file include/wx/motif/setup0.h to include/wx/motif/setup.h and
490 edit it if you wish to enable/disable some library features
491
492 - Choose a .env file from src/makeenvs that matches your
493 environment, and copy it to src/make.env. These are the
494 settings read by wxWindows for Motif makefiles.
495
496 - Edit src/make.env to change options according to your local
497 environment. In particular, change WXDIR to where wxWindows is
498 found on your system, or set the WXWIN environment variable
499 before compilation, e.g.:
500
501 export WXWIN=/home/jacs/wx2
502
503 Please feel free to contribute settings files for your environment.
504
505 - Change directory to src/motif and type:
506
507 make -f makefile.unx motif
508
509 This should make the library libwx_motif.a in the lib
510 directory. Note that this makefile system does not build shared
511 libraries, only static ones (that is, the wxWindows library will be
512 linked statically; to see remaining dependencies on shared libraries,
513 type e.g. ldd minimal_motif).
514
515 - Make a sample, such as the minimal sample:
516
517 cd samples/minimal
518 make -f makefile.unx motif
519
520 and run the resulting minimal_motif binary.
521
522 Troubleshooting
523 ---------------
524
525 - If you have trouble compiling the file y_tab.c, or have strange
526 linking errors, check whether you're using a C or C++ compiler for this file.
527 You should specify a C compiler in the CCLEX variable in src/make.env.
528 You could also try using bison and flex instead of yacc and
529 lex.
530
531 - Solaris compilation with gcc: if the compiler has problems with the variable argument
532 functions, try putting the gcc fixinclude file paths early in the include
533 path.
534
535 - If you operator-related compile errors or strange memory problems
536 (for example in deletion of string arrays), set wxUSE_GLOBAL_MEMORY_OPERATORS
537 and wxUSE_MEMORY_TRACING to 0 in setup.h, and recompile.
538
539 - If you get an internal compiler error in gcc, turn off optimisations.
540
541 - Problems with XtDestroyWidget crashing in ~wxWindow have been
542 reported on SGI IRIX 6.4. This has not yet been resolved, so
543 any advice here would be very welcome. See bugs.txt for a
544 possible temporary workaround (comment out the final
545 XtDestroyWidget from ~wxWindow in window.cpp).
546
547 - If you use flex and bison instead of yacc and lex, you may need
548 to change the relevant part of src/motif/makefile.unx to read:
549
550 ../common/y_tab.c: ../common/parser.y
551 $(YACC) ../common/parser.y
552 mv ../common/parser.tab.c ../common/y_tab.c
553
554 (the 'mv' command needs to be changed)
555
556 - Some compilers, such as Sun C++, may give a lot of warnings about
557 virtual functions being hidden. Please ignore these, it's correct C++ syntax.
558 If you find any incorrect instances, though, such as a
559 missing 'const' in an overridden function, please let us know.
560
561 Other Notes
562 -----------
563
564 - Debugging mode is switched on by default in the makefiles, but using
565 configure will create a release build of the library by default: it's
566 recommended to use --with-debug_info and --with-debug_flag configure
567 switches while developing your application. To compile in non-debug
568 mode, remove the -D__WXDEBUG__ switch in make.env (or if using the
569 configure system, change --with-debug_flag to --without_debug_flag
570 and --with-debug_info to --without-debug_info in the makewxmotif
571 script).
572
573 - Some classes can be switched off in include/wx/motif/setup.h,
574 if you are having trouble with a particular file. However,
575 I'd prefer you to fix the problem and send the fix to me :-) or at
576 least let me know about it.
577
578 - Thread support is switched off by default in setup.h (wxUSE_THREADS)
579 because standard Unices often do not have the necessary thread library
580 installed. Please see ../docs/gtk/install.txt for more details on this.
581 The systems for which thread support is known to work are Linux with libc6
582 (a.k.a. glibc2), Solaris 2.5 and 2.6 (provided that X libraries are thread
583 safe) and, to some extent, FreeBSD 2.8 and 3.1 (any feedback on thread
584 support under FreeBSD as well as the systems not mentioned here would be
585 appreciated).
586
587 - If you run into problems with a missing X11/Xpm.h header, you
588 need to install the XPM package. It can be obtained from:
589
590 ftp://ftp.x.org/contrib/libraries/xpm-3.4k.tar.gz
591 http://sunfreeware.com
592
593 You may need to modify make.env to add -I and -L options pointing to where Xpm
594 is installed and possibly change bitmap.cpp to
595 include <xpm.h> instead of <X11/xpm.h>
596
597 Alternatively, edit include/wx/motif/setup.h, set wxUSE_XPM
598 to 0, and recompile. You will not be able to load any XPMs,
599 though (currently the only supported colour bitmap format).
600
601 Bug reports
602 -----------
603
604 Please send bug reports with a description of your environment,
605 compiler and the error message(s) to the wxwin-developers mailing list at:
606
607 wxwin-developers@wx.dent.med.uni-muenchen.de
608
609 Julian Smart, Robert Roebling and Vadim Zeitlin, November 1999.
610