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