Header option macro fixes and documentation work.

This adds compile-time checks and documentation warning about defining
header option macros during compilation of GLFW.

Fixes #445.

README.md

@@ -62,6 +62,7 @@ GLFW bundles a number of dependencies in the `deps/` directory.
 
 ## Changelog
 
+ - Made library compilation fail if any header option macros are defined
  - Removed support for LCC and Borland C++
  - Bugfix: `glfwSetTime` silently accepted invalid values
  - [WGL] Bugfix: The context flags debug bit was not set for OpenGL ES
@@ -125,6 +126,7 @@ skills.
  - Michael Dickens
  - Jonathan Dummer
  - Ralph Eastwood
+ - Siavash Eliasi
  - Michael Fogleman
  - Gerald Franz
  - GeO4d

docs/build.dox

@@ -62,6 +62,7 @@ its behavior.
 that the GLFW functions are defined in a DLL.
 
 The following macros control which OpenGL or OpenGL ES API header is included.
+Only one of these may be defined at a time.
 
 `GLFW_INCLUDE_GLCOREARB` makes the GLFW header include the modern
 `GL/glcorearb.h` header (`OpenGL/gl3.h` on OS X) instead of the regular OpenGL
@@ -85,11 +86,15 @@ header.  This is useful in combination with an extension loading library.
 If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h`
 header (`OpenGL/gl.h` on OS X) is included.
 
-`GLFW_INCLUDE_GLEXT` makes the GLFW header include the appropriate extension
-header for the OpenGL or OpenGL ES header selected above after and _in addition
-to_ that header.
+The following macros control the inclusion of additional API headers.  Any
+number of these may be defined simultaneously, and/or together with one of the
+above macros.
 
-`GLFW_INCLUDE_GLU` makes the header include the GLU header _in addition to_ the
+`GLFW_INCLUDE_GLEXT` makes the GLFW header include the appropriate extension
+header for the OpenGL or OpenGL ES header selected above after and in addition
+to that header.
+
+`GLFW_INCLUDE_GLU` makes the header include the GLU header in addition to the
 header selected above.  This should only be used with the standard OpenGL header
 and only for legacy code.  GLU has been deprecated and should not be used in new
 code.
@@ -97,6 +102,10 @@ code.
 @note GLFW does not provide any of the API headers mentioned above.  They must
 be provided by your development environment or your OpenGL or OpenGL ES SDK.
 
+@note None of these macros may be defined during the compilation of GLFW itself.
+If your build includes GLFW and you define any these in your build files, make
+sure they are not applied to the GLFW sources.
+
 
 @section build_link Link with the right libraries
 

docs/compile.dox

@@ -317,4 +317,8 @@ available:
  - `_GLFW_USE_RETINA` to have windows use the full resolution of Retina displays
    (recommended)
 
+@note None of the @ref build_macros may be defined during the compilation of
+GLFW.  If you define any of these in your build files, make sure they are not
+applied to the GLFW sources.
+
 */

include/GLFW/glfw3.h

@@ -165,7 +165,7 @@ extern "C" {
   * version of the GLFW library.  _GLFW_BUILD_DLL is defined by the GLFW
   * configuration header when compiling the DLL version of the library.
   */
- #error "You must not have both GLFW_DLL and _GLFW_BUILD_DLL defined"
+ #error "You may not have both GLFW_DLL and _GLFW_BUILD_DLL defined"
 #endif
 
 /* GLFWAPI is used to declare public API functions for export

src/internal.h

@@ -35,6 +35,17 @@
 
 #define _GLFW_VERSION_NUMBER "3.1.1"
 
+#if defined(GLFW_INCLUDE_GLCOREARB) || \
+    defined(GLFW_INCLUDE_ES1)       || \
+    defined(GLFW_INCLUDE_ES2)       || \
+    defined(GLFW_INCLUDE_ES3)       || \
+    defined(GLFW_INCLUDE_NONE)      || \
+    defined(GLFW_INCLUDE_GLEXT)     || \
+    defined(GLFW_INCLUDE_GLU)       || \
+    defined(GLFW_DLL)
+ #error "You may not define any header option macros when compiling GLFW"
+#endif
+
 #if defined(_GLFW_USE_OPENGL)
  // This is the default for glfw3.h
 #elif defined(_GLFW_USE_GLESV1)