Initial Commit

1 files changed, 347 insertions, 0 deletions

diff --git a/glfw-3.2.1/docs/build.dox b/glfw-3.2.1/docs/build.dox
new file mode 100644
index 0000000..ff9ed86
--- /dev/null
+++ b/glfw-3.2.1/docs/build.dox
@@ -0,0 +1,347 @@
+/*!
+
+@page build_guide Building applications
+
+@tableofcontents
+
+This is about compiling and linking applications that use GLFW.  For information on
+how to write such applications, start with the
+[introductory tutorial](@ref quick_guide).  For information on how to compile
+the GLFW library itself, see @ref compile_guide.
+
+This is not a tutorial on compilation or linking.  It assumes basic
+understanding of how to compile and link a C program as well as how to use the
+specific compiler of your chosen development environment.  The compilation
+and linking process should be explained in your C programming material and in
+the documentation for your development environment.
+
+@section build_include Including the GLFW header file
+
+In the source files of your application where you use OpenGL or GLFW, you should
+include the GLFW header file, i.e.:
+
+@code
+#include <GLFW/glfw3.h>
+@endcode
+
+The GLFW header declares the GLFW API and by default also includes the OpenGL
+header of your development environment, which in turn defines all the constants,
+types and function prototypes of the OpenGL API.
+
+The GLFW header also defines everything necessary for your OpenGL header to
+function.  For example, under Windows you are normally required to include
+`windows.h` before the OpenGL header, which would pollute your code namespace
+with the entire Win32 API.
+
+Instead, the GLFW header takes care of this for you, not by including
+`windows.h`, but by duplicating only the very few necessary parts of it.  It
+does this only when needed, so if `windows.h` _is_ included, the GLFW header
+does not try to redefine those symbols.  The reverse is not true, i.e.
+`windows.h` cannot cope if any of its symbols have already been defined.
+
+In other words:
+
+ - Do _not_ include the OpenGL headers yourself, as GLFW does this for you
+ - Do _not_ include `windows.h` or other platform-specific headers unless you
+   plan on using those APIs directly
+ - If you _do_ need to include such headers, do it _before_ including
+   the GLFW header and it will handle this
+
+If you are using an OpenGL extension loading library such as
+[glad](https://github.com/Dav1dde/glad), the extension loader header should
+either be included _before_ the GLFW one, or the `GLFW_INCLUDE_NONE` macro
+(described below) should be defined.
+
+
+@subsection build_macros GLFW header option macros
+
+These macros may be defined before the inclusion of the GLFW header and affect
+its behavior.
+
+`GLFW_DLL` is required on Windows when using the GLFW DLL, to tell the compiler
+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
+header.
+
+`GLFW_INCLUDE_ES1` makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h`
+header instead of the regular OpenGL header.
+
+`GLFW_INCLUDE_ES2` makes the GLFW header include the OpenGL ES 2.0 `GLES2/gl2.h`
+header instead of the regular OpenGL header.
+
+`GLFW_INCLUDE_ES3` makes the GLFW header include the OpenGL ES 3.0 `GLES3/gl3.h`
+header instead of the regular OpenGL header.
+
+`GLFW_INCLUDE_ES31` makes the GLFW header include the OpenGL ES 3.1 `GLES3/gl31.h`
+header instead of the regular OpenGL header.
+
+`GLFW_INCLUDE_VULKAN` makes the GLFW header include the Vulkan `vulkan/vulkan.h`
+header instead of the regular OpenGL header.
+
+`GLFW_INCLUDE_NONE` makes the GLFW header not include any OpenGL or OpenGL ES API
+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.
+
+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_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 compatibility with legacy code.  GLU has been deprecated and should
+not be used in new code.
+
+@note GLFW does not provide any of the API headers mentioned above.  They must
+be provided by your development environment or your OpenGL, OpenGL ES or Vulkan
+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
+
+GLFW is essentially a wrapper of various platform-specific APIs and therefore
+needs to link against many different system libraries.  If you are using GLFW as
+a shared library / dynamic library / DLL then it takes care of these links.
+However, if you are using GLFW as a static library then your executable will
+need to link against these libraries.
+
+On Windows and OS X, the list of system libraries is static and can be
+hard-coded into your build environment.  See the section for your development
+environment below.  On Linux and other Unix-like operating systems, the list
+varies but can be retrieved in various ways as described below.
+
+A good general introduction to linking is
+[Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by
+David Drysdale.
+
+
+@subsection build_link_win32 With MinGW or Visual C++ on Windows
+
+The static version of the GLFW library is named `glfw3`.  When using this
+version, it is also necessary to link with some libraries that GLFW uses.
+
+When linking an application under Windows that uses the static version of GLFW,
+you must link with `opengl32`.  On some versions of MinGW, you must also
+explicitly link with `gdi32`, while other versions of MinGW include it in the
+set of default libraries along with other dependencies like `user32` and
+`kernel32`.  If you are using GLU, you must also link with `glu32`.
+
+The link library for the GLFW DLL is named `glfw3dll`.  When compiling an
+application that uses the DLL version of GLFW, you need to define the `GLFW_DLL`
+macro _before_ any inclusion of the GLFW header.  This can be done either with
+a compiler switch or by defining it in your source code.
+
+An application using the GLFW DLL does not need to link against any of its
+dependencies, but you still have to link against `opengl32` if your application
+uses OpenGL and `glu32` if it uses GLU.
+
+
+@subsection build_link_cmake_source With CMake and GLFW source
+
+This section is about using CMake to compile and link GLFW along with your
+application.  If you want to use an installed binary instead, see @ref
+build_link_cmake_package.
+
+With just a few changes to your `CMakeLists.txt` you can have the GLFW source
+tree built along with your application.
+
+When including GLFW as part of your build, you probably don't want to build the
+GLFW tests, examples and documentation.  To disable these, set the corresponding
+cache variables before adding the GLFW source tree.
+
+@code
+set(GLFW_BUILD_DOCS OFF CACHE BOOL "" FORCE)
+set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+@endcode
+
+Then add the root directory of the GLFW source tree to your project.  This
+will add the `glfw` target and the necessary cache variables to your project.
+
+@code{.cmake}
+add_subdirectory(path/to/glfw)
+@endcode
+
+Once GLFW has been added to the project, link against it with the `glfw` target.
+This adds all link-time dependencies of GLFW as it is currently configured,
+the include directory for the GLFW header and, when applicable, the
+[GLFW_DLL](@ref build_macros) macro.
+
+@code{.cmake}
+target_link_libraries(myapp glfw)
+@endcode
+
+Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
+OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
+If your application calls OpenGL directly, instead of using a modern
+[extension loader library](@ref context_glext_auto) you can find it by requiring
+the OpenGL package.
+
+@code{.cmake}
+find_package(OpenGL REQUIRED)
+@endcode
+
+If OpenGL is found, the `OPENGL_FOUND` variable is true and the
+`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
+
+@code{.cmake}
+target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
+target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
+@endcode
+
+The OpenGL CMake package also looks for GLU.  If GLU is found, the
+`OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
+`OPENGL_glu_LIBRARY` cache variables can be used.
+
+@code{.cmake}
+target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
+@endcode
+
+@note GLU has been deprecated and should not be used in new code, but some
+legacy code requires it.
+
+
+@subsection build_link_cmake_package With CMake and installed GLFW binaries
+
+This section is about using CMake to link GLFW after it has been built and
+installed.  If you want to build it along with your application instead, see
+@ref build_link_cmake_source.
+
+With just a few changes to your `CMakeLists.txt`, you can locate the package and
+target files generated when GLFW is installed.
+
+@code{.cmake}
+find_package(glfw3 3.2 REQUIRED)
+@endcode
+
+Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
+OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
+If your application calls OpenGL directly, instead of using a modern
+[extension loader library](@ref context_glext_auto) you can find it by requiring
+the OpenGL package.
+
+@code{.cmake}
+find_package(OpenGL REQUIRED)
+@endcode
+
+If OpenGL is found, the `OPENGL_FOUND` variable is true and the
+`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
+
+@code{.cmake}
+target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
+target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
+@endcode
+
+The OpenGL CMake package also looks for GLU.  If GLU is found, the
+`OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
+`OPENGL_glu_LIBRARY` cache variables can be used.
+
+@code{.cmake}
+target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
+@endcode
+
+@note GLU has been deprecated and should not be used in new code, but some
+legacy code requires it.
+
+
+@subsection build_link_pkgconfig With makefiles and pkg-config on Unix
+
+GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/),
+and the `glfw3.pc` pkg-config file is generated when the GLFW library is built
+and is installed along with it.  A pkg-config file describes all necessary
+compile-time and link-time flags and dependencies needed to use a library.  When
+they are updated or if they differ between systems, you will get the correct
+ones automatically.
+
+A typical compile and link command-line when using the static version of the
+GLFW library may look like this:
+
+@code{.sh}
+cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
+@endcode
+
+If you are using the shared version of the GLFW library, simply omit the
+`--static` flag.
+
+@code{.sh}
+cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
+@endcode
+
+You can also use the `glfw3.pc` file without installing it first, by using the
+`PKG_CONFIG_PATH` environment variable.
+
+@code{.sh}
+env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
+@endcode
+
+The dependencies do not include OpenGL or GLU, as GLFW loads any OpenGL, OpenGL
+ES or Vulkan libraries it needs at runtime and does not use GLU.  On OS X, GLU
+is built into the OpenGL framework, so if you need GLU you don't need to do
+anything extra.  If you need GLU and are using Linux or BSD, you should add the
+`glu` pkg-config package.
+
+@code{.sh}
+cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`
+@endcode
+
+@note GLU has been deprecated and should not be used in new code, but some
+legacy code requires it.
+
+If you are using the static version of the GLFW library, make sure you don't
+link statically against GLU.
+
+@code{.sh}
+cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --static --libs glfw3` `pkg-config --libs glu`
+@endcode
+
+
+@subsection build_link_xcode With Xcode on OS X
+
+If you are using the dynamic library version of GLFW, simply add it to the
+project dependencies.
+
+If you are using the static library version of GLFW, add it and the Cocoa,
+OpenGL, IOKit and CoreVideo frameworks to the project as dependencies.  They can
+all be found in `/System/Library/Frameworks`.
+
+
+@subsection build_link_osx With command-line on OS X
+
+It is recommended that you use [pkg-config](@ref build_link_pkgconfig) when
+building from the command line on OS X.  That way you will get any new
+dependencies added automatically.  If you still wish to build manually, you need
+to add the required frameworks and libraries to your command-line yourself using
+the `-l` and `-framework` switches.
+
+If you are using the dynamic GLFW library, which is named `libglfw.3.dylib`, do:
+
+@code{.sh}
+cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo
+@endcode
+
+If you are using the static library, named `libglfw3.a`, substitute `-lglfw3`
+for `-lglfw`.
+
+Note that you do not add the `.framework` extension to a framework when linking
+against it from the command-line.
+
+The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing
+special to do when using GLU.  Also note that even though your machine may have
+`libGL`-style OpenGL libraries, they are for use with the X Window System and
+will _not_ work with the OS X native version of GLFW.
+
+*/