install/unix/INSTALL

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