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