Build documentation improvements.

CMake/README.txt

@@ -1,18 +0,0 @@
-This directory contains a collection of toolchain definitions for
-cross-compiling for Windows using MinGW on various other systems.
-
-To use these files you add a special parameter when configuring the source tree:
-
-  cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> .
-
-The exact file to use depends on the prefix used by the MinGW binaries on your
-system.  You can usually see this in the /usr directory, i.e. the Ubuntu
-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 this article:
-
-  http://www.paraview.org/Wiki/CMake_Cross_Compiling 
-

README.md

@@ -18,29 +18,111 @@ the GLFW 3 API.
 
 ## Compiling GLFW
 
-To compile GLFW and the accompanying example programs, you will need the
-[CMake](http://www.cmake.org/) build system.
+### 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/).
 
-### Dependencies
+Additional dependencies are listed below.
+
+
+#### 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.
+
+
+#### MinGW or MinGW-w64 on Windows
+
+These packages contain all the necessary headers, link libraries and tools
+except for CMake.
+
+
+#### 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:
 
-#### X11 dependencies
+    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.
+
+
+#### 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.
+
+
+#### Unix-like systems with X11
 
 To compile GLFW for X11 and GLX, you need to have the X and OpenGL header
-packages installed.  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.  Note that using header files and
-libraries from Mesa during compilation *will not* tie your binaries to the Mesa
-implementation of OpenGL.
+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.  Note that using header files and libraries from Mesa during
+compilation *will not* tie your binaries to the Mesa implementation of OpenGL.
+
+
+### Generating with CMake
+
+Once you have all necessary dependencies, it is time to generate the project
+files or makefiles for your development environment.  If you are using the
+command-line version of CMake, the easiest way is to make an in-tree build.
+Enter the root directory of the GLFW source tree and do
+
+    cd <glfw-root-dir>
+    cmake .
+
+The dot is an argument telling CMake where the root of the source tree is
+located, while the current directory is used as the target for binaries.  If
+you prefer to do an out-of-tree build, make another directory, enter it and
+run CMake with the (relative or absolute) path to the root directory.
+
+    cd <glfw-root-dir>
+    mkdir build
+    cd build
+    cmake ..
+
+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 and then *Generate*.
 
 
 ### CMake options
 
-There are a number of CMake build options for GLFW, although not all are
+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 options