--------------------------------------
Installation of wxWindows Version 1.68
--------------------------------------

*** This file has been modified from Julian Smart's (the author's) 
    original due to distribution differences.

These are the installation notes for wxWindows 1.68,
November 1997. For more details for specific compilers and
platforms, please refer to the Frequently Asked Questions
document, available after the source installation at 
docs/winhelp/faq.hlp, or via the wxWindows HTML page 
http://web.ukonline.co.uk/julian.smart/wxwin. It is also
included in the optional documentation listed below.


-----
Files
-----

The source is available at the Simtel.net distribution for the MS-Windows 
version, in the directory ftp.simtel.net/pub/simtelnet/win95/prog/. Before
you proceed, make sure you have downloaded wx168_1.zip and wx168_2.zip. 
After unzipping, check to see that you have the following files, which are 
necessary to install the wxWindows source:

 setup.exe
 setup.w01
 setup.w02
 setup.w03      
 
Optional documentation is also available in the following formats:

 wx168htm.zip     HTML files
 wx168ps.zip      PostScript files
 wx168pdf.zip     Adobe Acrobat (PDF) files


Note that the Setup program installs WinHelp documentation as well.

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

wxWindows source and binaries can take a lot of space on your disk so 
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
------------

After downloading and unzipping the necessary files...

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) Downloading documentation of some sort is highly recommended. If you
   choose to do so, unzip the documentation file to the directory you
   installed the wxWindows source to, and make sure to restore all
   directories when unzipping (use the -d switch in PKUNZIP). If you 
   downloaded PostScript documentation, print manual.ps and referenc.ps on 
   a PostScript printer. The reference manual is around 320 pages, the user 
   manual is shorter. Alternatively, browse through the wx.hlp Windows Help 
   file, or the HTML or Adobe Acrobat (PDF) versions if you downloaded them.
   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/wsql/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.

It is not possible to successfully create a DLL out of wxWindows just
yet, but symbols have been added to the code to allow experimentation.
Please see docs/dll.txt for details.

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 users
xxxxxxxxxxxxxxxxxxxxxxxxx

wxWindows 1.68 supports Gnu-Win32 with less patching of the compiler than
with previous versions of both of these packages. wxWindows contains
extra include files in include/msw/gnuwin32.

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 Gnu-Win32 as per the Cygnus instructions.
- Get the file ftp://ftp.aiai.ed.ac.uk/pub/packages/ports/gnuwin32/rcl.zip
  (40 KB). This contains two files: cvtres.exe and rcl.exe, for compiling
  and binding resources to the Windows executable.
  Copy these two files to your gnuwin32/b18/H-i386-cygwin32/bin directory.
- Modify the file wx/install/cygnus.bat to set up appropriate
  variables, if necessary mounting drives. Run it before compiling. The variables
  are: GCC_EXEC_PREFIX, RCINCLUDE and CPLUS_INCLUDE_PATH. The latter must have paths for
  resources too since it's used as the resource file preprocessor. You don't need
  to edit makeg95.env as well as this batch file.
- Make sure you have a /tmp directory on the same drive as wxWindows, or BYACC will
  produce nonsense and y_tab.c won't compile properly, producing spurious errors.
  If you already use a DOS FLEX, adjust your path so the Gnu-Win32
  one is picked up instead.
- Use the makefile.g95 files for compiling wxWindows and samples.
- Use the 'strip' command to reduce executable size.

Gotchas:

- libwx.a is 27 MB.
- Print preview doesn't seem to work.
- The resource example doesn't load resources, although PrologIO
  seems to be working in Dialog Editor.
- wxPoem doesn't display properly.
- install.exe doesn't have built-in decompression because lzexpand.lib
  isn't available with Gnu-Win32 (it may have it in B18). However, you
  can use it with external decompression utilities.

References:

 - The GNU-WIN32 site is at
     http://www.cygnus.com/misc/gnu-win32/
 - See also http://web.ukonline.co.uk/julian.smart/wxwin/gnuwin32.htm


------------------------------
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    allows use of 3D style controls (CTL3D).
FAFA     allows use of bitmap buttons, messages and radiobuttons
         (FAFA_LIB).
wxString Use improved wxString and regular expression class (USE_GNU_WXSTRING).
ItsyBitsy supports tiny titlebars (USE_ITSY_BITSY).
Gauge    necessary for implementation of wxGauge class (USE_GAUGE).
wxXPM    necessary for implementation of XPM pixmap functionality
         (USE_XPM_IN_X, USE_XPM_IN_MSW).
DIB      necessary for implementation of BMP loading/saving
         functionality (USE_IMAGE_LOADING_IN_MSW).
PrologIO necessary for .WXR wxWindows resource-loading
         functionality (USE_MSW_RESOURCES).
RCPARSER 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.


-----------------------------------------
Known compilers compatible with wxWindows
-----------------------------------------

(please let me know of any others!)

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 (http://web.ukonline.co.uk/julian.smart/wxwin). 
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. There are also mirrors
listed at the web site in Europe and the United States.

For other useful utilities and packages, see the wxWindows Web
site at http://web.ukonline.co.uk/julian.smart/wxwin.

