From ffb699fb06ad9f6bea8f90b025631362dd9dd0d4 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Wed, 7 Aug 2013 17:05:32 +0200 Subject: [PATCH] Build documentation improvements. --- CMake/README.txt | 18 -------- README.md | 106 +++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 94 insertions(+), 30 deletions(-) delete mode 100644 CMake/README.txt diff --git a/CMake/README.txt b/CMake/README.txt deleted file mode 100644 index 9dbaee26..00000000 --- a/CMake/README.txt +++ /dev/null @@ -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= . - -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 - diff --git a/README.md b/README.md index e3fa991e..d353d5e3 100644 --- a/README.md +++ b/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 -#### X11 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. + + +#### 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= . + +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. + + +#### 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 + 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 + 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