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