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