mirror of
https://github.com/glfw/glfw.git
synced 2024-11-25 22:14:34 +00:00
Moved client build docs to Doxygen.
This commit is contained in:
Camilla Berglund
parent
e6bfbba429
commit
c449ef2e12
158
README.md
158
README.md
@ -99,163 +99,7 @@ CMake.
|
|||||||
|
|
||||||
## Using GLFW
|
## Using GLFW
|
||||||
|
|
||||||
There are two aspects to using GLFW:
|
See the [GLFW 3.0 documentation](http://www.glfw.org/docs/3.0/).
|
||||||
|
|
||||||
- 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.
|
|
||||||
|
|
||||||
|
|
||||||
## Changes for version 3.0
|
## Changes for version 3.0
|
||||||
|
|||||||
@ -671,6 +671,7 @@ WARN_LOGFILE = @GLFW_BINARY_DIR@/docs/warnings.txt
|
|||||||
INPUT = @GLFW_INTERNAL_DOCS@ \
|
INPUT = @GLFW_INTERNAL_DOCS@ \
|
||||||
@GLFW_SOURCE_DIR@/include/GLFW/glfw3.h \
|
@GLFW_SOURCE_DIR@/include/GLFW/glfw3.h \
|
||||||
@GLFW_SOURCE_DIR@/include/GLFW/glfw3native.h \
|
@GLFW_SOURCE_DIR@/include/GLFW/glfw3native.h \
|
||||||
|
@GLFW_SOURCE_DIR@/docs/build.dox \
|
||||||
@GLFW_SOURCE_DIR@/docs/compat.dox \
|
@GLFW_SOURCE_DIR@/docs/compat.dox \
|
||||||
@GLFW_SOURCE_DIR@/docs/context.dox \
|
@GLFW_SOURCE_DIR@/docs/context.dox \
|
||||||
@GLFW_SOURCE_DIR@/docs/main.dox \
|
@GLFW_SOURCE_DIR@/docs/main.dox \
|
||||||
|
|||||||
161
docs/build.dox
Normal file
161
docs/build.dox
Normal 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.
|
||||||
|
|
||||||
|
*/
|
||||||
Loading…
Reference in New Issue
Block a user