Moved client build docs to Doxygen.

This commit is contained in:
Camilla Berglund 2013-06-12 16:06:45 +02:00
parent e6bfbba429
commit c449ef2e12
3 changed files with 163 additions and 157 deletions

158
README.md
View File

@ -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 <GLFW/glfw3.h>
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

View File

@ -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 \

161
docs/build.dox Normal file
View File

@ -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 <GLFW/glfw3.h>
@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.
*/