docs/x11/install.txt

   1 wxWidgets 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.8.0, 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.wxwidgets.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 * Building wxX11 on Cygwin
 221 --------------------------
 222
 223 The normal build instructions should work fine on Cygwin. The one difference
 224 with Cygwin is that when using the "--enable-shared" configure option (which
 225 is the default) the API is exported explicitly using __declspec(dllexport)
 226 rather than all global symbols being available.
 227
 228 This shouldn't make a difference using the library and should be a little
 229 more efficient. However if an export attribute has been missed somewhere you
 230 will see linking errors. If this happens then you can work around the
 231 problem by setting LDFLAGS=-Wl,--export-all-symbols. Please also let us know
 232 about it on the wx-dev mailing list.
 233
 234 * Create your configuration
 235 ---------------------------
 236
 237 Usage:
 238         ./configure [options]
 239
 240 If you want to use system's C and C++ compiler,
 241 set environment variables CXX and CC as
 242
 243         % setenv CC cc
 244         % setenv CXX CC
 245         % ./configure [options]
 246
 247 to see all the options please use:
 248
 249         ./configure --help
 250
 251 The basic philosophy is that if you want to use different
 252 configurations, like a debug and a release version,
 253 or use the same source tree on different systems,
 254 you have only to change the environment variable OSTYPE.
 255 (Sadly this variable is not set by default on some systems
 256 in some shells - on SGI's for example). So you will have to
 257 set it there. This variable HAS to be set before starting
 258 configure, so that it knows which system it tries to
 259 configure for.
 260
 261 Configure will complain if the system variable OSTYPE has
 262 not been defined. And Make in some circumstances as well...
 263
 264
 265 * General options
 266 -----------------
 267
 268 Given below are the commands to change the default behaviour,
 269 i.e. if it says "--disable-threads" it means that threads
 270 are enabled by default.
 271
 272 You have to add --with-x11 on platforms, where X11 is
 273 not the default (on Linux, configure will default to GTK).
 274
 275         --with-x11              Use X11.
 276
 277 The following options handle the kind of library you want to build.
 278
 279         --disable-threads       Compile without thread support. Threads
 280                                 support is also required for the
 281                                 socket code to work.
 282
 283         --disable-shared        Do not create shared libraries.
 284
 285     --enable-monolithic     Build wxWidgets as single library instead
 286                             of as several smaller libraries (which is
 287                             the default since wxWidgets 2.5.0).
 288
 289         --disable-optimise      Do not optimise the code. Can
 290                                 sometimes be useful for debugging
 291                                 and is required on some architectures
 292                                 such as Sun with gcc 2.8.X which
 293                                 would otherwise produce segvs.
 294
 295         --enable-profile        Add profiling info to the object
 296                                 files. Currently broken, I think.
 297
 298         --enable-no_rtti        Enable compilation without creation of
 299                                 C++ RTTI information in object files.
 300                                 This will speed-up compilation and reduce
 301                                 binary size.
 302
 303         --enable-no_exceptions  Enable compilation without creation of
 304                                 C++ exception information in object files.
 305                                 This will speed-up compilation and reduce
 306                                 binary size. Also fewer crashes during the
 307                                 actual compilation...
 308
 309         --enable-no_deps        Enable compilation without creation of
 310                                 dependency information.
 311
 312         --enable-permissive     Enable compilation without checking for strict
 313                                 ANSI conformance.  Useful to prevent the build
 314                                 dying with errors as soon as you compile with
 315                                 Solaris' ANSI-defying headers.
 316
 317         --enable-mem_tracing    Add built-in memory tracing.
 318
 319         --enable-dmalloc        Use the dmalloc memory debugger.
 320                                 Read more at www.letters.com/dmalloc/
 321
 322         --enable-debug_info     Add debug info to object files and
 323                                 executables for use with debuggers
 324                                 such as gdb (or its many frontends).
 325
 326         --enable-debug_flag     Define __DEBUG__ and __WXDEBUG__ when
 327                                 compiling. This enable wxWidgets' very
 328                                 useful internal debugging tricks (such
 329                                 as automatically reporting illegal calls)
 330                                 to work. Note that program and library
 331                                 must be compiled with the same debug
 332                                 options.
 333
 334 * Feature Options
 335 -----------------
 336
 337 Many of the configure options have been thoroughly tested
 338 in wxWidgets snapshot 6, but not yet all (ODBC not).
 339
 340 When producing an executable that is linked statically with wxX11
 341 you'll be surprised at its immense size. This can sometimes be
 342 drastically reduced by removing features from wxWidgets that
 343 are not used in your program. The most relevant such features
 344 are
 345
 346         --without-libpng        Disables PNG image format code.
 347
 348         --without-libjpeg       Disables JPEG image format code.
 349
 350 {       --without-odbc          Disables ODBC code. Not yet. }
 351
 352     --without-expat         Disable XML classes based on Expat parser.
 353
 354         --disable-resources     Disables the use of *.wxr type
 355                                 resources.
 356
 357         --disable-threads       Disables threads. Will also
 358                                 disable sockets.
 359
 360         --disable-sockets       Disables sockets.
 361
 362         --disable-dnd           Disables Drag'n'Drop.
 363
 364         --disable-clipboard     Disables Clipboard.
 365
 366         --disable-serial        Disables object instance serialisation.
 367
 368         --disable-streams       Disables the wxStream classes.
 369
 370         --disable-file          Disables the wxFile class.
 371
 372         --disable-textfile      Disables the wxTextFile class.
 373
 374         --disable-intl          Disables the internationalisation.
 375
 376         --disable-validators    Disables validators.
 377
 378         --disable-accel         Disables accel.
 379
 380 Apart from disabling certain features you can very often "strip"
 381 the program of its debugging information resulting in a significant
 382 reduction in size.
 383
 384 Please see the output of "./configure --help" for comprehensive list
 385 of all configurable options.
 386
 387
 388 * Compiling
 389 -----------
 390
 391 The following must be done in the base directory (e.g. ~/wxX11
 392 or whatever)
 393
 394 Now the makefiles are created (by configure) and you can compile
 395 the library by typing:
 396
 397         make
 398
 399 make yourself some coffee, as it will take some time. On an old
 400 386SX possibly two weeks. During compilation, you'll get a few
 401 warning messages depending in your compiler.
 402
 403 If you want to be more selective, you can change into a specific
 404 directory and type "make" there.
 405
 406 Then you may install the library and its header files under
 407 /usr/local/include/wx and /usr/local/lib respectively. You
 408 have to log in as root (i.e. run "su" and enter the root
 409 password) and type
 410
 411         make install
 412
 413 You can remove any traces of wxWidgets by typing
 414
 415         make uninstall
 416
 417 If you want to save disk space by removing unnecessary
 418 object-files:
 419
 420         make clean
 421
 422 in the various directories will do the work for you.
 423
 424 * Creating a new Project
 425 ------------------------
 426
 427 1) The first way uses the installed libraries and header files
 428 automatically using wx-config
 429
 430 g++ myfoo.cpp `wx-config --libs` `wx-config --cxxflags` -o myfoo
 431
 432 Using this way, a make file for the minimal sample would look
 433 like this
 434
 435 CXX = g++
 436
 437 minimal: minimal.o
 438     $(CXX) -o minimal minimal.o `wx-config --libs`
 439
 440 minimal.o: minimal.cpp
 441     $(CXX) `wx-config --cxxflags` -c minimal.cpp -o minimal.o
 442
 443 clean:
 444         rm -f *.o minimal
 445
 446 This is certain to become the standard way unless we decide
 447 to stick to tmake.
 448
 449 If your application uses only some of wxWidgets libraries, you can
 450 specify required libraries when running wx-config. For example,
 451 `wx-config --libs=html,core` will only output link command to link
 452 with libraries required by core GUI classes and wxHTML classes. See
 453 the manual for more information on the libraries.
 454
 455 2) The other way creates a project within the source code
 456 directories of wxWidgets. For this endeavour, you'll need
 457 GNU autoconf version 2.14 and add an entry to your Makefile.in
 458 to the bottom of the configure.in script and run autoconf
 459 and configure before you can type make.
 460
 461 * Further notes by Julian Smart
 462 -------------------------------
 463
 464 - You may find the following script useful for compiling wxX11,
 465   especially if installing from zips (which don't preserve file
 466   permissions). Make this script executable with the command
 467   chmod a+x makewxx11.
 468
 469   -------:x-----Cut here-----:x-----
 470   # makewxx11
 471   # Sets permissions (in case we extracted wxX11 from zip files)
 472   # and makes wxX11.
 473   # Call from top-level wxWidgets directory.
 474   # Note that this uses standard (but commonly-used) configure options;
 475   # if you're feeling brave, you may wish to compile with threads:
 476   # if they're not supported by the target platform, they will be disabled
 477   # anyhow
 478   # -- Julian Smart
 479   chmod a+x configure config.sub config.guess
 480   ./configure --with-x11 --with-shared --with-debug_flag --with-debug_info --enable-debug --without-threads --without-sockets --without-odbc
 481   make
 482   -------:x-----Cut here-----:x-----
 483
 484   This script will build wxX11 using shared libraries. If you want to build
 485   a static wxWidgets library, use --disable-shared.
 486
 487 Troubleshooting
 488 ---------------
 489
 490 - Solaris compilation with gcc: if the compiler has problems with the variable
 491   argument functions, try putting the gcc fixinclude file paths early in the
 492   include path.
 493
 494 - If you operator-related compile errors or strange memory problems
 495   (for example in deletion of string arrays), set wxUSE_GLOBAL_MEMORY_OPERATORS
 496   and wxUSE_MEMORY_TRACING to 0 in setup.h, and recompile.
 497
 498 - If you get an internal compiler error in gcc, turn off optimisations.
 499
 500 - Some compilers, such as Sun C++, may give a lot of warnings about
 501   virtual functions being hidden. Please ignore these, it's correct C++ syntax.
 502   If you find any incorrect instances, though, such as a
 503   missing 'const' in an overridden function, please let us know.
 504
 505 Other Notes
 506 -----------
 507
 508 - Debugging mode is switched on by default in the makefiles, but using
 509   configure will create a release build of the library by default: it's
 510   recommended to use --with-debug_info and --with-debug_flag configure
 511   switches while developing your application. To compile in non-debug
 512   mode, remove the -D__WXDEBUG__ switch in make.env (or if using the
 513   configure system, change --with-debug_flag to --without-debug_flag
 514   and --with-debug_info to --without-debug_info in the makewxx11
 515   script).
 516
 517 Bug reports
 518 -----------
 519
 520 Please send bug reports with a description of your environment,
 521 compiler and the error message(s) to the wxwin-developers mailing list at:
 522
 523     wx-dev@lists.wxwidgets.org
 524
 525