387 lines
14 KiB
Plaintext
387 lines
14 KiB
Plaintext
/*!
|
|
|
|
@page build_guide Building applications
|
|
|
|
@tableofcontents
|
|
|
|
This is about compiling and linking applications that use GLFW. For information on
|
|
how to write such applications, start with the
|
|
[introductory tutorial](@ref quick_guide). For information on how to compile
|
|
the GLFW library itself, see @ref compile_guide.
|
|
|
|
This is not a tutorial on compilation or linking. It assumes basic
|
|
understanding of how to compile and link a C program as well as how to use the
|
|
specific compiler of your chosen development environment. The compilation
|
|
and linking process should be explained in your C programming material and in
|
|
the documentation for your development environment.
|
|
|
|
|
|
@section build_include Including the GLFW header file
|
|
|
|
You should include the GLFW header in the source files where you use OpenGL or
|
|
GLFW.
|
|
|
|
@code
|
|
#include <GLFW/glfw3.h>
|
|
@endcode
|
|
|
|
This header declares the GLFW API and by default also includes the OpenGL header
|
|
from your development environment. See below for how to control this.
|
|
|
|
The GLFW header also defines any platform-specific macros needed by your OpenGL
|
|
header, so it can be included without needing any window system headers.
|
|
|
|
For example, under Windows you are normally required to include `windows.h`
|
|
before the OpenGL header, which would bring in the whole Win32 API. The GLFW
|
|
header duplicates the small number of macros needed.
|
|
|
|
It does this only when needed, so if `windows.h` _is_ included, the GLFW header
|
|
does not try to redefine those symbols. The reverse is not true, i.e.
|
|
`windows.h` cannot cope if any of its symbols have already been defined.
|
|
|
|
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 header and it will handle this
|
|
|
|
If you are using an OpenGL extension loading library such as
|
|
[glad](https://github.com/Dav1dde/glad), the extension loader header should
|
|
be included _before_ the GLFW one.
|
|
|
|
@code
|
|
#include <glad/glad.h>
|
|
#include <GLFW/glfw3.h>
|
|
@endcode
|
|
|
|
Alternatively the @ref GLFW_INCLUDE_NONE macro (described below) can be used to
|
|
prevent the GLFW header from including the OpenGL header.
|
|
|
|
@code
|
|
#define GLFW_INCLUDE_NONE
|
|
#include <GLFW/glfw3.h>
|
|
#include <glad/glad.h>
|
|
@endcode
|
|
|
|
|
|
@subsection build_macros GLFW header option macros
|
|
|
|
These macros may be defined before the inclusion of the GLFW header and affect
|
|
its behavior.
|
|
|
|
@anchor GLFW_DLL
|
|
__GLFW_DLL__ is required on Windows when using the GLFW DLL, to tell the
|
|
compiler that the GLFW functions are defined in a DLL.
|
|
|
|
The following macros control which OpenGL or OpenGL ES API header is included.
|
|
Only one of these may be defined at a time.
|
|
|
|
@anchor GLFW_INCLUDE_GLCOREARB
|
|
__GLFW_INCLUDE_GLCOREARB__ makes the GLFW header include the modern
|
|
`GL/glcorearb.h` header (`OpenGL/gl3.h` on macOS) instead of the regular OpenGL
|
|
header.
|
|
|
|
@anchor GLFW_INCLUDE_ES1
|
|
__GLFW_INCLUDE_ES1__ makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h`
|
|
header instead of the regular OpenGL header.
|
|
|
|
@anchor GLFW_INCLUDE_ES2
|
|
__GLFW_INCLUDE_ES2__ makes the GLFW header include the OpenGL ES 2.0
|
|
`GLES2/gl2.h` header instead of the regular OpenGL header.
|
|
|
|
@anchor GLFW_INCLUDE_ES3
|
|
__GLFW_INCLUDE_ES3__ makes the GLFW header include the OpenGL ES 3.0
|
|
`GLES3/gl3.h` header instead of the regular OpenGL header.
|
|
|
|
@anchor GLFW_INCLUDE_ES31
|
|
__GLFW_INCLUDE_ES31__ makes the GLFW header include the OpenGL ES 3.1
|
|
`GLES3/gl31.h` header instead of the regular OpenGL header.
|
|
|
|
@anchor GLFW_INCLUDE_ES32
|
|
__GLFW_INCLUDE_ES31__ makes the GLFW header include the OpenGL ES 3.2
|
|
`GLES3/gl32.h` header instead of the regular OpenGL header.
|
|
|
|
@anchor GLFW_INCLUDE_NONE
|
|
__GLFW_INCLUDE_NONE__ makes the GLFW header not include any OpenGL or OpenGL ES
|
|
API header. This is useful in combination with an extension loading library.
|
|
|
|
If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h`
|
|
header (`OpenGL/gl.h` on macOS) is included.
|
|
|
|
The following macros control the inclusion of additional API headers. Any
|
|
number of these may be defined simultaneously, and/or together with one of the
|
|
above macros.
|
|
|
|
@anchor GLFW_INCLUDE_VULKAN
|
|
__GLFW_INCLUDE_VULKAN__ makes the GLFW header include the Vulkan
|
|
`vulkan/vulkan.h` header in addition to any selected OpenGL or OpenGL ES header.
|
|
|
|
@anchor GLFW_INCLUDE_GLEXT
|
|
__GLFW_INCLUDE_GLEXT__ makes the GLFW header include the appropriate extension
|
|
header for the OpenGL or OpenGL ES header selected above after and in addition
|
|
to that header.
|
|
|
|
@anchor GLFW_INCLUDE_GLU
|
|
__GLFW_INCLUDE_GLU__ makes the header include the GLU header in addition to the
|
|
header selected above. This should only be used with the standard OpenGL header
|
|
and only for compatibility with legacy code. GLU has been deprecated and should
|
|
not be used in new code.
|
|
|
|
@note GLFW does not provide any of the API headers mentioned above. They must
|
|
be provided by your development environment or your OpenGL, OpenGL ES or Vulkan
|
|
SDK.
|
|
|
|
@note None of these macros may be defined during the compilation of GLFW itself.
|
|
If your build includes GLFW and you define any these in your build files, make
|
|
sure they are not applied to the GLFW sources.
|
|
|
|
|
|
@section build_link Link with the right libraries
|
|
|
|
GLFW is essentially a wrapper of various platform-specific APIs and therefore
|
|
needs to link against many different system libraries. If you are using GLFW as
|
|
a shared library / dynamic library / DLL then it takes care of these links.
|
|
However, if you are using GLFW as a static library then your executable will
|
|
need to link against these libraries.
|
|
|
|
On Windows and macOS, the list of system libraries is static and can be
|
|
hard-coded into your build environment. See the section for your development
|
|
environment below. On Linux and other Unix-like operating systems, the list
|
|
varies but can be retrieved in various ways as described below.
|
|
|
|
A good general introduction to linking is
|
|
[Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by
|
|
David Drysdale.
|
|
|
|
|
|
@subsection build_link_win32 With MinGW or Visual C++ on 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 using MinGW to link an application with the static version of GLFW, you
|
|
must also explicitly link with `gdi32`. Other toolchains including MinGW-w64
|
|
include it in the set of default libraries along with other dependencies like
|
|
`user32` and `kernel32`.
|
|
|
|
If you are using GLU, you must also link with `glu32`.
|
|
|
|
The link library for the GLFW DLL is named `glfw3dll`. When compiling an
|
|
application that uses the DLL version of GLFW, you need to define the @ref
|
|
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.
|
|
|
|
An application using the GLFW DLL does not need to link against any of its
|
|
dependencies, but you still have to link against `glu32` if it uses GLU.
|
|
|
|
|
|
@subsection build_link_cmake_source With CMake and GLFW source
|
|
|
|
This section is about using CMake to compile and link GLFW along with your
|
|
application. If you want to use an installed binary instead, see @ref
|
|
build_link_cmake_package.
|
|
|
|
With a few changes to your `CMakeLists.txt` you can have the GLFW source tree
|
|
built along with your application.
|
|
|
|
When including GLFW as part of your build, you probably don't want to build the
|
|
GLFW tests, examples and documentation. To disable these, set the corresponding
|
|
cache variables before adding the GLFW source tree.
|
|
|
|
@code
|
|
set(GLFW_BUILD_DOCS OFF CACHE BOOL "" FORCE)
|
|
set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE)
|
|
set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
|
|
@endcode
|
|
|
|
Then add the root directory of the GLFW source tree to your project. This
|
|
will add the `glfw` target and the necessary cache variables to your project.
|
|
|
|
@code{.cmake}
|
|
add_subdirectory(path/to/glfw)
|
|
@endcode
|
|
|
|
Once GLFW has been added to the project, link against it with the `glfw` target.
|
|
This adds all link-time dependencies of GLFW as it is currently configured,
|
|
the include directory for the GLFW header and, when applicable, the @ref
|
|
GLFW_DLL macro.
|
|
|
|
@code{.cmake}
|
|
target_link_libraries(myapp glfw)
|
|
@endcode
|
|
|
|
Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
|
|
OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
|
|
If your application calls OpenGL directly, instead of using a modern
|
|
[extension loader library](@ref context_glext_auto) you can find it by requiring
|
|
the OpenGL package.
|
|
|
|
@code{.cmake}
|
|
find_package(OpenGL REQUIRED)
|
|
@endcode
|
|
|
|
If OpenGL is found, the `OPENGL_FOUND` variable is true and the
|
|
`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
|
|
|
|
@code{.cmake}
|
|
target_include_directories(myapp PUBLIC ${OPENGL_INCLUDE_DIR})
|
|
target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
|
|
@endcode
|
|
|
|
The OpenGL CMake package also looks for GLU. If GLU is found, the
|
|
`OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
|
|
`OPENGL_glu_LIBRARY` cache variables can be used.
|
|
|
|
@code{.cmake}
|
|
target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
|
|
@endcode
|
|
|
|
@note GLU has been deprecated and should not be used in new code, but some
|
|
legacy code requires it. See the [section on GLU](@ref moving_glu) in the
|
|
transition guide for suggested replacements.
|
|
|
|
|
|
@subsection build_link_cmake_package With CMake and installed GLFW binaries
|
|
|
|
This section is about using CMake to link GLFW after it has been built and
|
|
installed. If you want to build it along with your application instead, see
|
|
@ref build_link_cmake_source.
|
|
|
|
With a few changes to your `CMakeLists.txt` you can locate the package and
|
|
target files generated when GLFW is installed.
|
|
|
|
@code{.cmake}
|
|
find_package(glfw3 3.3 REQUIRED)
|
|
@endcode
|
|
|
|
Once GLFW has been added to the project, link against it with the `glfw` target.
|
|
This adds all link-time dependencies of GLFW as it is currently configured,
|
|
the include directory for the GLFW header and, when applicable, the @ref
|
|
GLFW_DLL macro.
|
|
|
|
@code{.cmake}
|
|
target_link_libraries(myapp glfw)
|
|
@endcode
|
|
|
|
Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
|
|
OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
|
|
If your application calls OpenGL directly, instead of using a modern
|
|
[extension loader library](@ref context_glext_auto) you can find it by requiring
|
|
the OpenGL package.
|
|
|
|
@code{.cmake}
|
|
find_package(OpenGL REQUIRED)
|
|
@endcode
|
|
|
|
If OpenGL is found, the `OPENGL_FOUND` variable is true and the
|
|
`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
|
|
|
|
@code{.cmake}
|
|
target_include_directories(myapp PUBLIC ${OPENGL_INCLUDE_DIR})
|
|
target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
|
|
@endcode
|
|
|
|
The OpenGL CMake package also looks for GLU. If GLU is found, the
|
|
`OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
|
|
`OPENGL_glu_LIBRARY` cache variables can be used.
|
|
|
|
@code{.cmake}
|
|
target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
|
|
@endcode
|
|
|
|
@note GLU has been deprecated and should not be used in new code, but some
|
|
legacy code requires it. See the [section on GLU](@ref moving_glu) in the
|
|
transition guide for suggested replacements.
|
|
|
|
|
|
@subsection build_link_pkgconfig With makefiles and pkg-config on Unix
|
|
|
|
GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/),
|
|
and the `glfw3.pc` pkg-config file is generated when the GLFW library is built
|
|
and is installed along with it. A pkg-config file describes all necessary
|
|
compile-time and link-time flags and dependencies needed to use a library. When
|
|
they are updated or if they differ between systems, you will get the correct
|
|
ones automatically.
|
|
|
|
A typical compile and link command-line when using the static version of the
|
|
GLFW library may look like this:
|
|
|
|
@code{.sh}
|
|
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
|
|
@endcode
|
|
|
|
If you are using the shared version of the GLFW library, omit the `--static`
|
|
flag.
|
|
|
|
@code{.sh}
|
|
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
|
|
@endcode
|
|
|
|
You can also use the `glfw3.pc` file without installing it first, by using the
|
|
`PKG_CONFIG_PATH` environment variable.
|
|
|
|
@code{.sh}
|
|
env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
|
|
@endcode
|
|
|
|
The dependencies do not include OpenGL or GLU, as GLFW loads any OpenGL, OpenGL
|
|
ES or Vulkan libraries it needs at runtime and does not use GLU. On macOS, GLU
|
|
is built into the OpenGL framework, so if you need GLU you don't need to do
|
|
anything extra. If you need GLU and are using Linux or BSD, you should add the
|
|
`glu` pkg-config package.
|
|
|
|
@code{.sh}
|
|
cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`
|
|
@endcode
|
|
|
|
@note GLU has been deprecated and should not be used in new code, but some
|
|
legacy code requires it. See the [section on GLU](@ref moving_glu) in the
|
|
transition guide for suggested replacements.
|
|
|
|
If you are using the static version of the GLFW library, make sure you don't
|
|
link statically against GLU.
|
|
|
|
@code{.sh}
|
|
cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --static --libs glfw3` `pkg-config --libs glu`
|
|
@endcode
|
|
|
|
|
|
@subsection build_link_xcode With Xcode on macOS
|
|
|
|
If you are using the dynamic library version of GLFW, add it to the project
|
|
dependencies.
|
|
|
|
If you are using the static library version of GLFW, add it and the Cocoa,
|
|
OpenGL, IOKit and CoreVideo frameworks to the project as dependencies. They can
|
|
all be found in `/System/Library/Frameworks`.
|
|
|
|
|
|
@subsection build_link_osx With command-line on macOS
|
|
|
|
It is recommended that you use [pkg-config](@ref build_link_pkgconfig) when
|
|
building from the command line on macOS. That way you will get any new
|
|
dependencies added automatically. If you still wish to build manually, you need
|
|
to add the required frameworks and libraries to your command-line yourself using
|
|
the `-l` and `-framework` switches.
|
|
|
|
If you are using the dynamic GLFW library, which is named `libglfw.3.dylib`, do:
|
|
|
|
@code{.sh}
|
|
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo
|
|
@endcode
|
|
|
|
If you are using the static library, named `libglfw3.a`, substitute `-lglfw3`
|
|
for `-lglfw`.
|
|
|
|
Note that you do not add the `.framework` extension to a framework when linking
|
|
against it from the command-line.
|
|
|
|
The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing
|
|
special to do 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 macOS native version of GLFW.
|
|
|
|
*/
|