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