--------------------------------------- Installation of wxWindows Version 1.68C --------------------------------------- These are the installation notes for wxWindows 1.68C, April 1998. For more details for specific compilers and platforms, please refer to the Frequently Asked Questions document, docs/postscript/faq.ps, or via the wxWindows HTML page http://web.ukonline.co.uk/julian.smart/wxwin. See also the directory ftp.aiai.ed.ac.uk/pub/packages/wxwin/ports for advice and patches for specific compilers and/or platforms. ----- Files ----- The source is available in the following formats, in the directory ftp.aiai.ed.ac.uk:/pub/packages/wxwin/1.68: wx168*.tgz tarred, gzipped files for UNIX setup.* Set of installation files for the PC wx168htm.tgz Optional HTML files wx168ps.tgz Optional PostScript files Note that the PC setup files includes WinHelp documentation, but for the UNIX distribution, you need to download the documentation you require. ---------------- BEFORE YOU START ---------------- Please note that wxWindows is quite complex and there may be some hurdles to overcome. Persistance and a calm approach usually works! Remeber that the wxwin-users mailing list is there to help you out if all seems lost. The wxwin-users archive at our WWW site can also be useful. The PrologIO library can be the most problematic library, so if it doesn't compile first time, read the installation notes in utils/prologio/docs/install.txt (also contained in the manual). A common error is to use a C++ compiler to compile y_tab.c; another is to attempt to compile lex_yy.c (included by y_tab.c). You need PrologIO if you wish to compile wxBuilder or create wxWindows resource files (.wxr). To compile PrologIO under UNIX you must have FLEX (or LEX) and YACC available on your system: see the tools directory in the wxWindows ftp area. Under DOS, the Borland and MS VC++ makefiles use the provided files dosyacc.c and doslex.c, so it is not necessary to have FLEX and YACC. wxWindows source and binaries can take a lot of space on your disk so if you're running Windows, you may wish to consider disk compression, rather than decide to do without the 'overhead' of debugging information. Disk compression is quite reliable these days. In general, please see the FAQ for solutions to particular configuration problems. ---------------- Installation: PC ---------------- 1) Run setup.exe. It should unpack about 18MB of source files and documentation into a directory of your choice, and will also alter autoexec.bat to set the environment variable 'WXWIN'. DO NOT INSTALL into c:\Program Files or any other path containing a space. If you have Borland C++, set BCCDIR to where the compiler is installed. NOTE: do not install wxWindows in a deeply nested subdirectory. DOS and/or Windows compilers sometimes can't cope with this. 2) Edit include/base/wx_setup.h which allows configuration of wxWindows. For MS VC++, the makefile src\msw\makefile.dos (16-bit) or makefile.nt (32-bit) needs to be edited so that variables prefixed USE_ match the settings in wx_setup.h. This controls linking of optional libraries for additional functionality. SEE ALSO 'NOTES ON SUBORDINATE LIBRARIES' BELOW. For VC++ users, probably the easiest thing is to leave wx_setup.h as it is, and just compile as below. Any optional libraries will be made as necessary and included in wx.lib (for Watcom, 16-bit Borland, and VC++ makefiles). For Borland users, change USE_ODBC to 0. For 32-bit Borland compilation, you _may_ need to set USE_GNU_WXSTRING to 0 (see below). 3) For VC++ 16-bit, type 'nmake -f makefile.dos' from src/msw. For VC++ 32-bit, type 'nmake -f makefile.nt' from src/msw. For Borland 16-bit, type 'make -f makefile.bcc' from src, not src/msw. For Borland 32-bit, type 'make -f makefile.b32' from src, not src/msw. For Symantec, type 'make -f makefile.sc' from src. 4) Print wx.ps and referenc.ps on a PostScript printer. The reference manual is around 320 pages, the user manual (wx.ps) is shorter. Alternatively, browse through the wx.hlp Windows Help file or download the HTML versions. Word RTF files are available on request. By default, wxWindows is compiled with debugging information. To compile without debugging information, specify FINAL=1 on your make command line. Note that to produce a non-debugging executable you need only relink your application (or the demo) since any debugging information in the wxWindows library will be removed by the linker if the FINAL flag is set to 1. Notes for Borland users xxxxxxxxxxxxxxxxxxxxxxx See detailed notes for Borland users in the FAQ (docs/faq.hlp or faq.ps). Using the makefiles, the compilation should progress smoothly but watch out for enormous precompiled header files in wx/src. So make sure there's at least 15 MB of free disk space before you start compiling. Borland .bcc and .b32 makefiles behave a bit differently: the .bcc makefiles put .lib files in the respective utility subdirectories, wherease the .b32 makefiles put them in the wx\lib directory. If tlink runs out of memory when linking, you may need to adjust the DOS box memory settings (Auto seems to work best), or switch debugging off (remove -v in src/makefile.bcc and sample's makefile.bcc LINKFLAGS), or as a last resort exit Windows and perform the link from DOS. You will to make at least one change to include\base\wx_setup.h: set USE_ODBC to 0 (if not already 0). If you are compiling 32-bit programs, you _may_ need to set USE_GNU_WXSTRING to 0 (and also in src\msw\makefile.b32). I got some link errors when using GNU wxString with bcc32 and when compiling with no debugging information, but your mileage may differ. Recent versions of Borland C++ use brc instead of rc for the resource compiler so you may need to change makefiles or copy brc.exe to rc.exe (or set up a batch file called brc.bat that calls rc.exe). For compiling the ODBC classes (leaving USE_ODBC set to 1), you need the sql.h, sqlext.h header files which normally come with MFC-enabled compilers such as MS VC++, Symantec, and Watcom. Borland doesn't provide them, and it may not be legal for me to distribute them. But... you can ftp them from Watcom's ftp site: ftp.watcom.on.ca/pub/ps_mirror/watsql/general/odbc_h.zip Notes for Symantec users xxxxxxxxxxxxxxxxxxxxxxxx Makefiles (extension .sc) are provided for the main wxWindows library, essential modules, and the minimal and hello samples. Makefiles and .def files for other modules and samples have not yet been upgraded. Edit src\makesc.env to switch between WIN32 and WIN16 compilation; also, in wx_setup.h, ensure that CTL3D is set to 0 if compiling for WIN32, and set USE_GNU_WXSTRING to 0. Start compiling from the src directory. Makefiles apply to SC++ 6.0; things may have changed in more recent versions. Other points: check that your global INCLUDE variable contains the sc\include\win16 directory, or you will error message such as 'print.h not found'. Notes for users of Turbo C++ 3.x for Windows xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx I successfully compiled early versions of wxWindows with Turbo C++ (although it quickly runs out of space for debugging information). Recently Turbo C++ has crashed at the library creation phase, but others have reported more success. There's a wx.prj file in wx/src/msw containing the basic files; you need to: - Run the file wx/install/turboini.bat to make a central include directory and copy include files into this directory. Or do it by hand. This centralised approach is needed since Turbo C++ can't cope with a long directory include list. - Add the extra files from modules you wish to use in wxWindows, e.g. C/C++ files from contrib/fafa, contrib/itsybits, contrib/gauge, utils/prologio/src (these are y_tab.c, read.cc and prorpc.cc), utils/dib.cc, utils/rcparser/src. - Edit wx_setup.h to reflect the modules you wish to use. - Build wx.lib, and create .prj files for the samples and utilities. I'm sorry there's not better support for Turbo C++, but I have to balance support for recent compilers and maintenance of wxWindows against support for older compilers. I do recommend you upgrade to a more heavyweight compiler such as Borland C++ 4.x or Visual C++, because Turbo C++ is relatively unstable and has debugging problems. Notes for MS C++ Vsn 7 users xxxxxxxxxxxxxxxxxxxxxxxxxxxx Ignore the warnings about unrecognised options when using the makefile.dos makefiles: it didn't seem worthwhile to spend time removing harmless warnings related to newer VC++ options. Recently I found it hard work getting a wx.lib out of this compiler; there were a lot of 'invalid module' errors when creating libraries. This may be due to lack of hard disk space, so make sure you have *lots* of free space (at least 15MB before you start compiling). I eventually had success after freeing space, switching off the wxXPM module (edit makefile.dos, wx_setup.h) and recompiling everything. The status line appears to be drawn without the 3D effect: have yet to track this down. Notes for Visual C++ users xxxxxxxxxxxxxxxxxxxxxxxxxx The C++ file extensions have now all been changed to .cpp, so it should be easier to build a project file. However, it may be simpler to use the makefile to build wx(32).lib, and then create project files for your own applications. The makefiles assume you have settings such as the following in autoexec.bat (or set in a batch file you call just before compiling): set INCLUDE=c:\MSDEV\INCLUDE;c:\MSDEV\MFC\INCLUDE set LIB=c:\msdev\LIB;c:\msdev\MFC\LIB Otherwise the compiler won't find the VC++ include files and libraries. For debugging, you can create a non-MFC project in the IDE, insert the application C++ file(s), fill in the fields in the Project Settings/Debug tab, and press F5 to run the program. When confronted with the dialog that asks if you wish to rebuild the program, answer No. To make a DLL version of wxWindows (only VC++ at present): 1) Edit include\base\wx_setup.h and set: a) USE_WX_RESOURCES to 0 b) USE_GNU_WXSTRING to 0 Do the same in src\msw\makefile.nt. Unfortunately PrologIO can't yet be compiled into a DLL because of a conflict with the 'read' function in lex_yy.c. There's an unknown problem with GNU wxString (complains about not being able to find libci.lib). 2) cd into wx\src\msw. Clean the .obj and .pch files if necessary with the 'cleanall' target. 3) Type: nmake -f makefile.nt dll 4) Then type: nmake -f makefile.nt pch This creates dummy.obj to link with, and a suitable PCH file for wxWindows applications to use. 5) Compile a sample to test the DLL. Edit e.g. \wx\samples\mdi\makefile.nt and put the line WXUSINGDLL=1 before the !include statement. 6) Compile the sample, copy \wx\lib\wx168.dll to the current directory, and run the sample. Note the small size of the .exe :-) - about 70K for the MDI sample. Note: in addition to no PrologIO or GNU wxString support, a DLL version of wxWindows doesn't allow use of a wxTextWindow as a stream buffer, so the hello sample will not compile. Notes for Watcom users xxxxxxxxxxxxxxxxxxxxxx Watcom will compile wxWindows in WIN386 mode and WIN32s mode, but for some reason, not in 16-bit mode. In wx_setup.h, you will need to set USE_ODBC to 0, since as yet there is no interface from the 16-bit odbc.lib to Watcom's 32 bits. However, there _is_ such a thing for the CTL3D library, and the Watcom makefiles are set up to compile and use this and the other usual wxWindows modules (PrologIO, DIB, FAFA, wxString, etc.) Edit the makewat.env file for your compilation mode and directories; all makefiles include this file. See the FAQ for reports of unresolved problems running some of the sample wxWindows applications. Notes for Gnu-Win32/Mingw32 users xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx From wxWindows 1.68C, both Gnu-Win32 b19 and Mingw32 (the minimal distribution of Gnu-Win32) can be used with the same makefiles. Thanks are due to Keith Garry Boyce (garp@opustel.com) and Cygnus for making it all possible. Here are the steps required: - Retrieve and install the latest beta of Gnu-Win32, or Mingw32, as per the instructions with either of these packages. - If using Mingw32 (including the EGCS variant), you need some extra files to use the wxWindows makefiles. You can find these files in ports/mingw32 on the ftp site or CD-ROM, as extra.zip. These should be extracted to the Mingw32 directory. - Modify the file wx/src/cygnus.bat (or mingw32.bat or mingegcs.bat) to set up appropriate variables, if necessary mounting drives. Run it before compiling. - For Gnu-Win32, make sure there's a \tmp directory on your Windows drive or bison will crash. - Edit wx/src/makeg95.env and search for MINGW32. Take note of the comments for adjusting settings to suit Gnu-Win32 or Mingw32. Basically, this is just a case of adding the __MINGW32__ symbol to OPTIONS for Mingw32, or removing it for Cygnus Gnu-Win32. For Mingw32/EGCS, add both __MINGW32__ and __EGCS__. - Use the makefile.g95 files for compiling wxWindows and samples, e.g.: > cd c:\wx\src\msw > make -f makefile.g95 > cd c:\wx\samples\hello > make -f makefile.g95 - Use the 'strip' command to reduce executable size. - With Cygnus Gnu-Win32, you can invoke gdb --nw myfile.exe to debug an executable. - If using GnuWin32 b18, you will need to copy windres.exe from e.g. the Mingw32 distribution, to a directory in your path. Gotchas: - libwx.a is 28 MB or more. - install.exe doesn't have built-in decompression because lzexpand.lib isn't available with Gnu-Win32. However, you can use it with external decompression utilities. References: - The GNU-WIN32 site is at http://www.cygnus.com/gnu-win32/ - Mingw32 is available at: http://agnes.dida.physik.uni-essen.de/~janjaap/mingw32/index.html - See also http://web.ukonline.co.uk/julian.smart/wxwin/gnuwin32.htm ------------------ Installation: UNIX ------------------ (See also 'Notes for Linux users' below this). Use the wxinstal script in the install directory or on the ftp site. This uses conventional makefiles and requires adjustment of some paths and settings. In the directory contrib/wxshlib, in the wxWindows distribution, there is a contributed GNU configure script for wxWindows, which you may find easier to work with than the makefiles provided. However, I have not yet had time to test the configure script and make it the default method of installation. To install by hand using conventional makefiles: 1) Unarchive wx168_1.tgz, wx168_2.tgz, Unarchive one or more appropriate document archives e.g. wx168ps.tgz or wx168htm.tgz. 2) If you want to use XView and XView 3.x is not present, install it (it's available free on the Net). Your LD_LIBRARY_PATH may need to be altered or disabled. 3) If GCC/G++ is not installed, install it (again, freely available). Or you could try an alternative compiler (AT&T C++ is known to work with wxWindows). 4) Edit include/base/wx_setup.h which allows configuration of wxWindows. For MS VC++, the makefile src\msw\makefile.dos also needs to be edited so that variables prefixed USE_ match the settings in wx_setup.h. This controls linking of optional libraries for additional functionality. SEE ALSO 'NOTES ON SUBORDINATE LIBRARIES' BELOW. Probably the easiest thing is to leave wx_setup.h as it is, and just compile as below. Any optional libraries will be made as necessary and included in wx.lib. 5) Edit src/make.env, which has many options common to all wxWindows makefiles. 6) Change directory to src/x, and type 'make -f makefile.unx xview' or 'make -f makefile.unx motif'. With luck, libwx_ol.a or libwx_motif.a should end up in the lib directory. 7) Set the WXHELPFILES environment variable to point to the docs directory. 8) Compile the demos and utilities. Again, specify 'xview' or 'motif' as target. The 'minimal' demo is a good one to start with, and 'hello' uses many GUI features that should test if wxWindows is functioning properly. If you wish to use the wxHelp hypertext help system, either for your own applications or for viewing the wxWindows class library reference, you will need to do download the binaries (in wxhelp14.tar.Z) or make wxHelp as follows: 10) Change directory into utils/wxhelp/src and type 'make -f makefile.unx xview' or 'make -f makefile.unx motif'. You may wish to strip the resulting executable of debugging information, e.g. 'strip wxhelp_ol'. 11) Copy wxhelp_ol or wxhelp_motif into a directory on your path, where it can be executed as 'wxhelp', and read the wxHelp documentation. XView problems -------------- If you are likely to be using XView and modal windows, where the flow of the program is stopped until the user responds, you will need to link sb_scrol.o and xvwinlp.o with your application. These are XView atches which (sort of) fixes listboxes on modal dialogs (i.e. on a window within xv_window_loop). Listboxes don't scroll without the patch. Other widgets may be affected by this bug. You will need to compile sb_scrol.c and xvwinlp.c. Important: use a C compiler for this file, not C++. SEE ALSO XVIEW.TXT. By default, wxWindows is compiled with debugging information. To compile without debugging information, specify DEBUGFLAGS='' on your make command line or edit make.env (UNIX only). ==== Miscellaneous notes === Notes for AIX xxxxxxxxxxxxx On AIX (perhaps other?) platforms you may get the following error message: "You need to define an instance of wxApp" in the samples. You need to include main() in the file where you declare your global wxApp. Use the WXWIN_IMPLEMENT_MAIN macro to do this (see hello.cc). Notes for SGI xxxxxxxxxxxxx For SGI, include -lPW on your LDLIBS line in all makefiles. Notes for HP/UX xxxxxxxxxxxxxxx For HP/UX, use FLEX for building PrologIO. You may need to comment out the #define yywrap line in the generated lex_yy.c. Also: if compiling with G++ 2.6.3 (perhaps other versions?), you will need to remove the file rx.o from libg++, because it contains a bug that causes the file selector to crash. You may want to make a copy of libg++ so as not to disturb other users of it. Use: ar d libg++.a rx.o A warning: if you create a copy of libg++.a, say libwx_g++.a, without rx.o, be sure to call the compiler from your makefiles as "gcc", because "g++" is an alias which automatically generates a reference to the original libg++ (-lg++). Thus even if you mention -lwx_g++ in you makefiles, your changes might not seem to work. This fix might be needed on other platforms too. For more details on this problem, and other methods of alleviating it, see the FAQ. IPC on HP/UX has a problem to do with a bug in sscanf; to use IPC, replace calls to sscanf in wx_ipc.cc with something else, e.g. atod. If you get an undefined 'main' symbol when linking, edit include/base/wb_main.h, remove the comments around the __hpux part of the #if defined... line above IMPLEMENT_WXWIN_MAIN, and recompile everything. ------------------------------ Notes on subordinate libraries ------------------------------ The makefiles are arranged so that several `subordinate' libraries are compiled into wx.lib (or wx_motif.a or whatever). This means that configuration of wxWindows is centralized, and it's not necessary to fiddle with many makefiles if you decide to compile in a specific wxWindows feature. These little libraries add optional functionality to wxWindows, supported in the wxWindows class library but the bulk of the functionality being implemented separately for modularity (and potential copyright) reasons. Unfortunately, you do have to edit both wx_setup.h and the makefile in src/x or src/msw in order to configure wxWindows. So it may be easier to compile all libraries rather than try to configure wxWindows, unless you're really having trouble compiling one of the libraries. Here's a list of the optional libraries (found in wx/contrib or wx/utils). The relevant wx_setup.h identifier is given in brackets. CTL3D Windows only: allows use of 3D style controls (CTL3D). FAFA Windows only: allows use of bitmap buttons, messages and radiobuttons (FAFA_LIB). wxString Use improved wxString and regular expression class (USE_GNU_WXSTRING). ItsyBitsy Windows only: supports tiny titlebars (USE_ITSY_BITSY). Gauge Windows only: necessary for implementation of wxGauge class (USE_GAUGE). xmGauge Motif only: necessary for implementation of wxGauge class (USE_GAUGE). wxXPM All platforms: necessary for implementation of XPM pixmap functionality (USE_XPM_IN_X, USE_XPM_IN_MSW). DIB Windows only: necessary for implementation of BMP loading/saving functionality (USE_IMAGE_LOADING_IN_MSW). wxImage X only: necessary for implementation of BMP, GIF loading functionality (USE_IMAGE_LOADING_IN_X). PrologIO All platforms: necessary for .WXR wxWindows resource-loading functionality (USE_MSW_RESOURCES). RCPARSER Windows only: necessary for dynamic icon loading (USE_RESOURCE_LOADING_IN_MSW). Note that if you don't compile in DIB, you could still use wxLoadBitmap in an application and link with dib.lib separately in your application makefile. Similarly, you can use PrologIO and RCPARSER independently without them being compiled into wx.lib. --------------------- Notes for Linux users --------------------- Reducing binary size -------------------- Some of the following information also applies to users of GCC on other platforms. The large size of binaries has been a worry for Linux users (who are probably pushing the limits of their hard disk capacity as it is). From version 1.60, the size of the wxWindows library has been reduced using #pragmas. You can reduce the size further by compiling out unnecessary wxWindows modules, by editing wx_setup.h. If GCC detects that no debugging information is present, in either the wxWindows library or the application object files, the binary will be linked _dynamically_ to various libraries including X11 and XView (but not wxWindows without special treatment: see below). In this case, hello_ol reduces to 480K. A kit to build a dynamic version of the wxWindows library can be found in wx/contrib/linuxshr.zip, or /pub/packages/wxwin/contrib on the AIAI ftp site. This reduces binaries still further (to around the 100K mark in the case of hello_ol). Dynamic libraries have the disadvantage of causing confusion when distributing binaries, and also cannot contain debugging information. ------------------------------------------------------- Known platforms and compilers compatible with wxWindows ------------------------------------------------------- (please let me know of any others!) PC 386SX and above Sun: SunOS and Solaris 2.x Silicon Graphics IRIX Linux Windows 3.1, Windows 95, Windows NT HPUX AIX/RS6000 Apollo ULTRIX VMS Gnu C++ (GCC) AT&T C++ SunPro C++ HP C++ Microsoft C/C++ 7 Microsoft Visual C++ 1.x, 2.x, 4.x, 5.x Borland C++ 3.1, 4.x, 5.x Borland Turbo C++ for Windows (with reservations: see above) Symantec C++ Watcom C++ (32-bit mode only) GNU-WIN32 --------------- FURTHER DETAILS --------------- There are various options which are controlled by settings in the file include/base/wx_setup.h. Some settings allow omission of large chunks of wxWindows functionality. This can be useful to reduce debugging executable size, for example. Other settings control the appearance of GUI elements, such as the use of 3D-look controls under Windows. Please see the manual and FAQ for further details. If you have difficulty compiling, please refer to the FAQ; see also information on our WWW pages. The /pub/packages/wxwin/ports directory contains recent contributions for particular platforms. GUI BUILDER ----------- wxBuilder, a GUI builder for wxWindows, is supplied in source form in wxWindows (quite difficult to compile owing to the use of nasty YACC and LEX-generated C code). A Windows binary may be obtained by ftp. Note that so far, wxBuilder only runs under Windows and Sun or HP Motif. The Open Look version has difficulties because multiple modal dialogs are used, but some people still find it useful (especially if they apply patches as documented in xview.txt). You may wish to try the Dialog Editor instead, which has less functionality but is more stable than wxBuilder. wxCLIPS ------- wxCLIPS is a CLIPS interface to much of wxWindows functionality, and is available from ftp.aiai.ed.ac.uk/pub/packages/wxclips and http://web.ukonline.co.uk/julian.smart/wxclips. For other useful utilities and packages, see the wxWindows Web site at http://web.ukonline.co.uk/julian.smart/wxwin.