docs/gtk/install.txt

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