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