Replace "WIN32" with "_WIN32" or "Windows".

Replace compiler/preprocessor/platform macro "WIN32" with "_WIN32".
Replace "WIN32" in text and documentation with "Windows".
Replace "MSWindows" with "Windows".

To do: README.Windows.txt (and maybe other documentation as well)
needs updates.


git-svn-id: file:///fltk/svn/fltk/branches/branch-1.4@12655 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 648 insertions, 0 deletions

diff --git a/README.Windows.txt b/README.Windows.txt
new file mode 100644
index 000000000..04faa338f
--- /dev/null
+++ b/README.Windows.txt
@@ -0,0 +1,648 @@
+ README.MSWindows.txt - Building FLTK under Microsoft Windows
+--------------------------------------------------------------
+
+
+
+ CONTENTS
+==========
+
+  1   INTRODUCTION
+  2   HOW TO BUILD FLTK USING MinGW/Cygwin
+    2.1   The Tools
+    2.2   Recommended Command Line Build Environment
+    2.3   Prerequisites
+    2.4   Downloading and Unpacking
+    2.5   Configuring FLTK
+    2.6   Building FLTK
+    2.7   Testing FLTK
+    2.8   Installing FLTK
+    2.9   Creating new Projects
+  3   HOW TO BUILD FLTK USING VISUAL STUDIO 2008
+    3.1   Prerequisites
+    3.2   Downloading and Unpacking
+    3.3   Configuring FLTK
+    3.4   Building FLTK
+    3.5   Testing FLTK
+    3.6   Installing FLTK
+    3.7   Creating new Projects
+  4   HOW TO BUILD FLTK USING VISUAL STUDIO 2010 OR LATER
+    4.1   Prerequisites
+    4.2   Downloading and Unpacking
+    4.3   Configuring FLTK
+    4.4   Building FLTK
+    4.5   Testing FLTK
+    4.6   Installing FLTK
+    4.7   Creating new Projects
+  5   FREQUENTLY ASKED QUESTIONS
+  7   LINKS
+  6   DOCUMENT HISTORY
+
+
+ INTRODUCTION
+==============
+
+FLTK 1.3 and later is officially supported on Windows (2000,) 2003,
+XP, and later.  Older Windows versions are not officially supported,
+but may still work.  The main reason is that the OS version needs
+to support UTF-8. FLTK 1.3 is known to work on Windows Vista, Windows 7,
+Windows 8/8.1, and Windows 10.
+
+FLTK currently supports the following development
+environments on the Windows platform:
+
+    - Free Microsoft "Visual C++ 2008 Express" or later or "Visual Studio
+      Community 2013" or later. The Visual Studio project files must be
+      generated using CMake. Visual Studio 2017 includes CMake support:
+
+      "Visual Studio 2017 introduces built-in support for handling CMake
+      projects. This makes it a lot simpler to develop C++ projects built
+      with CMake without the need to generate VS projects and solutions
+      from the command line. This post gives you an overview of the CMake
+      support, how to easily get started and stay productive in Visual Studio."
+
+      Citation from:
+      https://blogs.msdn.microsoft.com/vcblog/2016/10/05/cmake-support-in-visual-studio/
+
+      As of this writing (07/2017) the FLTK team did not yet test and
+      verify the functionality of Microsoft's included CMake features.
+
+    - GNU toolsets (Cygwin or MinGW) hosted on Windows.
+
+CAUTION: Libraries built by any one of these environments can not be mixed
+with object files from any other environment!
+
+
+ HOW TO BUILD FLTK USING MinGW and Cygwin
+==========================================
+
+This chapter of 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. Further information is
+available from the FLTK website at http://www.fltk.org, such
+as this Howto note: http://www.fltk.org/articles.php?L598
+
+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
+(cross-compiled and linked with the MinGW gcc/g++ cross compilers
+supplied with Cygwin) may be released under any license freely.
+
+Currently you would have to install mingw64-i686-gcc-g++ for
+32-bit Windows applications (despite its name!), and/or
+mingw64-x86_64-gcc-g++ for 64-bit applications. You may also
+need to install the corresponding '-headers' packages as well.
+Currently these tools support gcc 4.5 or newer. The setup for
+FLTK is somewhat more complicated because you must configure
+this as a cross compiler, but it works well.
+
+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. MinGW also
+supplies a Unix-like build environment for Windows,
+including MSYS (a Bourne-compatible shell) and the standard
+Unix file utilities (ls, cat, grep, etc.)
+
+If you are not familiar with these GNU-like toolkits please
+refer to the links section later in this note. In particular,
+check out their license conditions carefully before use.
+
+
+ The Tools
+-----------
+
+There are currently three main configurations supported by
+FLTK with the GNU tools:
+
+    1. Cygwin: Built using the Cygwin toolset and using the Unix-like
+       POSIX compatibility layer provided by the Cygwin DLL.
+       License: GPL or non-free commercial license (ask Redhat).
+
+    2. Cygwin using the MinGW cross compiler suite: Built using
+       the Cygwin tools but not using the Cygwin DLL.
+       License: freely distributable on all Windows systems.
+
+    3. MinGW: Built using the MinGW utilities, compiler and tools. This
+       is, in many aspects, analogous to (2.). This is the recommended
+       one if you want to build native Windows programs only.
+       License: freely distributable on all Windows systems.
+
+
+ Recommended Command Line Build Environment
+--------------------------------------------
+
+Our recommendation is to:
+
+    1. Get the current Cygwin toolset.
+
+       This can either produce executables that do or do not
+       rely on the Cygwin DLL (check licensing) at your choice.
+
+    2. Get the latest MinGW toolset. It is recommended that you
+       also get the MSYS shell and the msysDTK developer toolset.
+
+       This will only produce normal Windows native executables
+       without any Unix or POSIX compatibility layer.
+
+    See the links section below for more information.
+
+Either option can generate Windows native executables and option 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.
+
+
+ Prerequisites
+---------------
+
+In order to build FLTK from the command line, you need to install the MinGW
+environment from www.mingw.org. The graphical installer "mingw-get-inst" can
+be downloaded here for free:
+
+  http://www.mingw.org/wiki/Getting_Started
+
+Launch the installer and follow the instructions. In the "Select Components"
+dialog, add "C++ Compiler", "MSYS Basic System", and "MinGW Developer Toolkit".
+Wait for the installer to finish.
+
+After downloading and installing, you need to launch the MinGW Shell through
+the Start menu.
+
+
+ Downloading and Unpacking
+---------------------------
+
+Download FLTK from here:
+
+  http://www.fltk.org/software.php
+
+into your home folder. The default location as seen from MSWindows is similar
+to
+
+  C:\MinGW\msys\1.0\home\matt\
+
+If you are familiar with "subversion" and like to stay current with your
+version, you will find the subversion access parameters at the bottom of
+that page. Unpack FLTK into a convenient location. I like to have everything
+in my dev directory:
+
+  cd
+  mkdir dev
+  cd dev
+  tar xvfz fltk-1.3.xxxx.tar.gz
+  cd fltk-1.3.xxxx
+
+
+ Configuring FLTK
+------------------
+
+If you got FLTK via subversion then you need one extra step. Otherwise skip
+over this part. Stay in your FLTK source-code directory and type the
+following:
+
+  NOCONFIGURE=1 ./autogen.sh
+
+Now configure your FLTK installation:
+
+  ./configure
+
+ADVANCED: type "./configure --help" to get a complete list of optional
+configuration parameters. These should be pretty self-explanatory. Some
+more details can be found in README.
+:END_ADVANCED
+
+The configuration script will check your machine for the required resources
+which should all have been part of your MinGW installation. Review the
+Configuration Summary, maybe take some notes.
+
+ADVANCED: some versions of MinGW/Msys are broken and complain about a missing
+--enable-auto-import. The solution is to upgrade to the current release. If
+that is not possible, you can include the --enable-auto-import flag when
+linking:
+  ./configure <config flags> LDFLAGS=-Wl,--enable-auto-import
+:END_ADVANCED
+
+
+Known Problems:
+
+  There is a known incompatibility with some Windows subversion tools that
+  may not set the correct line endings for autoconf. If you get strange
+  error messages when running ./configure or make, you may need to convert
+  configh.in to "Unix line endings" (LF-only). These error messages are
+  unspecific, e.g. compilation errors like:
+
+     error: 'U32' does not name a type
+     error: 'bmibuffer' was not declared in this scope
+
+  You can fix the line endings with the MinGW/msys tool 'unix2dos' (u2d)
+  or with your favorite editor, if it allows to change the line endings,
+  then run autoconf and ./configure again.
+  For further information see this bug report:
+     http://www.fltk.org/newsgroups.php?gfltk.bugs+v:10197
+
+
+ Building FLTK
+---------------
+
+Now this is easy. Stay in your FLTK source-code directory and type:
+
+  make
+
+The entire FLTK toolkit including many test programs will be built for you.
+No warnings should appear.
+
+
+ Testing FLTK
+--------------
+
+After a successful build, you can test FLTK's capabilities:
+
+  test/demo
+
+
+ Installing FLTK
+-----------------
+
+If you did not change any of the configuration settings, FLTK will be
+installed in "/usr/local/include" and "/usr/local/lib" by typing
+
+  make install
+
+It is possible to install FLTK in user space by changing the installation path
+to a location within the user account by adding the "--prefix=PREFIX" parameter
+to the "./configure" command.
+
+
+ Creating new Projects
+-----------------------
+
+FLTK provides a neat script named "fltk-config" that can provide all the flags
+needed to build FLTK applications using the same flags that were used to build
+the library itself. Running "fltk-config" without arguments will print a list
+of options. The easiest call to compile an FLTK application from a single
+source file is:
+
+  fltk-config --compile myProgram.cxx
+
+"fltk-config" and "fluid" will be installed in "/usr/local/bin/" by default.
+I recommend that you add it to the command search path.
+
+
+
+ HOW TO BUILD FLTK USING MICROSOFT VISUAL STUDIO
+================================================
+
+
+ Prerequisites
+---------------
+
+In order to build FLTK from within Visual Studio, you need to install the
+Visual C++ developer environment from the Microsoft web site. The "Express"
+or "Community" edition is free of charge and sufficient to develop FLTK
+applications:
+
+  https://www.visualstudio.com/vs/visual-studio-express/
+
+If you intend to use an older (maybe commercial) version you need at least
+a version that is supported by the version of CMake you are using to generate
+the project files. You should make sure that all available service packs are
+installed or building FLTK may fail.
+
+As of this writing (07/2017) the FLTK team recommends at least Visual
+Studio 2008 with current service packs. Visual Studio 2008, 2010, 2013,
+2015, and 2017 are known to work with FLTK 1.4.0 (svn, 07/2017).
+
+You also need to install CMake (cmake-gui) from:
+
+  https://cmake.org/download/
+
+Visual Studio 2017 has internal CMake support (so you may not need to
+install CMake separately), but this has not yet been tested thoroughly
+by the FLTK team.
+
+
+ Downloading and Unpacking FLTK
+--------------------------------
+
+Download FLTK from here:
+
+  http://www.fltk.org/software.php
+
+If you are familiar with "subversion" and like to stay current with your
+version, you will find the subversion access parameters at the bottom of
+that page.
+
+Unpack FLTK by using an appropriate unpacker and copy the new folder into a
+convenient location. I have set up a "dev" folder in my home folder for all
+my projects.
+
+
+ Configuring FLTK
+------------------
+
+Note: Configuration with Visual Studio 2017's internal CMake support is
+not yet included here. You may try yourself...
+
+Please refer to README.CMake.txt for how to configure FLTK with CMake.
+
+Once you have followed the instructions you should have created a new
+build directory with the Visual Studio Solution (project files) for FLTK.
+
+Launch Visual Studio and open the project file (FLTK.sln) or double-click
+on FLTK.sln in the Windows Explorer.
+
+Choose "Debug" or "Release" mode from the "Solution Configurations" menu.
+
+
+ Building FLTK
+---------------
+
+Use the context menu of the "demo" project to "Set as StartUp Project". Then
+select "Build Solution" from the "Build" menu or press F7 to build all
+libraries.
+
+
+ Testing FLTK
+--------------
+
+Select "Start Debugging" from the "Debug" menu or just press F5 to run the
+Demo program. Use "Demo" to explore all test programs.
+
+
+ Installing FLTK
+-----------------
+
+********************************************************************************
+   The information in this chapter is NO LONGER RECOMMENDED by the FLTK team.
+********************************************************************************
+
+The default location for VisualC 2008 libraries and headers is here:
+
+  C:\Program Files\Microsoft Visual Studio 9.0\VC\
+
+It is possible to move the FLTK libraries, headers, and Fluid into the
+respective subdirectories, so that they are available for future development
+without adding link and include paths to the solution.
+
+  copy the entire FL directory into the include path
+
+  add all files from ide\VisualC2008\FL to the FL directory copied above
+    (this is currently only one file: abi-version.h)
+
+  copy all .lib files from the fltk lib directory to the VC lib directory
+
+  copy fluid.exe in the fluid directory to the bin directory
+
+I highly discourage using dll's (dynamically linking libraries) on MSWindows
+because they will require an installation process and likely cause version
+conflicts. Use the static .lib libraries instead.
+
+
+ Creating new Projects
+-----------------------
+
+********************************************************************************
+   The information in this chapter is NO LONGER RECOMMENDED by the FLTK team.
+********************************************************************************
+
+This chapter assumes that libraries and headers were copied into
+
+  C:\Program Files\Microsoft Visual Studio 9.0\VC\
+
+Create a new project of type "General", "Empty Project" and add a simple "C++"
+file to it. The FLTK "hello" source code is a good base.
+
+Now open the Project Properties dialog and add "Comctl32.lib" and all the FLTK
+libraries that you want to use (at least "fltk.lib") to Additional Dependencies
+(Configuration Properties > Linker > Additional Dependencies).
+
+Compile and run your test program with F5.
+
+You can also include .fl resources: add a new Header file to your project, but
+let the name end in .fl. Right-click and select "Open with...". Add "fluid.exe"
+from the "bin" directory and set it as the default editor.
+
+To automatically compile .fl files, open the Properties editor and set the
+Custom Build Steps to:
+
+  Command Line: fluid.exe -c $(InputPath)
+  Description: Compiling Fluid .fl file
+  Outputs: $(InputDir)$(InputName).cxx; $(InputDir)$(InputName).h
+
+Now add the generated .cxx file to your project as well. Whenever the .fl file
+is changed, the corresponding .cxx file will be recompiled.
+
+
+
+ HOW TO BUILD FLTK USING VISUAL STUDIO 2010 OR LATER
+====================================================
+
+
+ Prerequisites
+---------------
+
+See previous chapter "HOW TO BUILD FLTK USING MICROSOFT VISUAL STUDIO".
+
+
+ Downloading and Unpacking
+---------------------------
+
+See previous chapter "HOW TO BUILD FLTK USING MICROSOFT VISUAL STUDIO".
+
+
+ Configuring FLTK
+------------------
+
+See previous chapter "HOW TO BUILD FLTK USING MICROSOFT VISUAL STUDIO".
+
+
+ Building FLTK
+---------------
+
+See previous chapter "HOW TO BUILD FLTK USING MICROSOFT VISUAL STUDIO".
+
+ Testing FLTK
+--------------
+
+See previous chapter "HOW TO BUILD FLTK USING MICROSOFT VISUAL STUDIO".
+
+
+ Installing FLTK
+-----------------
+
+********************************************************************************
+   The information in this chapter is NO LONGER RECOMMENDED by the FLTK team.
+********************************************************************************
+
+The default location for VisualC 2010 libraries and headers is here:
+
+  C:\Program Files\Microsoft Visual Studio 10.0\VC\
+
+It is possible to move the FLTK libraries, headers, and Fluid into the
+respective subdirectories, so that they are available for future development
+without adding link and include paths to the solution.
+
+  copy the entire FL directory into the include path
+
+  add all files from ide\VisualC2010\FL to the FL directory copied above
+    (this is currently only one file: abi-version.h)
+
+  copy all .lib files from the fltk lib directory to the VC lib directory
+
+  copy fluid.exe in the fluid directory to the bin directory
+
+I highly discourage using dll's (dynamically linking libraries) on MSWindows
+because they will require an installation process and likely cause version
+conflicts. Use the static .lib libraries instead.
+
+
+ Creating new Projects
+-----------------------
+
+********************************************************************************
+   The information in this chapter is NO LONGER RECOMMENDED by the FLTK team.
+********************************************************************************
+
+This chapter assumes that libraries and headers are copied into
+
+  C:\Program Files\Microsoft Visual Studio 10.0\VC\
+
+Create a new project of type "General", "Empty Project" and add a simple "C++"
+file to it. The FLTK "hello" source code is a good base.
+
+Now open the Project Properties dialog and add "Comctl32.lib" and all the FLTK
+libraries that you want to use (at least "fltk.lib") to Additional Dependencies
+(Configuration Properties > Linker > Additional Dependencies).
+
+Compile and run your test program with F5.
+
+You can also include .fl resources: add a new Header file to your project, but
+let the name end in .fl. Right-click and select "Open with...". Add "fluid.exe"
+from the "bin" directory and set it as the default editor.
+
+To automatically compile .fl files, open the Properties editor and change the
+Element Type to Custom Build and click Apply. Now set the
+Custom Build Steps to:
+
+  Command Line: fluid.exe -c %(FullPath)
+  Description: Compiling Fluid .fl file
+  Outputs: $(InputDir)$(InputName).cxx; $(InputDir)$(InputName).h
+
+Now add the generated .cxx file to your project as well. Whenever the .fl file
+is changed, the corresponding .cxx file will be recompiled.
+
+
+
+ FREQUENTLY ASKED QUESTIONS
+============================
+
+
+ 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.
+
+If you're using gcc (i.e. MinGW or Cygwin), then use the
+linker option "-mwindows" to make your application run in
+the background and "-mconsole" to run in the foreground. Use
+fltk-config --ldflags to see appropriate linker flags, or use
+fltk-config --compile to compile a single source file.
+
+If you're using MS VC++, then you must set the linker option
+"/subsystem:windows" to create a "Windows" program (w/o console
+window), or set the linker option "/subsystem:console" for a
+console program, i.e. with a console window. These options
+are set differently in the FLTK project files, depending on
+whether you select a "Debug" or "Release" build.
+
+Other compilers and build systems may have different options.
+
+Keep in mind that a windows application cannot send output
+to stdout, even if you run it from an existing console
+application.
+(Note: A special case of this exists if running a MinGW
+application from the command line of an MSYS shell, when an
+application is able to write to stdout, even if compiled with
+"-mwindows".  The same applies to Cygwin.)
+
+
+ How do I get OpenGL to work?
+------------------------------
+
+Both builds should automatically support OpenGL.
+
+The configuration file config.h has a number of settings
+which control compile-time compilation.  One such setting is
+"HAVE_GL". This may be 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.
+
+
+
+ LINKS
+=======
+
+The following links may be of use:
+
+1. Main Cygwin homepage:
+
+	http://www.cygwin.com/
+
+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. 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.
+
+4. GNU Compiler Collection (GCC) compiler homepage:
+
+	http://gcc.gnu.org/
+
+5. OpenGL page - for OpenGL and GLUT libs
+
+	http://www.opengl.org/
+
+6. CMake homepage:
+
+	https://cmake.org/
+
+
+
+ DOCUMENT HISTORY
+==================
+
+Oct 25 2010 - matt: restructured entire document and verified instructions
+Dec 20 2010 - matt: merged with README.win32
+Dec 22 2010 - Albrecht: added newer Cygwin (cross/mingw-w64) options
+Feb 24 2012 - Albrecht: clarified console window FAQ
+Jul 05 2017 - Albrecht: several updates, particularly on Visual Studio usage