fltk/README.win32

README.win32 - 10/03/2002 - Building FLTK under Windows
-------------------------------------------------------

INTRODUCTION

    This document is split into two main sections.  The first
    describes several possible build environments, while the
    second describes some of the issues associated with using
    the GNU-like build configurations in the "makefiles"
    subdirectory.

    FLTK currently supports the following development
    environments on the Windows platform:

	- Microsoft Visual C++ 6.0 using the supplied workspace
	  and project files.  Be sure to get your service packs!

	- Borland C++ Builder 5 using the supplied IDE file.

	- GNU toolsets (Cygwin or MinGW) hosted on Windows
	  9x/2000/NT/XP.

    This document gives a brief overview of compiling and using
    FLTK with the Cygwin and MinGW compiler toolkits.  Both
    toolkits provide a build environment based around the GNU
    C/C++ compiler.

    The Cygwin build environment supplies a library (the Cygwin
    DLL) that is primarily intended to provide a number of
    Unix-like POSIX facilities for programs being ported to the
    Windows environment (Win32 or WinNT).  Cygwin also supplies
    a very Unix-like build environment for Windows, including
    the "BASH" Bourne-compatible shell and all of the standard
    Unix file utilities (ls, cat, grep, etc.).

    Cygwin is developed by Cygnus (now part of RedHat, Inc). 
    Although provided for free download under the GPL,
    distributing programs that require the Cygwin DLL under a
    license other than the GPL requires a commercial license for
    the Cygwin DLL.  Native Windows programs that do not require
    the Cygwin DLL (compiled and linked with the "-mno-cygwin"
    option) may be released under any license freely.

    The MinGW distribution (Minimalist GNU for Windows) provides
    a similar toolset but geared solely towards native Windows
    development without the Unix-like POSIX library.  The lack
    of any libraries under the GPL or any other restrictive
    license means that programs built with the MinGW environment
    may always be released under any license freely.

    If you are not familiar with these GNU-like toolkits please
    refer to the links section later in this section.  In
    particular, check out their license conditions carefully
    before use.


THE TOOLS

    There are currently three main configurations supported by
    FLTK:

	1. Cygwin: Built using the Cygwin toolset and using the
	   Unix-like POSIX compatibility layer provided by the
	   Cygwin DLL.

	2. Cygwin using the "-mno-cygwin" option: Built using
	   the Cygwin toolset but not using the Cygwin DLL.

	3. MinGW: Mainly based upon the MinGW utilities,
	   compiler and tools but currently needs additional
	   tools from the Cygwin distribution (make.exe and
	   sh.exe).


RECOMMENDED BUILD ENVIRONMENTS

    Our recommendation is to:

	1. Get the current Cygwin toolset (June 20, 2000 or
	   later).

	   Can produce executables that do or do not rely on the
	   Cygwin DLL (check licensing)-- your choice.  No
	   supplementary MinGW files are required.

	2. Get the latest full MinGW toolset and add Cygwin
	   "make.exe" and "sh.exe" to it.

	   Will only normal Windows native executables without
	   any Unix or POSIX compatibility.

	3. Get a pre-built combined toolset that has been tested
	   with FLTK.

	   Carl Thompson has provided a set based upon the B20.1
	   Cygwin release and ~Feb 2000 version of Mingw which
	   has been successfully used for FLTK.

	   This will provide several Cygwin utilities and the
	   MinGW compiler. Compilation will produce executables
	   not reliant on the Cygwin DLL and so are freely
	   redistributable under any license you choose.

	   See the links section below for more information.

    All three options can provide windows-native executables and
    1 can provide a Unix-like POSIX portability layer that is
    reliant on a GPLed library.

    See the later sections for detailed information about using
    one of these configurations.

LINKS

    The following links may be of use:

	1. Main Cygwin homepage:

	       http://sourceware.cygnus.com/cygwin/

	2. Main Mingw homepage:

	       http://www.mingw.org/

	   In particular look for the MinGW FAQ at this link for
	   a lot of useful Mingw-native development
	   documentation.

	3. Mumit Khan's homepage (chief maintainer and driving
	   force behing MinGW):

	       http://www.xraylith.wisc.edu/~khan/software/gnu-win32/index.html

	   This page provides descriptions of Cygwin, Mingw and
	   several other similar packages. This information can
	   sometimes lag the current release however.

	   In particular the insights and recommendations for
	   using Cygwin for MinGW compilation are very useful:

	       http://www.xraylith.wisc.edu/~khan/software/gnu-win32/mno-cygwin-howto.txt

	   (Some of this information may be outdated and inaccurate!)

	4. Check out the FLTK newsgroups at the FLTK homepage:

	       http://www.fltk.org/

	   Its archival search facilities are EXTREMELY useful
	   to check back through previous problems with this
	   sort of configuration before posting new questions.

	5. Carl Thompson (member of the core team responsible
	   for FLTK):

	       http://www.carlthompson.net/

	   Currently a pre-bundled development toolset may be
	   found at:

	       http://www.carlthompson.net/cygwin/

	6. GNU Compiler Collection (GCC) compiler homepage:

	       http://gcc.gnu.org/

	7. OpenGL page - for OpenGL and GLUT libs

	       http://www.opengl.org/
  

BUILDING FLTK WITH CYGWIN OR MINGW

    Please read chapter 1 of the FLTK Programmers Manual for
    compilation instructions.


WHY DOES A CONSOLE WINDOW APPEAR WHEN I RUN MY PROGRAM

    Windows has a flag that determines whether an application
    runs in the foreground with a console or in the background
    without a console.  Use the "-mwindows" option to make your
    application run in the background and "-mconsole" to run in
    the foreground.

    Keep in mind that a windows application cannot send output
    to stdout, even if you run it from an existing console
    application.


HOW DO I GET OPENGL TO WORK?

    The CygWin build automatically supports OpenGL.

    The MingW build disables OpenGL by default, since the
    standard MingW distribution lacks the OpenGL header files.

    The configuration file config.h has a number of settings
    which control compile-time compilation.  One such setting is
    "HAVE_GL" . By default this is set to 0 to disable Open GL
    operation.  Changing the line in config.h to

        #define HAVE_GL 1

    will change this to compile and link in OpenGL.

    In order for it to work you will need a few OpenGL headers
    for both Cygwin and MinGW.  These are not part of the
    official distributions of Cygwin or MinGW, so they need to
    be added.  The following page provides a ZIP file containing
    the OpenGL headers:

	http://www.carlthompson.net/fltk/

    These should be put in a "GL" subdirectory somewhere in your
    compiler's search path.

    You will also need an OpenGL library and an additional set
    of GLUT libraries.

    The OpenGL files are most likely already part of your
    operating system, and the GLUT libraries are in current
    versions of MinGW and Cygwin or may be found at:

        http://www.opengl.org/

    Do a search for 'GLUT windows' and the first couple of
    results will take you to the latest GLUT and OpenGL libs for
    Windows.

    The binaries (DLLs normally) need to be put somewhere on the
    system PATH. Consult the install documentation on the site
    for info.

    Many programs use OpenGL and GLUT so you may already have
    them on your system.