docs/os2/install.txt

   1 Installing wxWidgets
   2 --------------------
   3
   4 This is wxWidgets for IBM OS/2 Warp3 and Warp4. This is an unstable
   5 development release and OS/2 is considered to be in beta.
   6
   7 IMPORTANT NOTE: If you experience problems installing, please
   8 re-read this instructions and other related files (changes.txt,
   9 readme.txt, notes on the Web site) carefully before mailing
  10 wx-users or the author. Preferably, try to fix the problem first and
  11 then send a patch to the author. Please report bugs using the
  12 bug report form on the wxWidgets web site.
  13
  14 Unarchiving
  15 -----------
  16
  17 At this time there is no comprehensive setup.exe type installation program.
  18 wxWidgets for OS/2 requires you download various .zip files and unpack them
  19 to your desired location on your system.  Pick a location say,
  20 C:\wx\wxWidgets-2.8.0, copy the .zip files to there and unzip them ensuring you
  21 unzip the subdirectories as well.  You will need:
  22
  23 - All common, generic and OS2-specific wxWidgets source;
  24 - samples;
  25 - documentation in HTML Help format;
  26 - makefiles for VisualAge V3.0 (possibly for EMX and Watcom C++);
  27 - JPEG, TIFF, PNG, ZLIB, wxSTC, REGEX, EXPAT library sources.
  28
  29 All but the documentation is included in wxOS2-2.8.0.zip, documentation
  30 must be downloaded separately from the wxWidgets Web site.
  31
  32
  33 General installation notes
  34 --------------------------
  35
  36 After unzipping everything your directory tree should look something like
  37 this:
  38
  39 x:\wx\wxWidgets-2.8.0\docs (your HTML reference manual)
  40 x:\wx\wxWidgets-2.8.0\include\wx
  41 x:\wx\wxWidgets-2.8.0\include\wx\generic
  42 x:\wx\wxWidgets-2.8.0\include\wx\html
  43 x:\wx\wxWidgets-2.8.0\include\wx\os2
  44 x:\wx\wxWidgets-2.8.0\samples\....  (all the sample directories)
  45 x:\wx\wxWidgets-2.8.0\src
  46 x:\wx\wxWidgets-2.8.0\src\common
  47 x:\wx\wxWidgets-2.8.0\src\generic
  48 x:\wx\wxWidgets-2.8.0\src\html
  49 x:\wx\wxWidgets-2.8.0\src\jpeg
  50 x:\wx\wxWidgets-2.8.0\src\os2
  51 x:\wx\wxWidgets-2.8.0\src\png
  52 x:\wx\wxWidgets-2.8.0\src\tiff
  53 x:\wx\wxWidgets-2.8.0\src\zlib
  54
  55 If you are using VisualAge, you will also need to ensure you have a
  56 \lib directory as well, x:\wx\wxWidgets-2.8.0\lib
  57 and you will have to set a WXWIN environment variable in your
  58 config.sys,
  59 SET WXWIN=X:\WX\WXWINDOWS-2.8.0;
  60
  61 Compilation
  62 -----------
  63
  64 For now, only VisualAge V3.0 FP 8 and EMX-0.9d (with fix4) are supported.
  65 However, the library has been successfully compiled with Watcom C++ as
  66 well. As those build environments get a bit more "formalized", I will add
  67 them here.
  68
  69 Compilation with VisualAge on the one hand and EMX on the other hand are
  70 rather different, VisualAge is essentially following Windows' way of doing
  71 it, EMX is following the example of the unix ports.
  72
  73 Compilation with VisualAge
  74 --------------------------
  75
  76 In addition to VisualAge V3.0 Fixpack 8 you will need the following in order
  77 to successfully build and use wxWidgets for OS/2:
  78
  79 1.  IBM OS/2 Toolkit Version 4.5 or later
  80 2.  IBM TCPIP V4.0 or later
  81 3.  You will need the IBMLAN Lan Requester service and UPM if you wish to use
  82     network based components of the library (generally a standard part of any
  83     Warp Connect 3.0 or Warp 4.0 installation.
  84 4.  I strongly suggest that you have the latest IBM fixpacks installed for
  85     all your components.
  86
  87 Go to the \src directory and open the file, makeva.env (there should be a
  88 .env for each supported compiler when they are fully supported), for edit.
  89 This is where the "make" environment for wxOS2 is set.  Locate UMPLIB, NETLIB,
  90 and TCPIP environment variables about 20 lines down.  Set these to match
  91 your system.
  92
  93 There are number of possible outputs you can produce.  There is a static
  94 lib and a dynamically linked lib, and both can be built in debug or release
  95 mode.  Since wxOS2 is a beta and a rough one at that, I suggest, for now,
  96 you stick to the debug builds.  The resultant linkable binaries will be
  97 output to the \lib directory as will the .dll files.  The statically linked
  98 lib will be named wx.lib.  Each of the third party libs will be there as well,
  99 including png.lib, jpeg.lib, tiff.lib, and zlib.lib.  For DLL builds the
 100 import libs will have the same name, only with a 'd' appended.  Thus the
 101 import library for the main lib in a dll build is wxd.lib.
 102
 103 Object modules will be output into paths dictated by the build mode.  For
 104 example, for debug static the outputs will be in DebugOS2, for DLLs in
 105 DebugOS2DLL.
 106
 107 For your first build, you can directly build the library.  For subsequent
 108 builds you will want to "clean" the output paths.  To build the static library
 109 go to \src and execute nmake all -f makefile.va.  To clean out the outputs
 110 execute nmake clean -f makefile.va.
 111
 112 To build the wx.dll execut nmake all -f makefile.va WXMAKINGDLL=1.  To clean
 113 the outputs execute namek clean -f makefile.va WXMAKINGDLL=1.  For
 114 VisualAge 3.0 we use the module definition file method.
 115
 116 If, for some reason you encounter linking problems with your dll build you may
 117 need to rebuild the module definition file, wx23.def, found in \src\os2.  To
 118 do this you need to have a static version built.  Go to the \lib directoy and
 119 execute CPPFILT /B /P wx.lib>temp.def.  Copy this file to \src\os2.  Delete
 120 the temp.def from your \lib directory.
 121
 122 I find the following to be the easiest to reconstruct the .def file.  Open
 123 both the wx23.def and the temp.def file.  Copy the header of the wx23.def to
 124 the clipboard and paste it into the top of the temp.def file.  If you have
 125 a valid SQL database client with its SDK on your system you can skip the next
 126 step.  wxWidgets included some ODBC and SQL modules.  They expect the standard
 127 sql.h and such to available.  If you do not have a database client with its
 128 SDK (such as DB/2) then for the .dll build you need to delete the exports for
 129 the following three modules from your temp.def file, db.cpp, dbgrid.cpp and
 130 dbtable.cpp.  save you changes to temp.def.  Delete wx23.def and rename your
 131 temp.def to wx23.def and you are ready to go.
 132
 133 I hope to clean up the .dll builds at some point before the library is
 134 a full fledged production caliber product.  Fortunately EMX and Watcom can use
 135 the import and export pragmas successfully negating the need for manual .def
 136 files.  VA 3.0, unfortunately in C++ does not properly export the mangled
 137 names so we are stuck with the CPPFILT .def file method of .dll builds for
 138 now.
 139
 140 When building an application that uses the wx.dll you need to build it using
 141 the WXUSINGDLL=1 macro.  For example to build the minimal sample you would
 142 go to \samples\minimal and execute nmake all -f makefile.va WXUSINGDLL=1.
 143
 144 I strongly suggest when developing apps using wxWidgets for OS/2 under old
 145 VisualAge 3.0, that you use the dynamically linked library. The library is
 146 very large and even the most trivial statically linked .exe can be very
 147 large and take a long time to link.  The release builds are much smaller,
 148 however.  Fortunately, EMX seems to build much smaller static executables.
 149
 150 Compilation using EMX
 151 ---------------------
 152
 153 In addition to EMX-0.9d you will need a rather complete Unix-like
 154 environment, starting with a shell (e.g. ash) and most of the
 155 GNU file/text/shell utilities, but also flex, bison, sed, grep, awk
 156 and GNU make. Particularly note that uname is relevant to get the
 157 configure script working - the one from GNU shell utilities 1.12
 158 does work (check that uname -s returns "OS/2" and uname -m returns "i386"
 159 and you should be mostly fine.
 160
 161 The first thing to do is to decide on a build directory. You can either
 162 do in-tree builds or you can do the build in a directory separated from
 163 the source directory. The later has the advantage, that it is much easier
 164 to compile and maintain several ports of wxWidgets on OS/2 - if you are
 165 developping cross-platform applications you might want to compile (and
 166 update) e.g. wxGTK or wxX11 as well.
 167
 168 In the following, let's assume you decided to build in
 169 \wx\wxWidgets-2.8.0\build\pm. Now we need to set some environment
 170 variables, namely MAKESHELL (to a Unix like shell, let's assume ash)
 171 and INSTALL (to point to the install script. If you omit this, configure
 172 might find something like the system's tcpip\pcomos\install.exe which will
 173 not do the thing you want), e.g.
 174 SET MAKESHELL=ash
 175 SET INSTALL=/wx/wxWidgets-2.8.0/install-sh -c
 176
 177 Be warned that depending on the precise version of your make, the
 178 variable that needs to be set might be MAKE_SHELL instead of MAKESHELL.
 179 If you have a really deficient version of GNU make, it might even be
 180 necessary to set SHELL or even COMSPEC to a unix like shell as well.
 181
 182 Now run the provided configure script by executing e.g.
 183 `ash -c "../../configure \
 184    --prefix=directory_where_you_want_wxWidgets_to_be_installed"'
 185 from within the build directory (the relative path might be different
 186 depending on the build directory you selected).
 187 If you are already running some unix-like shell and not cmd, you may
 188 of course ommit the `ash -c' part in the above command.
 189 This will create a whole directory structure containing lib and sample
 190 directories which each essentially contain a suitable makefile.
 191
 192 Calling `make' now should start a compile run which hopefully ends
 193 with a library being placed in the lib subdirectory.
 194
 195 Now you can change in the samples subdirectory and call make to compile
 196 all samples, however currently not all will work on OS/2, so you might
 197 prefer to change into the directory of a specific sample
 198 (e.g. samples\minimal) and call make there to just build this one example.
 199 Essentially, each sample that's not working indicates an area, where help
 200 in porting wxWidgets to OS/2 would be appreciated.
 201
 202 Finally, you can run `make install' which should install wxWidgets to
 203 the desired place.
 204 Note that we also install the wx-config script which wants to help you
 205 compiling your own applications, e.g. `wx-config --cxxflags` will emit the
 206 flags that are needed for compiling source code which includes wxWidgets
 207 headers, `wx-config --libs` will emit the flags needed for linking against
 208 wxWidgets (wx-config is assuming you are calling it from a unix-like shell!).
 209
 210 For building a DLL, the only supported way currently is to first build the
 211 static library and then use Andrew Zabolotny's dllar.cmd. However, this
 212 works quite nicely.
 213
 214 Finally, if you also want to build a different port, e.g. wxGTK, you
 215 essentially have to use the procedure described above, the only difference
 216 being that you have to pass a switch to configure indicating which port
 217 to build. If you do not do this in a separate build directory (e.g.
 218 \wxWidgets-2.8.0\build\gtk), you'll have to do a `make clean' first.
 219 The magical switches that have to be passed to configure for the various
 220 ports are --with-gtk (wxGTK), --with-motif (wxMotif), --with-x11 (wxX11),
 221 and --disable-gui (wxBase). Note that contrary to the native, PM based
 222 OS/2 port, all of those ports work slightly better with POSIX/2's cExt
 223 library. If include and library path include the suitable paths, -lcExt
 224 is automatically appended to the linker flags by the configure script.