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