docs/gtk/install.txt

   1 * The most simple case
   2 -----------------------
   3
   4 If you compile wxWindows on Unix for the first time and don't
   5 like to read install instructions just do (in the base dir):
   6
   7 ./configure --without-threads
   8 make
   9
  10 and drink 10 coffees. Then you may log in as root and type
  11
  12 make install
  13
  14 You can leave out the --without-threads option if you have
  15 a NEW Linux distribution based on glibc (e.g. RedHat 5.1 or
  16 Debian 2.0) or any other Unix that comes with Posix threads
  17 or SGI threads.
  18
  19 Now create your super-application myfoo.app and compile anywhere
  20 with
  21
  22 g++ myfoo.cpp `wx-config --libs` `wx-config --cflags` -o myfoo
  23
  24 * General
  25 -----------------------
  26
  27 The Unix variants of wxWindows use GNU configure. If you have
  28 problems with your make use GNU make instead.
  29
  30 If you have general problems with installation, read my
  31 homepage at
  32
  33   http://wesley.informatik.uni-freiburg.de/~wxxt
  34
  35 for newest information. If you still don't have any success,
  36 please send a bug report to one of our mailing lists (see
  37 my homepage) INCLUDING A DESCRIPTION OF YOUR SYSTEM AND
  38 YOUR PROBLEM, SUCH AS YOUR VERSION OF GTK, WXGTK, WHAT
  39 DISTRIBUTION YOU USE AND WHAT ERROR WAS REPORTED. I know
  40 this has no effect, but I tried...
  41
  42 * GUI libraries
  43 -----------------------
  44
  45 wxWindows/GTK requires the GTK+ library to be installed on your system.
  46 It has to be a stable version, preferebly version 1.0.6. When using
  47 a version previous to 1.0.6 you'll get crashes here and there.
  48
  49 wxWindows/GTK does NOT work with the 1.1.X versions of the GTK+ library
  50 and we will wait until the 1.2 version comes out and has stabilized
  51 until we'll work with that library.
  52
  53 You can get the newest version of the GTK+ from the GTK homepage
  54 at
  55   http://www.gtk.org
  56
  57 We also mirror GTK+ 1.0.6 at our ftp site. You'll find information
  58 about downloading at my homepage.
  59
  60 * Additional libraries
  61 -----------------------
  62
  63 wxWindows/Gtk requires a thread library and X libraries
  64 known to work with threads. This is the case on all
  65 commercial Unix-Variants and all Linux-Versions that
  66 are based on glibc 2 except RedHat 5.0 which is broken
  67 in many aspects. As of writing this, these Linux
  68 distributions have correct glibc 2 support:
  69
  70  - RedHat 5.1
  71  - Debian 2.0
  72  - Stampede
  73  - DLD 6.0
  74
  75 The next major version of SuSE will also support glibc 2,
  76 but version 5.X does not. Also Caldera and Slackware
  77 don't yet support glibc 2.
  78
  79 On IRIX you can also use SGI threads if Posix-Threads
  80 are not present. The SGI threads will be detected by
  81 configure automatically.
  82
  83 You can always disable thread support by running
  84
  85 ./configure "--without-threads"
  86 make clean
  87 make
  88
  89 NB: I included thread support in wxWindows/Gtk, as this
  90 problem will disappear in the near future when all major
  91 Linux Variants have moved to glibc 2. Also, the Linux
  92 Base Standard will include glibc 2.
  93
  94 * Create your configuration
  95 -----------------------------
  96
  97 Usage:
  98         ./configure options
  99
 100 If you want to use system's C and C++ compiler,
 101 set environment variables CC and CCC as
 102
 103         % setenv CC cc
 104         % setenv CCC CC
 105         % ./configure options
 106
 107 Using the SGI native compilers, it is recommended that you
 108 also set CFLAGS and CXXFLAGS before running configure. These
 109 should be set to :
 110
 111 CFLAGS="-mips3 -n32"
 112 CXXFLAGS="-mips3 -n32"
 113
 114 This is essential if you want to use the resultant binaries
 115 on any other machine than the one it was compiled on. If you
 116 have a 64bit machine (Octane) you should also do this to ensure
 117 you don't accidently build the libraries as 64bit (which is
 118 untested).
 119
 120 The SGI native compiler support has only been tested on Irix 6.5.
 121
 122 to see all the options please use:
 123
 124         ./configure --help
 125
 126 The basic philosophy is that if you want to use different
 127 configurations, like a debug and a release version,
 128 or use the same source tree on different systems,
 129 you have only to change the environment variable OSTYPE.
 130 (Sadly this variable is not set by default on some systems
 131 in some shells - on SGI's for example). So you will have to
 132 set it there. This variable HAS to be set before starting
 133 configure, so that it knows which system it tries to
 134 configure for.
 135
 136 Configure will complain if the system variable OSTYPE has
 137 not been defined. And Make in some circumstances as well...
 138
 139
 140 * General options
 141 -------------------
 142
 143 Normally, you won't have to choose a toolkit, because when
 144 you download wxGTK, it will default to --with-gtk etc. But
 145 if you use all of our CVS repository you have to choose a
 146 toolkit. You must do this by running configure with either of:
 147
 148         --with-gtk               Use the GIMP ToolKit (GTK)
 149
 150         --with-qt                Use Qt from TrollTec
 151
 152         --with-motif             Use either Motif or Lesstif
 153                                  Configure will look for both.
 154
 155 The following options handle the kind of library you want to build.
 156
 157         --without-threads       Compile without thread support.
 158
 159         --without-shared        Do not create shared libraries.
 160
 161         --without-optimise      Do not optimise the code.
 162
 163         --with-profile          Add profiling info to the object
 164                                 files. Currently broken, I think.
 165
 166         --with-mem_tracing      Add built-in memory tracing.
 167                                 This doesn't work well with gcc.
 168
 169         --with-dmalloc          Use the dmalloc memory debugger.
 170                                 Read more at www.letters.com/dmalloc/
 171
 172         --with-debug_info       Add debug info to object files and
 173                                 executables.
 174
 175         --with-debug_flag       Define __DEBUG__ and __WXDEBUG__ when
 176                                 compiling.
 177
 178 * Feature Options
 179 -------------------
 180
 181 As I don't yet care for binary size and target mainly at
 182 producing a shared library, wxWindows's configure system auto-
 183 matically enables all features, as long as they are already
 184 implemented. It is currently NOT possible to disable these
 185 options (in contrast to what configure tells you).
 186
 187 * Compiling
 188 -------------
 189
 190 The following must be done in the base directory (e.g. ~/wxGTK
 191 or ~/wxWin or whatever)
 192
 193 Now the makefiles are created and you can compile everything
 194 by typing:
 195
 196         make
 197
 198 make yourself some coffee, as it will try to compile ALL the
 199 files in this distribution. During compilation, you'll get
 200 a few warning messages.
 201
 202 if you want to be more selective:
 203
 204         make src        will build only the base libraries
 205         make samples    will build the samples
 206         make other      will build everything in other
 207         make user       will build everything in user
 208
 209 Then you may install the library and it's header files under
 210 /usr/local/include/wx and /usr/local/lib respectively. You
 211 have to log in as root (i.e. run "su" and enter the root
 212 password) and type
 213
 214         make install
 215
 216 Depending on the configuration of some files, the libraries
 217 and binaries will be placed in different directories.
 218 The "global" binaries and libraries will be placed in:
 219
 220         bin/$(OSTYPE) and
 221         lib/$(OSTYPE) respectively
 222
 223 "local" binaries and libraries will be placed in:
 224
 225         (basedir of that application)/$(OSTYPE).
 226
 227 This is also the place where all the object-files will go.
 228
 229 If you want to conserve disk space by removing unnecessary
 230 object-files:
 231
 232          make clean_obj
 233
 234 will do the work for you.
 235
 236 * Creating a new Project
 237 --------------------------
 238
 239 There are two ways to create your own project:
 240
 241 1) The first way uses the installed libraries and header files
 242 automatically using wx-config
 243
 244 g++ myfoo.cpp `wx-config --libs` `wx-config --cflags` -o myfoo
 245
 246 Using this way, a make file for the minimal sample would look
 247 like this
 248
 249 CC = g++
 250
 251 minimal: minimal.o
 252     $(CC) -o minimal minimal.o `wx-config --libs`
 253
 254 minimal.o: minimal.cpp mondrian.xpm
 255     $(CC) `wx-config --cflags` -c minimal.cpp -o minimal.o
 256
 257 clean:
 258         rm -f *.o minimal
 259
 260 This is certain to become the standard way unless we decide
 261 to sitch to tmake.
 262
 263 2) The other way creates a project within the source code
 264 directories of wxWindows: In this case I propose to put
 265 all contributed programs in the directory "/user", with a
 266 directory of its own.
 267
 268 This directory then should include the following files:
 269
 270 Makefile        (You can copy this one from any application in samples
 271                  probably you will not need to edit this one. There is
 272                  only one case where you might be interested in changing
 273                  this file, but about that see later.)
 274 Makefile.in     (This is the base application-Makefile template, from
 275                  which the actual Makefile for each system is created.
 276                  More about this later)
 277
 278 put ALL your source code along with all the other stuff you need for
 279 your application in this directory (subdirectories are welcome).
 280
 281
 282 ** Something about Makefiles
 283 ------------------------------
 284
 285 On general principle it should only contain ONE line, which is as follows:
 286
 287         include ../../setup/general/makeapp
 288
 289 this will include all the necessary definitions for creating the applications
 290
 291 the only case where you might want to add another line is the following:
 292 this version of configure also supports creation of source archives of the
 293 application for easy distribution and updates to newer version of wxWindows.
 294     For this purpose all files in the application-directory will be put into
 295 a gziped tar-file in the full notation user/<your application>/*
 296 if you want to include some other files that you want "more visible", like
 297 a README.<yourApp> or a shell script for easy
 298 compilation/installation/distribution, then you have to add a variable
 299
 300         DISTRIBUTE_ADDITIONAL=<your files>
 301
 302 to the Makefile.
 303 So it would look like this:
 304
 305         DISTRIBUTE_ADDITIONAL=README.TheApp
 306         include ../../setup/general/makeapp
 307
 308 As we have already talked about distribution the command to create a
 309 distribution is:
 310
 311         make distrib
 312
 313 NOTE: If you are in the base directory of wxWindows it will create
 314 distribution packages for wxWindows as well as for all packages in the
 315 user directory.
 316     So if you want to create only packages for the files in user,
 317 then go to the directory other and type:
 318
 319         make distrib
 320
 321 or if you only want one application to be created then
 322 enter the specific directory and type there:
 323 make distrib
 324
 325 All the distribution files will be put in the directory
 326 distrib at the base of the wxWindows-tree (where also configure
 327 and template.mak can be found).
 328
 329 ** Something about Makefile.in
 330 --------------------------------
 331
 332 As you have already seen with Makefile, configure makes a lot of use
 333 if the include statement in make to keep the Makefiles as simple as
 334 possible.
 335
 336 So basically there are only variables to define and then a include command.
 337 Exception to this rule is if you have special rules for some stuff...
 338 These rules should go AFTER the include statement!!!
 339
 340 so the general header looks like this:
 341
 342         # wxWindows base directory
 343         WXBASEDIR=@WXBASEDIR@
 344         # set the OS type for compilation
 345         OS=@OS@
 346         # compile a library only
 347         RULE=bin
 348
 349 and the general footer will look like this:
 350
 351         # include the definitions now
 352         include ../../../template.mak
 353
 354 the key variable is RULE, which defines what make should create
 355 in this directory.
 356
 357 here are some examples:
 358
 359   RULE    description
 360   ===========================================================================
 361   bin     creates a local binary (for a global binary prefix bin with g)
 362           additional variables needed:
 363                 BIN_TARGET      this gives the name of your application
 364                 BIN_OBJ         this gives the object files needed to
 365                                 link the application
 366           optional variables are:
 367                 BIN_SRC         this gives the list of c/c++ files for
 368                                 which dependencies will be checked.
 369                                 (This can be achieved with: make depend)
 370                 BIN_LINK        this gives commands for additional
 371                                 libraries needed to link the application
 372   ---------------------------------------------------------------------------
 373   bin2    creates two local binaries (for global binaries prefix bin2 with g)
 374           in addition to the variables specified above you MUST also
 375           provide the same variables with BIN2_ instead of BIN_
 376   ---------------------------------------------------------------------------
 377   lib     creates a local library (for a global binary prefix bin with g)
 378           additional variables needed:
 379                 LIB_TARGET      this gives the name of your library
 380                 LIB_OBJ         this gives the object files needed for
 381                                 the library to be build.
 382           optional variables are:
 383                 LIB_SRC         this gives the list of c/c++ files for
 384                                 which dependencies will be checked.
 385           libbin and libgbin are also possible and will need in addition
 386           the variables from bin
 387   ---------------------------------------------------------------------------
 388   gslib   is similar to lib, but it creates a shared library if the system
 389           supports it.
 390           additional variables needed:
 391                 LIB_MAJOR       major number of the shared library
 392                 LIB_MINOR       minor number of the shared library
 393   ---------------------------------------------------------------------------
 394   other additional variables:
 395
 396           ADD_COMPILE      define additional includes/defines that
 397                            are needed to compile the object files
 398                            (if you need to reference some directory
 399                            utils - like wxGrid -, then please
 400                            reference them with the variables defined
 401                            in template.mak - e.g.: $(SRCDIR),$(UTILS),
 402                            $(SAMPLES),$(OTHERS))
 403
 404           NEEDED_DEFINES   lists all the defines that HAVE to be set in
 405                            /include/wx/setup.h to compile correctly.
 406
 407           SRC_DIR          lists all directories that are needed to
 408                            compile. (i.e: lists all the directories,
 409                            where there are source-files.) But it is
 410                            also needed to clean an object and for
 411                            machines, for which make does not support
 412                            VPATH
 413
 414 currently there are the following compiling rules provided:
 415 object files are created for the following file extensions:
 416 .c .cc .cpp
 417
 418 Please have a closer look at the Makefiles in this distribution.
 419
 420 * Platforms configure is working with
 421 ---------------------------------------
 422
 423 Please report build succes on any machine. Especially non-
 424 Linux operating systems (which I don't have).
 425
 426 Original author of the autoconf system for wxxt-1.66 and for this INSTALL
 427 file:
 428
 429         Martin Sperl    sperl@dsn.ast.univie.ac.at
 430
 431 Ported to wxGTK 0.1:
 432
 433         Wolfram Gloger  wmglo@dent.med.uni-muenchen.de
 434
 435 Thanks alot to both of them.
 436
 437 In the hope that it will be useful,
 438
 439         Robert Roebling roebling@sun2.ruf.uni-freiburg.de
 440
 441