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