docs/gtk/install.txt

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