diff --git a/README.md b/README.md index 09c78c21..445d8508 100644 --- a/README.md +++ b/README.md @@ -99,163 +99,7 @@ CMake. ## Using GLFW -There are two aspects to using GLFW: - - - Using the GLFW API - - Compiling and linking programs using the GLFW library - -The first point is covered in the WIP -[reference manual](http://www.glfw.org/TEMP/3.0/). - - -### Include the GLFW header file - -In the files of your program where you use OpenGL or GLFW, you should include -the GLFW 3 header file, i.e.: - - #include - -This defines all the constants, types and function prototypes of the GLFW API. -It also includes the chosen client API header files (by default OpenGL), and -defines all the constants and types necessary for those headers to work on that -platform. - -For example, under Windows you are normally required to include `windows.h` -before including `GL/gl.h`. This would make your source file tied to Windows -and pollute your code's namespace with the whole Win32 API. - -Instead, the GLFW header takes care of this for you, not by including -`windows.h`, but rather by itself duplicating only the necessary parts of it. -It does this only where needed, so if `windows.h` *is* included, the GLFW header -does not try to redefine those symbols. - -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 one and it will detect this - -If you are using an OpenGL extension loading library such as -[GLEW](http://glew.sourceforge.net/), the GLEW header should also be included -*before* the GLFW one. The GLEW header defines macros that disable any OpenGL -header that the GLFW header includes and GLEW will work as expected. - - -#### GLFW header option macros - -These macros may be defined before the inclusion of the GLFW header. - -`GLFW_INCLUDE_GLCOREARB` makes the header include the modern `GL/glcorearb.h` -header (`OpenGL/gl3.h` on Mac OS X) instead of the regular OpenGL header. - -`GLFW_INCLUDE_ES1` makes the header include the OpenGL ES 1.x `GLES/gl.h` header -instead of the regular OpenGL header. - -`GLFW_INCLUDE_ES2` makes the header include the OpenGL ES 2.0 `GLES2/gl2.h` -header instead of the regular OpenGL header. - -`GLFW_INCLUDE_ES3` makes the header include the OpenGL ES 3.0 `GLES3/gl3.h` -header instead of the regular OpenGL header. - -`GLFW_INCLUDE_NONE` makes the header not include any client API header. - -`GLFW_INCLUDE_GLU` makes the header include the GLU header. This only makes -sense if you are using OpenGL. - -`GLFW_DLL` is necessary when using the GLFW DLL on Windows. - - -### Link with the right libraries - -#### Using GLFW from CMake - -The `GLFW_LIBRARIES` cache variable contains all link-time dependencies of GLFW -as it is currently configured, so to link against GLFW simply do: - - target_link_libraries(myapp glfw ${GLFW_LIBRARIES}) - -Note that this does not include GLU, as GLFW does not use it. If your -application needs GLU, you can add it to the list of dependencies with the -`OPENGL_glu_LIBRARY` cache variable. - - -#### Windows static library - -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 a program under Windows that uses the static version of GLFW, you -must link with `opengl32`. If you are using GLU, you must also link with -`glu32`. - - -#### Windows DLL - -The link library for the GLFW DLL is named `glfw3dll`. When compiling a program -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. - -A program using the GLFW DLL does not need to link against any of its -dependencies, but you still have to link against `opengl32` if your program uses -OpenGL and `glu32` if it uses GLU. - - -#### Unix library - -GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/), -and `glfw3.pc` file is generated when the library is built and installed along -with it. You can use it without installation using the `PKG_CONFIG_PATH` -environment variable. See the documentation for pkg-config for more details. - -A typical compile and link command-line when using the static may look like this: - - cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3` - -If you are using the shared library, simply omit the `--static` flag. - -If you are using GLU, you should also add `-lGLU` to your link flags. - - -#### Mac OS X static library - -GLFW on Mac OS X uses the Cocoa, OpenGL and IOKit frameworks. - -If you are using Xcode, you can simply add the GLFW library and these frameworks -as dependencies. - -If you are building from the -command-line, it is recommended that you use pkg-config - -GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/), -and `glfw3.pc` file is generated when the library is built and installed along -with it. You can use it without installation using the `PKG_CONFIG_PATH` -environment variable. See the documentation for pkg-config for more details. - -You can find pkg-config in most package systems such as -[Fink](http://www.finkproject.org/) and [MacPorts](http://www.macports.org/), so -if you have one of them installed, simply install pkg-config. Once you have -pkg-config available, the command-line for compiling and linking your -program is: - - cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3` - -If you do not wish to use pkg-config, you need to add the required frameworks -and libraries to your command-line using the `-l` and `-framework` switches, -i.e.: - - cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit - -Note that you do not add the `.framework` extension to a framework when adding -it from the command-line. - -The OpenGL framework contains both the OpenGL and GLU APIs, so there is no need -to add additional libraries or frameworks 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 Mac OS X native version of -GLFW. +See the [GLFW 3.0 documentation](http://www.glfw.org/docs/3.0/). ## Changes for version 3.0 diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index f3c9a0db..9359dd8c 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -671,6 +671,7 @@ WARN_LOGFILE = @GLFW_BINARY_DIR@/docs/warnings.txt INPUT = @GLFW_INTERNAL_DOCS@ \ @GLFW_SOURCE_DIR@/include/GLFW/glfw3.h \ @GLFW_SOURCE_DIR@/include/GLFW/glfw3native.h \ + @GLFW_SOURCE_DIR@/docs/build.dox \ @GLFW_SOURCE_DIR@/docs/compat.dox \ @GLFW_SOURCE_DIR@/docs/context.dox \ @GLFW_SOURCE_DIR@/docs/main.dox \ diff --git a/docs/build.dox b/docs/build.dox new file mode 100644 index 00000000..3df8e002 --- /dev/null +++ b/docs/build.dox @@ -0,0 +1,161 @@ +/*! + +@page build Building programs using 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). + + +@section build_include Including the GLFW header file + +In the files of your program where you use OpenGL or GLFW, you should include +the GLFW 3 header file, i.e.: + +@code +#include +@endcode + +This defines all the constants, types and function prototypes of the GLFW API. +It also includes the chosen client API header files (by default OpenGL), and +defines all the constants and types necessary for those headers to work on that +platform. + +For example, under Windows you are normally required to include `windows.h` +before including `GL/gl.h`. This would make your source file tied to Windows +and pollute your code's namespace with the whole Win32 API. + +Instead, the GLFW header takes care of this for you, not by including +`windows.h`, but rather by itself duplicating only the necessary parts of it. +It does this only where needed, so if `windows.h` *is* included, the GLFW header +does not try to redefine those symbols. + +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 one and it will detect this + +If you are using an OpenGL extension loading library such as +[GLEW](http://glew.sourceforge.net/), the GLEW header should also be included +*before* the GLFW one. The GLEW header defines macros that disable any OpenGL +header that the GLFW header includes and GLEW will work as expected. + + +@subsection build_macros GLFW header option macros + +These macros may be defined before the inclusion of the GLFW header and affect +how that header behaves. + +`GLFW_INCLUDE_GLCOREARB` makes the header include the modern `GL/glcorearb.h` +header (`OpenGL/gl3.h` on Mac OS X) instead of the regular OpenGL header. + +`GLFW_INCLUDE_ES1` makes the header include the OpenGL ES 1.x `GLES/gl.h` header +instead of the regular OpenGL header. + +`GLFW_INCLUDE_ES2` makes the header include the OpenGL ES 2.0 `GLES2/gl2.h` +header instead of the regular OpenGL header. + +`GLFW_INCLUDE_ES3` makes the header include the OpenGL ES 3.0 `GLES3/gl3.h` +header instead of the regular OpenGL header. + +`GLFW_INCLUDE_NONE` makes the header not include any client API header. + +`GLFW_INCLUDE_GLU` makes the header include the GLU header. This only makes +sense if you are using OpenGL. + +`GLFW_DLL` is necessary when using the GLFW DLL on Windows, in order to explain +to the compiler that the GLFW functions will be coming from another executable. + + +@section build_link Link with the right libraries + +@subsection build_link_cmake Using GLFW from CMake + +The `GLFW_LIBRARIES` cache variable contains all link-time dependencies of GLFW +as it is currently configured, so to link against GLFW simply do: + + target_link_libraries(myapp glfw ${GLFW_LIBRARIES}) + +Note that this does not include GLU, as GLFW does not use it. If your +application needs GLU, you can add it to the list of dependencies with the +`OPENGL_glu_LIBRARY` cache variable. + + +@subsection build_link_win32 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 a program under Windows that uses the static version of GLFW, you +must link with `opengl32`. If you are using GLU, you must also link with +`glu32`. + +The link library for the GLFW DLL is named `glfw3dll`. When compiling a program +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. + +A program using the GLFW DLL does not need to link against any of its +dependencies, but you still have to link against `opengl32` if your program uses +OpenGL and `glu32` if it uses GLU. + + +@subsection build_link_unix Unix with X11 + +GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/), +and `glfw3.pc` file is generated when the library is built and installed along +with it. You can use it without installation using the `PKG_CONFIG_PATH` +environment variable. See the documentation for pkg-config for more details. + +A typical compile and link command-line when using the static may look like this: + + cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3` + +If you are using the shared library, simply omit the `--static` flag. + +If you are using GLU, you should also add `-lGLU` to your link flags. + + +@subsection build_link_osx Mac OS X + +GLFW on Mac OS X uses the Cocoa, OpenGL and IOKit frameworks. + +If you are using Xcode, you can simply add the GLFW library and these frameworks +as dependencies. + +If you are building from the +command-line, it is recommended that you use pkg-config + +GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/), +and `glfw3.pc` file is generated when the library is built and installed along +with it. You can use it without installation using the `PKG_CONFIG_PATH` +environment variable. See the documentation for pkg-config for more details. + +You can find pkg-config in most package systems such as +[Fink](http://www.finkproject.org/) and [MacPorts](http://www.macports.org/), so +if you have one of them installed, simply install pkg-config. Once you have +pkg-config available, the command-line for compiling and linking your +program is: + + cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3` + +If you do not wish to use pkg-config, you need to add the required frameworks +and libraries to your command-line using the `-l` and `-framework` switches, +i.e.: + + cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit + +Note that you do not add the `.framework` extension to a framework when adding +it from the command-line. + +The OpenGL framework contains both the OpenGL and GLU APIs, so there is no need +to add additional libraries or frameworks 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 Mac OS X native version of +GLFW. + +*/