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 like
   5 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 a NEW
  15 Linux distribution based on glibc (e.g. RedHat 5.1 or Debian 2.0)
  16 or any other Unix that comes with Posix threads or SGI threads.
  17
  18 Now create your super-application myfoo.app and compile anywhere with
  19
  20 g++ myfoo.cpp `wx-config --libs` `wx-config --cflags` -o myfoo
  21
  22 * General
  23 -----------------------
  24
  25 The Unix variants of wxWindows use GNU configure. If you have problems
  26 with your make use GNU make instead.
  27
  28 Read my homepage at
  29
  30   http://wesley.informatik.uni-freiburg.de/~wxxt
  31
  32 for newest information.
  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. This
  40 is certain to happen with colors in native widgets.
  41
  42 You can get the newest version of the GTK+ from the GTK homepage
  43 at
  44   http://www.gtk.org
  45
  46 We also mirror GTK+ 1.0.6 at our ftp site. You'll find information
  47 about downloading at my homepage.
  48
  49 * Additional libraries
  50 -----------------------
  51
  52 wxWindows/Gtk requires a thread library and X libraries
  53 known to work with threads. This is the case on all
  54 commercial Unix-Variants and all Linux-Versions that
  55 are based on glibc 2 except RedHat 5.0 which is broken
  56 in many aspects. As of writing this, these Linux
  57 distributions have correct glibc 2 support:
  58
  59  - RedHat 5.1
  60  - Debian 2.0
  61  - Stampede
  62
  63 The next major version of SuSE will also support glibc 2,
  64 but version 5.X does not. Also Caldera and Slackware
  65 don't yet support glibc 2.
  66
  67 On IRIX you can also use SGI threads if Posix-Threads
  68 are not present. The SGI threads will be detected by
  69 configure automatically.
  70
  71 You can always disable thread support by running
  72
  73 ./configure "--without-threads"
  74 make clean
  75 make
  76
  77 NB: I included thread support in wxWindows/Gtk, as this
  78 problem will disappear in the near future when all major
  79 Linux Variants have moved to glibc 2. Also, the Linux
  80 Base Standard will include glibc 2.
  81
  82 * Create your configuration
  83 -----------------------------
  84
  85 Usage:
  86         ./configure options
  87
  88 If you want to use system's C and C++ compiler,
  89 set environment variables CC and CCC as
  90
  91         % setenv CC cc
  92         % setenv CCC CC
  93         % ./configure options
  94
  95 Using the SGI native compilers, it is recommended that you
  96 also set CFLAGS and CXXFLAGS before running configure. These
  97 should be set to :
  98
  99 CFLAGS="-mips3 -n32"
 100 CXXFLAGS="-mips3 -n32"
 101
 102 This is essential if you want to use the resultant binaries
 103 on any other machine than the one it was compiled on. If you
 104 have a 64bit machine (Octane) you should also do this to ensure
 105 you don't accidently build the libraries as 64bit (which is
 106 untested).
 107
 108 The SGI native compiler support has only been tested on Irix 6.5.
 109
 110 to see all the options please use:
 111
 112         ./configure --help
 113
 114 The basic philosophy is that if you want to use different
 115 configurations, like a debug and a release version,
 116 or use the same source tree on different systems,
 117 you have only to change the environment variable OSTYPE.
 118 (Sadly this variable is not set by default on some systems
 119 in some shells - on SGI's for example). So you will have to
 120 set it there. This variable HAS to be set before starting
 121 configure, so that it knows which system it tries to
 122 configure for.
 123
 124 Configure will complain if the system variable OSTYPE has
 125 not been defined. And Make in some circumstances as well...
 126
 127
 128 * General options
 129 -------------------
 130
 131 Normally, you won't have to choose a toolkit, because when
 132 you download wxGTK, it will default to --with-gtk etc. But
 133 if you use all of our CVS repository you have to choose a
 134 toolkit. You must do this by running configure with either of:
 135
 136         --with-gtk               Use the GIMP ToolKit (GTK)
 137
 138         --with-qt                Use Qt from TrollTec
 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         --without-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                                 This doesn't work well with gcc.
 156
 157         --with-dmalloc          Use the dmalloc memory debugger.
 158                                 Read more at www.letters.com/dmalloc/
 159
 160         --with-debug_info       Add debug info to object files and
 161                                 executables.
 162
 163         --with-debug_flag       Define __DEBUG__ and __WXDEBUG__ when
 164                                 compiling.
 165
 166 * Feature Options
 167 -------------------
 168
 169 As I don't yet care for binary size and target mainly at
 170 producing a shared library, wxWindows's configure system auto-
 171 matically enables all features, as long as they are already
 172 implemented. It is currently NOT possible to disable these
 173 options (in contrast to what configure tells you).
 174
 175 * Compiling
 176 -------------
 177
 178 The following must be done in the base directory (e.g. ~/wxGTK
 179 or ~/wxWin or whatever)
 180
 181 Now the makefiles are created and you can compile everything
 182 by typing:
 183
 184         make
 185
 186 make yourself some coffee, as it will try to compile ALL the
 187 files in this distribution. During compilation, you'll get
 188 a few warning messages.
 189
 190 if you want to be more selective:
 191
 192         make src        will build only the base libraries
 193         make samples    will build the samples
 194         make other      will build everything in other
 195         make user       will build everything in user
 196
 197 Then you may install the library and it's header files under
 198 /usr/local/include/wx and /usr/local/lib respectively. You
 199 have to log in as root (i.e. run "su" and enter the root
 200 password) and type
 201
 202         make install
 203
 204 Depending on the configuration of some files, the libraries
 205 and binaries will be placed in different directories.
 206 The "global" binaries and libraries will be placed in:
 207
 208         bin/$(OSTYPE) and
 209         lib/$(OSTYPE) respectively
 210
 211 "local" binaries and libraries will be placed in:
 212
 213         (basedir of that application)/$(OSTYPE).
 214
 215 This is also the place where all the object-files will go.
 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