docs/x11/install.txt

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