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.