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