home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / wxos2240.zip / install-os2-2_4_0.txt < prev    next >
Text File  |  2003-01-18  |  12KB  |  255 lines
  1. Installing wxWindows 2.4.0
  2. --------------------------
  3.  
  4. This is wxWindows 2.4.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 wxWindows web site.
  13.  
  14. Unarchiving
  15. -----------
  16.  
  17. At this time there is no comprehensive setup.exe type installation program.
  18. wxWindows 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\wxWindows-2.4.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 wxWindows 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.4.0.zip, documentation
  34. must be downloaded separately from the wxWindows Web site.
  35.  
  36. Other add-on packages are available from the wxWindows 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\wxWindows-2.4.0\docs (your HTML reference manual)
  50. x:\wx\wxWindows-2.4.0\include\wx
  51. x:\wx\wxWindows-2.4.0\include\wx\generic
  52. x:\wx\wxWindows-2.4.0\include\wx\html
  53. x:\wx\wxWindows-2.4.0\include\wx\os2
  54. x:\wx\wxWindows-2.4.0\samples\....  (all the sample directories)
  55. x:\wx\wxWindows-2.4.0\src
  56. x:\wx\wxWindows-2.4.0\src\common
  57. x:\wx\wxWindows-2.4.0\src\generic
  58. x:\wx\wxWindows-2.4.0\src\html
  59. x:\wx\wxWindows-2.4.0\src\jpeg
  60. x:\wx\wxWindows-2.4.0\src\os2
  61. x:\wx\wxWindows-2.4.0\src\png
  62. x:\wx\wxWindows-2.4.0\src\tiff
  63. x:\wx\wxWindows-2.4.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\wxWindows-2.4.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.4.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 wxWindows 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.  wxWindows 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 wxWindows 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. If you donwloaded wxAll-2.4.0, the directories will contain unix versions
  172. of all configure scripts which need to be replaced by the OS/2 enhanced
  173. versions contained in e.g. \wx\wxWindows-2.4.0\docs\os2\os2-specific.zip.
  174. For this purpose change into the top level directory (\wx\wxWindows-2.4.0)
  175. and call "unzip docs\os2\os2-specific.zip" (assuming you have InfoZip's
  176. unzip installed). Of course, replace \wx\wxWindows-2.4.0 by the path you
  177. did choose.
  178.  
  179. Once you are done with those preliminaries, the first thing to do is to
  180. decide on a build directory. You can either do in-tree builds or you can
  181. do the build in a directory separated from the source directory. The later
  182. has the advantage, that it is much easier to compile and maintain several
  183. ports of wxWindows on OS/2 - if you are developping cross-platform
  184. applications you might want to compile (and update) e.g. wxGTK or wxX11
  185. as well.
  186.  
  187. In the following, let's assume you decided to build in
  188. \wx\wxWindows-2.4.0\build\pm. Now we need to set some environment
  189. variables, namely MAKE_SHELL (to a Unix like shell, let's assume ash)
  190. and INSTALL (to point to the install script. If you omit this, configure
  191. might find something like the system's tcpip\pcomos\install.exe which will
  192. not do the thing you want), e.g.
  193. SET MAKE_SHELL=ash
  194. SET INSTALL=/wx/wxWindows-2.4.0/install-sh.
  195.  
  196. Be warned that depending on the precise version of your make, setting
  197. MAKE_SHELL might not be sufficient, it might be necessary to set SHELL
  198. and even COMSPEC to a unix like shell as well.
  199.  
  200. Now run the provided configure script by executing e.g.
  201. `ash -c "../../configure \
  202.    --prefix=directory_where_you_want_wxWindows_to_be_installed"'
  203. from within the build directory (the relative path might be different
  204. depending on the build directory you selected).
  205. If you are already running some unix-like shell and not cmd, you may
  206. of course ommit the `ash -c' part in the above command.
  207. This will create a whole directory structure containing lib and sample
  208. directories which each essentially contain a suitable makefile.
  209.  
  210. Calling `make' now should start a compile run which hopefully ends
  211. with a library being placed in the lib subdirectory.
  212.  
  213. Note however, that the auto-generated .d files (containing depency
  214. information) use a mixture of "/" and "\" path separators, that
  215. confuses many make versions. Therefore you'll often get error messages
  216. indicating that some file with a random character in place of a path
  217. separator cannot be found on subsequent calls to make. The only solution
  218. currently available for this requires "sed": Run
  219.  for %1 in (*.d) do @(sed "s/\//\\/g" < %1 > dep.sed && copy dep.sed %1)
  220. under "cmd" in the build directory (or a suitable variant of it under a 
  221. unix like shell). Note however, that a new call to make will generate
  222. new .d files, so you will likely have to run that between any two calls
  223. to make.
  224.  
  225. Now you can change in the samples subdirectory and call make to compile
  226. all samples, however currently not all will work on OS/2, so you might
  227. prefer to change into the directory of a specific sample
  228. (e.g. samples\minimal) and call make there to just build this one example.
  229. Essentially, each sample that's not working indicates an area, where help
  230. in porting wxWindows to OS/2 would be appreciated.
  231.  
  232. Finally, you can run `make install' which should install wxWindows to
  233. the desired place.
  234. Note that we also install the wx-config script which wants to help you
  235. compiling your own applications, e.g. `wx-config --cxxflags` will emit the
  236. flags that are needed for compiling source code which includes wxWindows
  237. headers, `wx-config --libs` will emit the flags needed for linking against
  238. wxWindows (wx-config is assuming you are calling it from a unix-like shell!).
  239.  
  240. For building a DLL, the only supported way currently is to first build the
  241. static library and then use Andrew Zabolotny's dllar.cmd. However, this
  242. works quite nicely.
  243.  
  244. Finally, if you also want to build a different port, e.g. wxGTK, you
  245. essentially have to use the procedure described above, the only difference
  246. being that you have to pass a switch to configure indicating which port
  247. to build. If you do not do this in a separate build directory (e.g.
  248. \wxWindows-2.4.0\build\gtk), you'll have to do a `make clean' first.
  249. The magical switches that have to be passed to configure for the various
  250. ports are --with-gtk (wxGTK), --with-motif (wxMotif), --with-x11 (wxX11),
  251. and --disable-gui (wxBase). Note that contrary to the native, PM based
  252. OS/2 port, all of those ports work slightly better with POSIX/2's cExt
  253. library. If include and library path include the suitable paths, -lcExt
  254. is automatically appended to the linker flags by the configure script. 
  255.