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