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