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 As I don't yet care for binary size and target mainly at
 192 producing a shared library, wxWindows's configure system auto-
 193 matically enables all features, as long as they are already
 194 implemented. It is currently NOT possible to disable these
 195 options (in contrast to what configure tells you).
 196
 197 * Compiling
 198 -------------
 199
 200 The following must be done in the base directory (e.g. ~/wxGTK
 201 or ~/wxWin or whatever)
 202
 203 Now the makefiles are created and you can compile everything
 204 by typing:
 205
 206         make
 207
 208 make yourself some coffee, as it will try to compile ALL the
 209 files in this distribution. During compilation, you'll get
 210 a few warning messages.
 211
 212 if you want to be more selective:
 213
 214         make src        will build only the base libraries
 215         make utils      will build the utils
 216         make samples    will build the samples
 217         make other      will build the other samples
 218         make user       will build the files in the directory other
 219
 220 Then you may install the library and it's header files under
 221 /usr/local/include/wx and /usr/local/lib respectively. You
 222 have to log in as root (i.e. run "su" and enter the root
 223 password) and type
 224
 225         make install
 226
 227 Depending on the configuration of some files, the libraries
 228 and binaries will be placed in different directories.
 229 The "global" binaries and libraries will be placed in:
 230
 231         bin/$(OSTYPE) and
 232         lib/$(OSTYPE) respectively
 233
 234 "local" binaries and libraries will be placed in:
 235
 236         (basedir of that application)/$(OSTYPE).
 237
 238 This is also the place where all the object-files will go.
 239
 240 If you want to conserve disk space by removing unnecessary
 241 object-files:
 242
 243          make clean_obj
 244
 245 will do the work for you.
 246
 247 * Creating a new Project
 248 --------------------------
 249
 250 There are two ways to create your own project:
 251
 252 1) The first way uses the installed libraries and header files
 253 automatically using wx-config
 254
 255 g++ myfoo.cpp `wx-config --libs` `wx-config --cflags` -o myfoo
 256
 257 Using this way, a make file for the minimal sample would look
 258 like this
 259
 260 CC = g++
 261
 262 minimal: minimal.o
 263     $(CC) -o minimal minimal.o `wx-config --libs`
 264
 265 minimal.o: minimal.cpp mondrian.xpm
 266     $(CC) `wx-config --cflags` -c minimal.cpp -o minimal.o
 267
 268 clean:
 269         rm -f *.o minimal
 270
 271 This is certain to become the standard way unless we decide
 272 to sitch to tmake.
 273
 274 2) The other way creates a project within the source code
 275 directories of wxWindows: In this case I propose to put
 276 all contributed programs in the directory "/user", with a
 277 directory of its own.
 278
 279 This directory then should include the following files:
 280
 281 Makefile        (You can copy this one from any application in samples
 282                  probably you will not need to edit this one. There is
 283                  only one case where you might be interested in changing
 284                  this file, but about that see later.)
 285 Makefile.in     (This is the base application-Makefile template, from
 286                  which the actual Makefile for each system is created.
 287                  More about this later)
 288
 289 put ALL your source code along with all the other stuff you need for
 290 your application in this directory (subdirectories are welcome).
 291
 292
 293 ** Something about Makefiles
 294 ------------------------------
 295
 296 On general principle it should only contain ONE line, which is as follows:
 297
 298         include ../../setup/general/makeapp
 299
 300 this will include all the necessary definitions for creating the applications
 301
 302 the only case where you might want to add another line is the following:
 303 this version of configure also supports creation of source archives of the
 304 application for easy distribution and updates to newer version of wxWindows.
 305     For this purpose all files in the application-directory will be put into
 306 a gziped tar-file in the full notation user/<your application>/*
 307 if you want to include some other files that you want "more visible", like
 308 a README.<yourApp> or a shell script for easy
 309 compilation/installation/distribution, then you have to add a variable
 310
 311         DISTRIBUTE_ADDITIONAL=<your files>
 312
 313 to the Makefile.
 314 So it would look like this:
 315
 316         DISTRIBUTE_ADDITIONAL=README.TheApp
 317         include ../../setup/general/makeapp
 318
 319 As we have already talked about distribution the command to create a
 320 distribution is:
 321
 322         make distrib
 323
 324 NOTE: If you are in the base directory of wxWindows it will create
 325 distribution packages for wxWindows as well as for all packages in the
 326 user directory.
 327     So if you want to create only packages for the files in user,
 328 then go to the directory other and type:
 329
 330         make distrib
 331
 332 or if you only want one application to be created then
 333 enter the specific directory and type there:
 334 make distrib
 335
 336 All the distribution files will be put in the directory
 337 distrib at the base of the wxWindows-tree (where also configure
 338 and template.mak can be found).
 339
 340 ** Something about Makefile.in
 341 --------------------------------
 342
 343 As you have already seen with Makefile, configure makes a lot of use
 344 if the include statement in make to keep the Makefiles as simple as
 345 possible.
 346
 347 So basically there are only variables to define and then a include command.
 348 Exception to this rule is if you have special rules for some stuff...
 349 These rules should go AFTER the include statement!!!
 350
 351 so the general header looks like this:
 352
 353         # wxWindows base directory
 354         WXBASEDIR=@WXBASEDIR@
 355         # set the OS type for compilation
 356         OS=@OS@
 357         # compile a library only
 358         RULE=bin
 359
 360 and the general footer will look like this:
 361
 362         # include the definitions now
 363         include ../../../template.mak
 364
 365 the key variable is RULE, which defines what make should create
 366 in this directory.
 367
 368 here are some examples:
 369
 370   RULE    description
 371   ===========================================================================
 372   bin     creates a local binary (for a global binary prefix bin with g)
 373           additional variables needed:
 374                 BIN_TARGET      this gives the name of your application
 375                 BIN_OBJ         this gives the object files needed to
 376                                 link the application
 377           optional variables are:
 378                 BIN_SRC         this gives the list of c/c++ files for
 379                                 which dependencies will be checked.
 380                                 (This can be achieved with: make depend)
 381                 BIN_LINK        this gives commands for additional
 382                                 libraries needed to link the application
 383   ---------------------------------------------------------------------------
 384   bin2    creates two local binaries (for global binaries prefix bin2 with g)
 385           in addition to the variables specified above you MUST also
 386           provide the same variables with BIN2_ instead of BIN_
 387   ---------------------------------------------------------------------------
 388   lib     creates a local library (for a global binary prefix bin with g)
 389           additional variables needed:
 390                 LIB_TARGET      this gives the name of your library
 391                 LIB_OBJ         this gives the object files needed for
 392                                 the library to be build.
 393           optional variables are:
 394                 LIB_SRC         this gives the list of c/c++ files for
 395                                 which dependencies will be checked.
 396           libbin and libgbin are also possible and will need in addition
 397           the variables from bin
 398   ---------------------------------------------------------------------------
 399   gslib   is similar to lib, but it creates a shared library if the system
 400           supports it.
 401           additional variables needed:
 402                 LIB_MAJOR       major number of the shared library
 403                 LIB_MINOR       minor number of the shared library
 404   ---------------------------------------------------------------------------
 405   other additional variables:
 406
 407           ADD_COMPILE      define additional includes/defines that
 408                            are needed to compile the object files
 409                            (if you need to reference some directory
 410                            utils - like wxGrid -, then please
 411                            reference them with the variables defined
 412                            in template.mak - e.g.: $(SRCDIR),$(UTILS),
 413                            $(SAMPLES),$(OTHERS))
 414
 415           NEEDED_DEFINES   lists all the defines that HAVE to be set in
 416                            /include/wx/setup.h to compile correctly.
 417
 418           SRC_DIR          lists all directories that are needed to
 419                            compile. (i.e: lists all the directories,
 420                            where there are source-files.) But it is
 421                            also needed to clean an object and for
 422                            machines, for which make does not support
 423                            VPATH
 424
 425 currently there are the following compiling rules provided:
 426 object files are created for the following file extensions:
 427 .c .cc .cpp
 428
 429 Please have a closer look at the Makefiles in this distribution.
 430
 431 * Platforms configure is working with
 432 ---------------------------------------
 433
 434 Please report build succes on any machine. Especially non-
 435 Linux operating systems (which I don't have).
 436
 437 Original author of the autoconf system for wxxt-1.66 and for this INSTALL
 438 file:
 439
 440         Martin Sperl    sperl@dsn.ast.univie.ac.at
 441
 442 Ported to wxGTK 0.1:
 443
 444         Wolfram Gloger  wmglo@dent.med.uni-muenchen.de
 445
 446 Thanks alot to both of them.
 447
 448 In the hope that it will be useful,
 449
 450         Robert Roebling roebling@sun2.ruf.uni-freiburg.de
 451
 452