docs/gtk/install.txt

   1
   2   !!! When sending bug reports tell us what version of wxWindows you are
   3       using (including the beta) and what compiler on what system. One
   4       example: wxGTK 2.1 beta 6, egcs 1.1.1, Redhat 5.0 !!!
   5
   6 * The most simple case
   7 -----------------------
   8
   9 If you compile wxWindows on Linux for the first time and don't like to read
  10 install instructions just do (in the base dir):
  11
  12 > ./configure --with-gtk
  13 > make
  14 > su <type root password>
  15 > make install
  16 > ldconfig
  17 > exit
  18
  19 Afterwards you can continue with
  20
  21 > make
  22 > su <type root password>
  23 > make install
  24 > ldconfig
  25 > exit
  26
  27 If you want to remove wxWindows on Unix you can do this:
  28
  29 > su <type root password>
  30 > make uninstall
  31 > ldconfig
  32 > exit
  33
  34 * The expert case
  35 -----------------
  36
  37 If you want to do some more serious cross-platform programming with wxWindows,
  38 such as for GTK and Motif, you can now build two complete libraries and use
  39 them concurretly. For this end, you have to create a directory for each build
  40 of wxWindows - you may also want to create different versions of wxWindows
  41 and test them concurrently. Most typically, this would be a version configured
  42 with --enable-debug_flag and one without. Note, that only one build can currently
  43 be installed, so you'd have to use local version of the library for that purpose.
  44 For building three versions (one GTK, one Motif and a debug version of the GTK
  45 source) you'd do this:
  46
  47 md buildmotif
  48 cd buildmotif
  49 ../configure --with-motif
  50 make
  51 cd ..
  52
  53 md buildgtk
  54 cd buildgtk
  55 ../configure --with-gtk
  56 make
  57 cd ..
  58
  59 md buildgtkd
  60 cd buildgtkd
  61 ../configure --with-gtk --enable-debug_flag
  62 make
  63 cd ..
  64
  65 * The most simple errors
  66 ------------------------
  67
  68 configure reports, that you don't have GTK 1.2 installed although you are
  69 very sure you have. Well, you have installed it, but you also have another
  70 version of the GTK installed, which you may need to remove including other
  71 versions of glib (and its headers). Also, look for the PATH variable and check
  72 if it includes the path to the correct gtk-config! The check your LDPATH if it
  73 points to the correct library. There is no way to compile wxGTK if configure
  74 doesn't pass this test as all this test does is compile and link a GTK program.
  75
  76 You get errors during compilation: The reason is that you probably have a broken
  77 compiler, which includes almost everything that is called gcc. If you use gcc 2.8
  78 you have to disable optimsation as the compiler will give up with an internal
  79 compiler error.
  80
  81 If there is just any way for you to use egcs, use egcs. We cannot fix gcc.
  82
  83 You get immediate segfault when starting any sample or application: This is either
  84 due to having compiled the library with different flags or options than your program -
  85 typically you might have the __WXDEBUG__ option set for the library but not for your
  86 program - or due to using a broken compiler (and its optimisation) such as GCC 2.8.
  87
  88 * The most simple program
  89 -------------------------
  90
  91 Now create your super-application myfoo.app and compile anywhere with
  92
  93 g++ myfoo.cpp `wx-config --libs --cflags` -o myfoo
  94
  95 * General
  96 -----------------------
  97
  98 The Unix variants of wxWindows use GNU configure. If you have problems with your
  99 make use GNU make instead.
 100
 101 If you have general problems with installation, read my homepage at
 102
 103   http://wesley.informatik.uni-freiburg.de/~wxxt
 104
 105 for newest information. If you still don't have any success, please send a bug
 106 report to one of our mailing lists (see my homepage) INCLUDING A DESCRIPTION OF
 107 YOUR SYSTEM AND YOUR PROBLEM, SUCH AS YOUR VERSION OF GTK, WXGTK, WHAT DISTRIBUTION
 108 YOU USE AND WHAT ERROR WAS REPORTED. I know this has no effect, but I tried...
 109
 110 * GUI libraries
 111 -----------------------
 112
 113 wxWindows/GTK requires the GTK+ library to be installed on your system. It has to
 114 be a stable version, preferebly version 1.2.3.
 115
 116 You can get the newest version of the GTK+ from the GTK homepage at:
 117
 118   http://www.gtk.org
 119
 120 We also mirror GTK+ 1.2.3 at my ftp site. You'll find information about downloading
 121 at my homepage.
 122
 123 * Additional libraries
 124 -----------------------
 125
 126 wxWindows/Gtk requires a thread library and X libraries known to work with threads.
 127 This is the case on all commercial Unix-Variants and all Linux-Versions that are
 128 based on glibc 2 except RedHat 5.0 which is broken in many aspects. As of writing
 129 this, these Linux distributions have correct glibc 2 support:
 130
 131  - RedHat 5.1
 132  - Debian 2.0
 133  - Stampede
 134  - DLD 6.0
 135  - SuSE 6.0
 136
 137 You can disable thread support by running
 138
 139 ./configure "--disable-threads"
 140 make
 141 su <type root password>
 142 make install
 143 ldconfig
 144 exit
 145
 146 NB: DO NOT COMPILE WXGTK WITH GCC AND THREADS, SINCE ALL PROGRAMS WILL CRASH UPON
 147 START-UP! Just always use egcs and be happy.
 148
 149 * Building wxGTK on OS/2
 150 --------------------------
 151
 152 Please send comments and question about the OS/2 installation
 153 to Andrea Venturoli <a.ventu@flashnet.it> and patches to
 154 make the installation work (better) to me (Robert Roebling).
 155
 156 You'll need OS/2 Warp (4.00FP#6), X-Free86/2 (3.3.3),
 157 gtk+ (?), emx (0.9d fix 1), flex (2.5.4), yacc (1.8),
 158 korn shell (5.2.13), Autoconf (?),  GNU file utilities (3.6),
 159 GNU text utilities (1.3), GNU shell utilites (1.12), m4 (1.4),
 160 sed (2.05), grep (2.0), Awk (3.0.3), GNU Make (3.76.1).
 161
 162 Open an OS/2 prompt and switch to the directory above.
 163 First set some global environment variables we need:
 164
 165 SET CXXFLAGS=-Zmtd -D__ST_MT_ERRNO__
 166 SET OSTYPE=OS2X
 167 SET COMSPEC=sh
 168
 169 Notice you can choose whatever you want, if you don't like OS2X.
 170
 171 * Building wxGTK on SGI
 172 --------------------------
 173
 174 Using the SGI native compilers, it is recommended that you
 175 also set CFLAGS and CXXFLAGS before running configure. These
 176 should be set to :
 177
 178 CFLAGS="-mips3 -n32"
 179 CXXFLAGS="-mips3 -n32"
 180
 181 This is essential if you want to use the resultant binaries
 182 on any other machine than the one it was compiled on. If you
 183 have a 64bit machine (Octane) you should also do this to ensure
 184 you don't accidently build the libraries as 64bit (which is
 185 untested).
 186
 187 The SGI native compiler support has only been tested on Irix 6.5.
 188
 189 * Create your configuration
 190 -----------------------------
 191
 192 Usage:
 193         ./configure options
 194
 195 If you want to use system's C and C++ compiler,
 196 set environment variables CC and CCC as
 197
 198         % setenv CC cc
 199         % setenv CCC CC
 200         % ./configure options
 201
 202 to see all the options please use:
 203
 204         ./configure --help
 205
 206 The basic philosophy is that if you want to use different
 207 configurations, like a debug and a release version,
 208 or use the same source tree on different systems,
 209 you have only to change the environment variable OSTYPE.
 210 (Sadly this variable is not set by default on some systems
 211 in some shells - on SGI's for example). So you will have to
 212 set it there. This variable HAS to be set before starting
 213 configure, so that it knows which system it tries to
 214 configure for.
 215
 216 Configure will complain if the system variable OSTYPE has
 217 not been defined. And Make in some circumstances as well...
 218
 219
 220 * General options
 221 -------------------
 222
 223 Given below are the commands to change the default behaviour,
 224 i.e. if it says "--disable-threads" it means that threads
 225 are enabled by default.
 226
 227 Many of the confiugre options have been thoroughly tested
 228 in wxWindows snapshot 6, but not yet all (ODBC not).
 229
 230 Normally, you won't have to choose a toolkit, because when
 231 you download wxGTK, it will default to --with-gtk etc. But
 232 if you use all of our CVS repository you have to choose a
 233 toolkit. You must do this by running configure with either of:
 234
 235         --without-gtk            Don't use the GIMP ToolKit (GTK)
 236
 237         --with-motif             Use either Motif or Lesstif
 238                                  Configure will look for both.
 239
 240 The following options handle the kind of library you want to build.
 241
 242         --disable-threads       Compile without thread support. Threads
 243                                 support is also required for the
 244                                 socket code to work.
 245
 246         --disable-shared        Do not create shared libraries.
 247
 248         --disable-optimise      Do not optimise the code. Can
 249                                 sometimes be useful for debugging
 250                                 and is required on some architectures
 251                                 such as Sun with gcc 2.8.X which
 252                                 would otherwise produce segvs.
 253
 254         --enable-profile        Add profiling info to the object
 255                                 files. Currently broken, I think.
 256
 257         --enable-no_rtti        Enable compilation without creation of
 258                                 C++ RTTI information in object files.
 259                                 This will speed-up compilation and reduce
 260                                 binary size.
 261
 262         --enable-no_exceptions  Enable compilation without creation of
 263                                 C++ exception information in object files.
 264                                 This will speed-up compilation and reduce
 265                                 binary size. Also fewer crashes during the
 266                                 actual compilation...
 267
 268         --enable-no_deps        Enable compilation without creation of
 269                                 dependency information.
 270
 271         --enable-permissive     Enable compilation without creation of
 272                                 giving erros as soon as you compile with
 273                                 Solaris ANSI-defying headers...
 274
 275         --enable-mem_tracing    Add built-in memory tracing.
 276
 277         --enable-dmalloc        Use the dmalloc memory debugger.
 278                                 Read more at www.letters.com/dmalloc/
 279
 280         --enable-debug_info     Add debug info to object files and
 281                                 executables for use with debuggers
 282                                 such as gdb (or its many frontends).
 283
 284         --enable-debug_flag     Define __DEBUG__ and __WXDEBUG__ when
 285                                 compiling. This enable wxWindows' very
 286                                 useful internal debugging tricks (such
 287                                 as automatically reporting illegal calls)
 288                                 to work. Note that program and library
 289                                 must be compiled with the same debug
 290                                 options.
 291
 292 * Feature Options
 293 -------------------
 294
 295 Many of the confiugre options have been thoroughly tested
 296 in wxWindows snapshot 6, but not yet all (ODBC not).
 297
 298 When producing an executable that is linked statically with wxGTK
 299 you'll be surprised at its immense size. This can sometimes be
 300 drastically reduced by removing features from wxWindows that
 301 are not used in your program. The most relevant such features
 302 are
 303
 304         --without-libpng        Disables PNG image format code.
 305
 306         --without-libjpeg       Disables JPEG image format code.
 307
 308 {       --without-odbc          Disables ODBC code. Not yet. }
 309
 310         --disable-resources     Disables the use of *.wxr type
 311                                 resources.
 312
 313         --disable-threads       Disables threads. Will also
 314                                 disable sockets.
 315
 316         --disable-sockets       Disables sockets.
 317
 318         --disable-dnd           Disables Drag'n'Drop.
 319
 320         --disable-clipboard     Disables Clipboard.
 321
 322         --disable-serial        Disables object instance serialiasation.
 323
 324         --disable-streams       Disables the wxStream classes.
 325
 326         --disable-file          Disables the wxFile class.
 327
 328         --disable-textfile      Disables the wxTextFile class.
 329
 330         --disable-intl          Disables the internationalisation.
 331
 332         --disable-validators    Disables validators.
 333
 334         --disable-accel         Disables accel.
 335
 336 Apart from disabling certain features you can very often "strip"
 337 the program of its debugging information resulting in a significant
 338 reduction in size.
 339
 340 * Compiling
 341 -------------
 342
 343 The following must be done in the base directory (e.g. ~/wxGTK
 344 or ~/wxWin or whatever)
 345
 346 Now the makefiles are created (by configure) and you can compile
 347 the library by typing:
 348
 349         make
 350
 351 make yourself some coffee, as it will take some time. On an old
 352 386SX possibly two weeks. During compilation, you'll get a few
 353 warning messages depending in your compiler.
 354
 355 If you want to be more selective, you can change into a specific
 356 directiry and type "make" there.
 357
 358 Then you may install the library and it's header files under
 359 /usr/local/include/wx and /usr/local/lib respectively. You
 360 have to log in as root (i.e. run "su" and enter the root
 361 password) and type
 362
 363         make install
 364
 365 You can remove any traces of wxWindows by typing
 366
 367         make uninstall
 368
 369 If you want to save disk space by removing unnecessary
 370 object-files:
 371
 372          make clean
 373
 374 in the various directories will do the work for you.
 375
 376 * Creating a new Project
 377 --------------------------
 378
 379 1) The first way uses the installed libraries and header files
 380 automatically using wx-config
 381
 382 g++ myfoo.cpp `wx-config --libs` `wx-config --cflags` -o myfoo
 383
 384 Using this way, a make file for the minimal sample would look
 385 like this
 386
 387 CC = g++
 388
 389 minimal: minimal.o
 390     $(CC) -o minimal minimal.o `wx-config --libs`
 391
 392 minimal.o: minimal.cpp mondrian.xpm
 393     $(CC) `wx-config --cflags` -c minimal.cpp -o minimal.o
 394
 395 clean:
 396         rm -f *.o minimal
 397
 398 This is certain to become the standard way unless we decide
 399 to sitch to tmake.
 400
 401 2) The other way creates a project within the source code
 402 directories of wxWindows. For this endeavour, you'll need
 403 GNU autoconf version 2.14 and add an entry to your Makefile.in
 404 to the bottom of the configure.in script and run autoconf
 405 and configure before you can type make.
 406
 407 ----------------------
 408
 409 In the hope that it will be useful,
 410
 411         Robert Roebling <roebling@sun2.ruf.uni-freiburg.de>
 412
 413