docs/os2/install.txt

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