INSTALL

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