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