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 gcc -o -c myfoo.cpp -I/usr/local/include -L/usr/local/lib -lwx_gtk
  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. The first creates
 260 a project within the source code directories of wxWindows: In this
 261 case I propose to put all contributed programs in the directory
 262 "/user", with a directory of its own.
 263
 264 This directory then should include the following files:
 265
 266 Makefile        (You can copy this one from any application in samples
 267                  probably you will not need to edit this one. There is
 268                  only one case where you might be interested in changing
 269                  this file, but about that see later.)
 270 Makefile.in     (This is the base application-Makefile template, from
 271                  which the actual Makefile for each system is created.
 272                  More about this later)
 273
 274 put ALL your source code along with all the other stuff you need for
 275 your application in this directory (subdirectories are welcome).
 276
 277 The other way uses the installed libraries and header files in
 278 /usr/local/include/wx and /usr/local/lib. In this case, just
 279 compile your program like this:
 280
 281 gcc -o -c myfoo.cpp -I/usr/local/include -L/usr/local/lib -lwx_gtk
 282
 283
 284 ** Something about Makefiles
 285 ------------------------------
 286
 287 On general principle it should only contain ONE line, which is as follows:
 288
 289         include ../../setup/general/makeapp
 290
 291 this will include all the necessary definitions for creating the applications
 292
 293 the only case where you might want to add another line is the following:
 294 this version of configure also supports creation of source archives of the
 295 application for easy distribution and updates to newer version of wxWindows.
 296     For this purpose all files in the application-directory will be put into
 297 a gziped tar-file in the full notation user/<your application>/*
 298 if you want to include some other files that you want "more visible", like
 299 a README.<yourApp> or a shell script for easy
 300 compilation/installation/distribution, then you have to add a variable
 301
 302         DISTRIBUTE_ADDITIONAL=<your files>
 303
 304 to the Makefile.
 305 So it would look like this:
 306
 307         DISTRIBUTE_ADDITIONAL=README.TheApp
 308         include ../../setup/general/makeapp
 309
 310 As we have already talked about distribution the command to create a
 311 distribution is:
 312
 313         make distrib
 314
 315 NOTE: If you are in the base directory of wxWindows it will create
 316 distribution packages for wxWindows as well as for all packages in the
 317 user directory.
 318     So if you want to create only packages for the files in user,
 319 then go to the directory other and type:
 320
 321         make distrib
 322
 323 or if you only want one application to be created then
 324 enter the specific directory and type there:
 325 make distrib
 326
 327 All the distribution files will be put in the directory
 328 distrib at the base of the wxWindows-tree (where also configure
 329 and template.mak can be found).
 330
 331 ** Something about Makefile.in
 332 --------------------------------
 333
 334 As you have already seen with Makefile, configure makes a lot of use
 335 if the include statement in make to keep the Makefiles as simple as
 336 possible.
 337
 338 So basically there are only variables to define and then a include command.
 339 Exception to this rule is if you have special rules for some stuff...
 340 These rules should go AFTER the include statement!!!
 341
 342 so the general header looks like this:
 343
 344         # wxWindows base directory
 345         WXBASEDIR=@WXBASEDIR@
 346         # set the OS type for compilation
 347         OS=@OS@
 348         # compile a library only
 349         RULE=bin
 350
 351 and the general footer will look like this:
 352
 353         # include the definitions now
 354         include ../../../template.mak
 355
 356 the key variable is RULE, which defines what make should create
 357 in this directory.
 358
 359 here are some examples:
 360
 361   RULE    description
 362   ===========================================================================
 363   bin     creates a local binary (for a global binary prefix bin with g)
 364           additional variables needed:
 365                 BIN_TARGET      this gives the name of your application
 366                 BIN_OBJ         this gives the object files needed to
 367                                 link the application
 368           optional variables are:
 369                 BIN_SRC         this gives the list of c/c++ files for
 370                                 which dependencies will be checked.
 371                                 (This can be achieved with: make depend)
 372                 BIN_LINK        this gives commands for additional
 373                                 libraries needed to link the application
 374   ---------------------------------------------------------------------------
 375   bin2    creates two local binaries (for global binaries prefix bin2 with g)
 376           in addition to the variables specified above you MUST also
 377           provide the same variables with BIN2_ instead of BIN_
 378   ---------------------------------------------------------------------------
 379   lib     creates a local library (for a global binary prefix bin with g)
 380           additional variables needed:
 381                 LIB_TARGET      this gives the name of your library
 382                 LIB_OBJ         this gives the object files needed for
 383                                 the library to be build.
 384           optional variables are:
 385                 LIB_SRC         this gives the list of c/c++ files for
 386                                 which dependencies will be checked.
 387           libbin and libgbin are also possible and will need in addition
 388           the variables from bin
 389   ---------------------------------------------------------------------------
 390   gslib   is similar to lib, but it creates a shared library if the system
 391           supports it.
 392           additional variables needed:
 393                 LIB_MAJOR       major number of the shared library
 394                 LIB_MINOR       minor number of the shared library
 395   ---------------------------------------------------------------------------
 396   other additional variables:
 397
 398           ADD_COMPILE      define additional includes/defines that
 399                            are needed to compile the object files
 400                            (if you need to reference some directory
 401                            utils - like wxGrid -, then please
 402                            reference them with the variables defined
 403                            in template.mak - e.g.: $(SRCDIR),$(UTILS),
 404                            $(SAMPLES),$(OTHERS))
 405
 406           NEEDED_DEFINES   lists all the defines that HAVE to be set in
 407                            /include/wx/setup.h to compile correctly.
 408
 409           SRC_DIR          lists all directories that are needed to
 410                            compile. (i.e: lists all the directories,
 411                            where there are source-files.) But it is
 412                            also needed to clean an object and for
 413                            machines, for which make does not support
 414                            VPATH
 415
 416 currently there are the following compiling rules provided:
 417 object files are created for the following file extensions:
 418 .c .cc .cpp
 419
 420 Please have a closer look at the Makefiles in this distribution.
 421
 422 * Platforms configure is working with
 423 ---------------------------------------
 424
 425 Please report build succes on any machine. Especially non-
 426 Linux operating systems (which I don't have).
 427
 428 Original author of the autoconf system for wxxt-1.66 and for this INSTALL
 429 file:
 430
 431         Martin Sperl    sperl@dsn.ast.univie.ac.at
 432
 433 Ported to wxGTK 0.1:
 434
 435         Wolfram Gloger  wmglo@dent.med.uni-muenchen.de
 436
 437 Thanks alot to both of them.
 438
 439 In the hope that it will be useful,
 440
 441         Robert Roebling roebling@sun2.ruf.uni-freiburg.de
 442
 443