| 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 | - 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. |