regenerated after adding DEBUG_ options

[wxWidgets.git] / docs / mgl / install.txt

wxWindows 2.5 for MGL installation
------------------------------------

IMPORTANT NOTE:

  If you experience problems installing, please re-read these
  instructions and other related files (todo.txt, bugs.txt and
  osname.txt for your platform if it exists) carefully before
  mailing wxwin-users or the author. Preferably, try to fix the
  problem first and then send a patch to the author.
  
  When sending bug reports tell us what version of wxWindows you are 
  using (including the beta) and what compiler on what system. One 
  example: wxMGL 2.5.0, gcc 2.95.3, Redhat 7.0

First steps
-----------

- Download SciTech MGL library (version 5.0) from http://www.scitechsoft.com.
  The downloads page is here (you need MGL version 5.0beta7 or newer):
  http://www.scitechsoft.com/products/embedded/mgl_home.html
  
  Install MGL according to provided instructions. In particular, make sure that
  MGL_ROOT and NUCLEUS_PATH environment variables are set before attempting to
  build wxMGL.

  Make sure you installed all MGL components, including the "fonts" package
  (it's called mgl50b7-font.tar.gz in Linux version). It is important to have
  SciTech's basic fonts in $(MGL_ROOT)/fonts directory (you may want to add
  Arial TrueType font for better output quality) and basic cursors in 
  $(MGL_ROOT)/cursors. wxMGL depends on their presence.

- Download wxMGL-x.y.z.tgz, where x.y.z is the version number.
  Download documentation in a preferred format, such as
  wxWindows-HTML.zip or wxWindows-PDF.zip.

- Make a directory such as ~/wx and unarchive the files into this
  directory.

- It is recommended that you install bison and flex; using yacc
  and lex may require tweaking of the makefiles.

- You can now use configure or makefiles to build wxWindows and the samples.
  In case of problems, please use GNU make.


COMPILING
=========

Following systems are supported by wxMGL so far:
 - Unix (Linux etc.)
 - MS-DOS (DJGPP and Watcom compilers)


* Compiling using configure
----------------------------

These instructions apply to installation on a Unix system (such as Linux). Please
see bellow for information on using configure on non-Unix platforms.

If you compile wxWindows on Linux for the first time and don't like to read 
install instructions just do (in the base dir):

> ./configure --with-mgl
> make
> su <type root password>
> make install
> ldconfig
> exit

Afterwards you can continue with

> make
> su <type root password>
> make install
> ldconfig
> exit

If you want to remove wxWindows on Unix you can do this:

> su <type root password>
> make uninstall
> ldconfig
> exit

You can set many options to configure. Type

> ./configure --help

and you will get a list of supported options.


* Using wxMGL library built with configure
-------------------------------------------

'make install' will install wx-config script that can (and should) be used
to get compiler flags that are needed to build your program. wx-config --cxxflags
will output necessary C++ compiler flags and wx-config --libs will list all
needed libraries. See an example of wxWindows application makefile:

minimal: minimal.o
	$(CC) -o minimal minimal.o `wx-config --libs`

minimal.o: minimal.cpp mondrian.xpm
	$(CC) `wx-config --cxxflags` -c minimal.cpp -o minimal.o


* Using configure to build MS-DOS version
------------------------------------------

Even though configure is a Unix script, you can use it to build MS-DOS version
of the wxMGL library. There are two possible ways to achieve this: you can
either cross-compile from Unix or compile natively. Either way you will needed
the DJGPP port of GCC compiler freely available from http://www.djgpp.org. You will
also need DJGPP version of SciTech MGL (this must be built using native tools).

Cross-compilation is very easy. It works like ordinary compilation with configure,
you only have to specify the target:

> ./configure --with-mgl --build=i586-linux --host=i586-pc-msdosdjgpp
> make

If you want to build wxMGL natively using DJGPP compiler, you will have to install
a couple of Unix utilities. The easiest way to get them is to install the Cygwin
package (available from RedHat, see http://freshmeat.net/search/?q=cygwin for exact
URL). Cygwin contains win32 compiler, so make sure you did *not* install it! Once
you have Cygwin utilities and DJGPP compiler in your PATH, run bash.exe and type

> ./configure --with-mgl
> make

in wxWindows top directory. You can build wxMGL in MS-DOS with configure, sorry.


* Building wxMGL for MS-DOS using Watcom C/C++
-----------------------------------------------

You will need Watcom C/C++ compiler version 11 or newer (Watcom is going to be 
OpenSourced by SciTech, check out http://www.openwatcom.org).

1. Edit $(WXDIR)\include\wx\univ\setup.h to suit your needs (in same way as you
   do when compiling wxMSW).

2. Go to $(WXDIR)\src\mgl and run
   > wmake -f makefile.wat all

3. You can compile the samples by typing 'wmake -f makefile.mgl all' in sample
   directory if this file is available. If it is not, copy makefile.wat to 
   makefile.mgl and replace the line that says

       !include $(WXDIR)\src\makeprog.wat

   with

       !include $(WXDIR)\src\mgl\makeprog.wat


Bug reports
-----------

Please send bug reports with a description of your environment,
compiler and the error message(s) to the wxwin-developers mailing list at:

    wx-dev@lists.wxwindows.org

Vaclav Slavik, Julian Smart, Robert Roebling and Vadim Zeitlin, February 2002.