Moved GLFW compilation guide to docs.

README.md

@@ -16,204 +16,17 @@ If you are new to GLFW, you may find the
 the GLFW 3 API.
 
 
-## Building GLFW
+## Compiling GLFW
 
-These are the build instructions for the GLFW library itself.  For information
-on how to build programs that use GLFW, see the [Building programs using
-GLFW](http://www.glfw.org/docs/latest/build.html) guide.
-
-
-### Dependencies
-
-To compile GLFW and the accompanying example programs, you will need **CMake**,
-which will generate the project files or makefiles for your particular
-development environment.  If you are on a Unix-like system such as Linux or
-FreeBSD or have a package system like Fink, MacPorts, Cygwin or Homebrew, you
-can simply install its CMake package.  If not, you can get installers for
-Windows and OS X from the [CMake website](http://www.cmake.org/).
-
-Additional dependencies are listed below.
-
-
-#### Dependencies using Visual C++ on Windows
-
-The Microsoft Platform SDK that is installed along with Visual C++ contains all
-the necessary headers, link libraries and tools except for CMake.
-
-
-#### Dependencies with MinGW or MinGW-w64 on Windows
-
-Both the MinGW and the MinGW-w64 packages contain all the necessary headers,
-link libraries and tools except for CMake.
-
-
-#### Dependencies using MinGW or MinGW-w64 cross-compilation
-
-Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages.  For
-example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages
-for 32- and 64-bit version of MinGW-w64, while Debian GNU/Linux and derivatives
-like Ubuntu have the `mingw-w64` package for both.
-
-GLFW has CMake toolchain files in the `CMake/` directory that allow for easy
-cross-compilation of Windows binaries.  To use these files you need to add a
-special parameter when generating the project files or makefiles:
-
-    cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> .
-
-The exact toolchain file to use depends on the prefix used by the MinGW or
-MinGW-w64 binaries on your system.  You can usually see this in the /usr
-directory.  For example, both the Debian/Ubuntu and Cygwin MinGW-w64 packages
-have `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct
-invocation would be:
-
-    cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake .
-
-For more details see the article
-[CMake Cross Compiling](http://www.paraview.org/Wiki/CMake_Cross_Compiling) on
-the CMake wiki.
-
-
-#### Dependencies using Xcode on OS X
-
-Xcode contains all necessary tools except for CMake.  The necessary headers and
-libraries are included in the core OS frameworks.  Xcode can be downloaded from
-the Mac App Store or from the ADC Member Center.
-
-
-#### Dependencies using Linux and X11
-
-To compile GLFW for X11, you need to have the X11 and OpenGL header packages
-installed, as well as the basic development tools like GCC and make.  For
-example, on Ubuntu and other distributions based on Debian GNU/Linux, you need
-to install the `xorg-dev` and `libglu1-mesa-dev` packages.  The former pulls in
-all X.org header packages and the latter pulls in the Mesa OpenGL and GLU
-packages.  GLFW itself doesn't need or use GLU, but some of the examples do.
-Note that using header files and libraries from Mesa during compilation *will
-not* tie your binaries to the Mesa implementation of OpenGL.
-
-
-### Generating files with CMake
-
-Once you have all necessary dependencies it is time to generate the project
-files or makefiles for your development environment.  CMake needs to know two
-paths for this: the path to the source directory and the target path for the
-generated files and compiled binaries.  If these are the same, it is called an
-in-tree build, otherwise it is called an out-of-tree build.
-
-One of several advantages of out-of-tree builds is that you can generate files
-and compile for different development environments using a single source tree.
-
-
-#### Generating files with the CMake command-line tool
-
-To make an in-tree build, enter the root directory of the GLFW source tree and
-run CMake.  The current directory is used as target path, while the path
-provided as an argument is used to find the source tree.
-
-    cd <glfw-root-dir>
-    cmake .
-
-To make an out-of-tree build, make another directory, enter it and run CMake
-with the (relative or absolute) path to the root of the source tree as an
-argument.
-
-    cd <glfw-root-dir>
-    mkdir build
-    cd build
-    cmake ..
-
-
-#### Generating files with the CMake GUI
-
-If you are using the GUI version, choose the root of the GLFW source tree as
-source location and the same directory or another, empty directory as the
-destination for binaries.  Choose *Configure*, change any options you wish to,
-*Configure* again to let the changes take effect and then *Generate*.
-
-
-### CMake options
-
-The CMake files for GLFW provide a number of options, although not all are
-available on all supported platforms.  Some of these are de facto standards
-among CMake users and so have no `GLFW_` prefix.
-
-If you are using the GUI version of CMake, these are listed and can be changed
-from there.  If you are using the command-line version, use the `ccmake` tool.
-Some package systems like Ubuntu and other distributions based on Debian
-GNU/Linux have this tool in a separate `cmake-curses-gui` package.
-
-
-#### Shared CMake options
-
-`BUILD_SHARED_LIBS` determines whether GLFW is built as a static
-library or as a DLL / shared library / dynamic library.
-
-`LIB_SUFFIX` affects where the GLFW shared /dynamic library is
-installed.  If it is empty, it is installed to `$PREFIX/lib`.  If it is set to
-`64`, it is installed to `$PREFIX/lib64`.
-
-`GLFW_CLIENT_LIBRARY` determines which client API library to use.  If set to
-`opengl` the OpenGL library is used, if set to `glesv1` for the OpenGL ES 1.x
-library is used, or if set to `glesv2` the OpenGL ES 2.0 library is used.  The
-selected library and its header files must be present on the system for this to
-work.
-
-`GLFW_BUILD_EXAMPLES` determines whether the GLFW examples are built
-along with the library.
-
-`GLFW_BUILD_TESTS` determines whether the GLFW test programs are
-built along with the library.
-
-
-#### OS X specific CMake options
-
-`GLFW_USE_CHDIR` determines whether `glfwInit` changes the current
-directory of bundled applications to the `Contents/Resources` directory.
-
-`GLFW_USE_MENUBAR` determines whether the first call to
-`glfwCreateWindow` sets up a minimal menu bar.
-
-`GLFW_BUILD_UNIVERSAL` determines whether to build Universal Binaries.
-
-
-#### Windows specific CMake options
-
-`USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version or the
-static library version of the Visual C++ runtime library.  If set to `ON`, the
-DLL version of the Visual C++ library is used.  It is recommended to set this to
-`ON`, as this keeps the executable smaller and benefits from security and bug
-fix updates of the Visual C++ runtime.
-
-`GLFW_USE_DWM_SWAP_INTERVAL` determines whether the swap interval is set even
-when DWM compositing is enabled.  If this is `ON`, the swap interval is set even
-if DWM is enabled.  It is recommended to set this to `OFF`, as doing otherwise
-can lead to severe jitter.
-
-`GLFW_USE_OPTIMUS_HPG` determines whether to export the `NvOptimusEnablement`
-symbol, which forces the use of the high-performance GPU on nVidia Optimus
-systems.
-
-
-#### EGL specific CMake options
-
-`GLFW_USE_EGL` determines whether to use EGL instead of the platform-specific
-context creation API.  Note that EGL is not yet provided on all supported
-platforms.
-
-
-## Installing GLFW
-
-A rudimentary installation target is provided for all supported platforms via
-CMake.  If you are building from the command-line, use the `install` target.
-
-    sudo make install
-
-If you are using an IDE, run the generated install target from the IDE.
+See the [Compiling GLFW](http://www.glfw.org/docs/latest/compile.html) guide in
+the GLFW documentation.
 
 
 ## Using GLFW
 
-See the [GLFW documentation](http://www.glfw.org/docs/latest/).
+See the
+[Building programs that use GLFW](http://www.glfw.org/docs/latest/build.html)
+guide in the GLFW documentation.
 
 
 ## Changelog

docs/Doxyfile.in

@@ -659,6 +659,7 @@ INPUT                  = @GLFW_INTERNAL_DOCS@                         \
                          @GLFW_SOURCE_DIR@/docs/news.dox              \
                          @GLFW_SOURCE_DIR@/docs/quick.dox             \
                          @GLFW_SOURCE_DIR@/docs/moving.dox            \
+                         @GLFW_SOURCE_DIR@/docs/compile.dox           \
                          @GLFW_SOURCE_DIR@/docs/build.dox             \
                          @GLFW_SOURCE_DIR@/docs/context.dox           \
                          @GLFW_SOURCE_DIR@/docs/monitor.dox           \

docs/build.dox

@@ -1,13 +1,13 @@
 /*!
 
-@page build Building programs using GLFW
+@page build Building programs that use GLFW
 
 @tableofcontents
 
 This is about compiling and linking programs that use GLFW.  For information on
 how to write such programs, start with the [introductory tutorial](@ref quick).
-For information on how to build the GLFW library itself, see the
-[Building GLFW](https://github.com/glfw/glfw#building-glfw) guide.
+For information on how to compile the GLFW library itself, see the @ref compile
+guide.
 
 
 @section build_include Including the GLFW header file

docs/compile.dox

@@ -0,0 +1,188 @@
+/*!
+
+@page compile Compiling GLFW
+
+@tableofcontents
+
+This is about compiling the GLFW library itself.  For information on how to
+build programs that use GLFW, see the @ref build guide.
+
+
+@section compile_deps Dependencies
+
+To compile GLFW and the accompanying example programs, you will need **CMake**,
+which will generate the project files or makefiles for your particular
+development environment.  If you are on a Unix-like system such as Linux or
+FreeBSD or have a package system like Fink, MacPorts, Cygwin or Homebrew, you
+can simply install its CMake package.  If not, you can get installers for
+Windows and OS X from the [CMake website](http://www.cmake.org/).
+
+Additional dependencies are listed below.
+
+
+@subsection compile_deps_msvc Dependencies using Visual C++ on Windows
+
+The Microsoft Platform SDK that is installed along with Visual C++ contains all
+the necessary headers, link libraries and tools except for CMake.
+
+
+@subsection compile_deps_mingw Dependencies with MinGW or MinGW-w64 on Windows
+
+Both the MinGW and the MinGW-w64 packages contain all the necessary headers,
+link libraries and tools except for CMake.
+
+
+@subsection compile_deps_mingw_cross Dependencies using MinGW or MinGW-w64 cross-compilation
+
+Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages.  For
+example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages
+for 32- and 64-bit version of MinGW-w64, while Debian GNU/Linux and derivatives
+like Ubuntu have the `mingw-w64` package for both.
+
+GLFW has CMake toolchain files in the `CMake/` directory that allow for easy
+cross-compilation of Windows binaries.  To use these files you need to add a
+special parameter when generating the project files or makefiles:
+
+    cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> .
+
+The exact toolchain file to use depends on the prefix used by the MinGW or
+MinGW-w64 binaries on your system.  You can usually see this in the /usr
+directory.  For example, both the Debian/Ubuntu and Cygwin MinGW-w64 packages
+have `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct
+invocation would be:
+
+    cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake .
+
+For more details see the article
+[CMake Cross Compiling](http://www.paraview.org/Wiki/CMake_Cross_Compiling) on
+the CMake wiki.
+
+
+@subsection compile_deps_xcode Dependencies using Xcode on OS X
+
+Xcode contains all necessary tools except for CMake.  The necessary headers and
+libraries are included in the core OS frameworks.  Xcode can be downloaded from
+the Mac App Store or from the ADC Member Center.
+
+
+@subsection compile_deps_x11 Dependencies using Linux and X11
+
+To compile GLFW for X11, you need to have the X11 and OpenGL header packages
+installed, as well as the basic development tools like GCC and make.  For
+example, on Ubuntu and other distributions based on Debian GNU/Linux, you need
+to install the `xorg-dev` and `libglu1-mesa-dev` packages.  The former pulls in
+all X.org header packages and the latter pulls in the Mesa OpenGL and GLU
+packages.  GLFW itself doesn't need or use GLU, but some of the examples do.
+Note that using header files and libraries from Mesa during compilation *will
+not* tie your binaries to the Mesa implementation of OpenGL.
+
+
+@section compile_cmake Generating files with CMake
+
+Once you have all necessary dependencies it is time to generate the project
+files or makefiles for your development environment.  CMake needs to know two
+paths for this: the path to the source directory and the target path for the
+generated files and compiled binaries.  If these are the same, it is called an
+in-tree build, otherwise it is called an out-of-tree build.
+
+One of several advantages of out-of-tree builds is that you can generate files
+and compile for different development environments using a single source tree.
+
+
+@subsection compile_cmake_cli Generating files with the CMake command-line tool
+
+To make an in-tree build, enter the root directory of the GLFW source tree and
+run CMake.  The current directory is used as target path, while the path
+provided as an argument is used to find the source tree.
+
+    cd <glfw-root-dir>
+    cmake .
+
+To make an out-of-tree build, make another directory, enter it and run CMake
+with the (relative or absolute) path to the root of the source tree as an
+argument.
+
+    cd <glfw-root-dir>
+    mkdir build
+    cd build
+    cmake ..
+
+
+@subsection compile_cmake_gui Generating files with the CMake GUI
+
+If you are using the GUI version, choose the root of the GLFW source tree as
+source location and the same directory or another, empty directory as the
+destination for binaries.  Choose *Configure*, change any options you wish to,
+*Configure* again to let the changes take effect and then *Generate*.
+
+
+@section compile_options CMake options
+
+The CMake files for GLFW provide a number of options, although not all are
+available on all supported platforms.  Some of these are de facto standards
+among CMake users and so have no `GLFW_` prefix.
+
+If you are using the GUI version of CMake, these are listed and can be changed
+from there.  If you are using the command-line version, use the `ccmake` tool.
+Some package systems like Ubuntu and other distributions based on Debian
+GNU/Linux have this tool in a separate `cmake-curses-gui` package.
+
+
+@subsection compile_options_shared Shared CMake options
+
+`BUILD_SHARED_LIBS` determines whether GLFW is built as a static
+library or as a DLL / shared library / dynamic library.
+
+`LIB_SUFFIX` affects where the GLFW shared /dynamic library is
+installed.  If it is empty, it is installed to `$PREFIX/lib`.  If it is set to
+`64`, it is installed to `$PREFIX/lib64`.
+
+`GLFW_CLIENT_LIBRARY` determines which client API library to use.  If set to
+`opengl` the OpenGL library is used, if set to `glesv1` for the OpenGL ES 1.x
+library is used, or if set to `glesv2` the OpenGL ES 2.0 library is used.  The
+selected library and its header files must be present on the system for this to
+work.
+
+`GLFW_BUILD_EXAMPLES` determines whether the GLFW examples are built
+along with the library.
+
+`GLFW_BUILD_TESTS` determines whether the GLFW test programs are
+built along with the library.
+
+
+@subsection compile_options_osx OS X specific CMake options
+
+`GLFW_USE_CHDIR` determines whether `glfwInit` changes the current
+directory of bundled applications to the `Contents/Resources` directory.
+
+`GLFW_USE_MENUBAR` determines whether the first call to
+`glfwCreateWindow` sets up a minimal menu bar.
+
+`GLFW_BUILD_UNIVERSAL` determines whether to build Universal Binaries.
+
+
+@subsection compile_options_win32 Windows specific CMake options
+
+`USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version or the
+static library version of the Visual C++ runtime library.  If set to `ON`, the
+DLL version of the Visual C++ library is used.  It is recommended to set this to
+`ON`, as this keeps the executable smaller and benefits from security and bug
+fix updates of the Visual C++ runtime.
+
+`GLFW_USE_DWM_SWAP_INTERVAL` determines whether the swap interval is set even
+when DWM compositing is enabled.  If this is `ON`, the swap interval is set even
+if DWM is enabled.  It is recommended to set this to `OFF`, as doing otherwise
+can lead to severe jitter.
+
+`GLFW_USE_OPTIMUS_HPG` determines whether to export the `NvOptimusEnablement`
+symbol, which forces the use of the high-performance GPU on nVidia Optimus
+systems.
+
+
+@subsection compile_options_egl EGL specific CMake options
+
+`GLFW_USE_EGL` determines whether to use EGL instead of the platform-specific
+context creation API.  Note that EGL is not yet provided on all supported
+platforms.
+
+*/

docs/main.dox

@@ -11,8 +11,9 @@ existing applications and does not lay claim to the main loop.
 This is the documentation for version 3.0, which has [many new features](@ref news).
 
 There is a [quick tutorial](@ref quick) for people new to GLFW, which shows how
-to write a small but complete program, and a
-[guide for building](@ref build) programs that use GLFW.
+to write a small but complete program, and guides for
+[compiling GLFW](@ref compile) and
+[building programs that use GLFW](@ref build).
 
 If you have used GLFW 2.x in the past, there is a
 [transition guide](@ref moving) that explains what has changed and how to update