From 174c72f2c03bca0527a6c040a22ffa3de09878e5 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Sun, 27 Oct 2013 12:50:33 +0100 Subject: [PATCH] Moved GLFW compilation guide to docs. --- README.md | 199 ++--------------------------------------------- docs/Doxyfile.in | 1 + docs/build.dox | 6 +- docs/compile.dox | 188 ++++++++++++++++++++++++++++++++++++++++++++ docs/main.dox | 5 +- 5 files changed, 201 insertions(+), 198 deletions(-) create mode 100644 docs/compile.dox diff --git a/README.md b/README.md index 04679dd3..b32f358d 100644 --- a/README.md +++ b/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= . - -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 - 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 - 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 diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index eb547d35..ed6c6589 100644 --- a/docs/Doxyfile.in +++ b/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 \ diff --git a/docs/build.dox b/docs/build.dox index 1f92a5b7..86ec1e5f 100644 --- a/docs/build.dox +++ b/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 diff --git a/docs/compile.dox b/docs/compile.dox new file mode 100644 index 00000000..579f10a2 --- /dev/null +++ b/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= . + +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 + 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 + 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. + +*/ diff --git a/docs/main.dox b/docs/main.dox index 76675174..18980796 100644 --- a/docs/main.dox +++ b/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