install/gtk/INSTALL

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