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.:

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.

• 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, 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 and affect the behavior of the header. Note that GLFW does not provide any of the OpenGL or OpenGL ES headers mentioned below. These are provided by your development environment or your OpenGL or OpenGL ES SDK.

GLFW_INCLUDE_GLCOREARB makes the header include the modern GL/glcorearb.h header ( OpenGL/gl3.h on 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 in addition to the OpenGL header. This should only be used with the default GL/gl.h header ( OpenGL/gl.h on OS X), i.e. if you are not using any of the above macros.

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. It has no function on other platforms.

Link with the right libraries

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 linking a program under Windows that uses the static version of GLFW, you must link with opengl32 . On some versions of MinGW, you must also explicitly link with gdi32 , while other versions of MinGW 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 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.

With CMake and GLFW source

You can use the GLFW source tree directly from a project that uses CMake. This way, GLFW will be built along with your application as needed.

Firstly, 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.

To be able to include the GLFW header from your code, you need to tell the compiler where to find it.

Once GLFW has been added to the project, the GLFW_LIBRARIES cache variable contains all link-time dependencies of GLFW as it is currently configured. To link against GLFW, link against them and the glfw target.

Note that GLFW_LIBRARIES 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, which is implicitly created when the GLFW CMake files look for OpenGL.

With CMake on Unix and installed GLFW binaries

CMake can import settings from pkg-config, which GLFW supports. When you installed GLFW, the pkg-config file glfw3.pc was installed along with it.

First you need to find the PkgConfig package. If this fails, you may need to install the pkg-config package for your distribution.

This creates the CMake commands to find pkg-config packages. Then you need to find the GLFW package.

This creates the CMake variables you need to use GLFW. To be able to include the GLFW header, you need to tell your compiler where it is.

You also need to link against the correct libraries. If you are using the shared library version of GLFW, use the GLFW_LIBRARIES variable.

If you are using the static library version of GLFW, use the GLFW_STATIC_LIBRARIES variable instead.

With pkg-config on OS X or other Unix

GLFW supports pkg-config, and the glfw3.pc file is generated when the GLFW library is built and installed along with it.
A typical compile and link command-line when using the static may look like this:

If you are using the shared library, simply omit the —static flag.

You can also use the glfw3.pc file without installing it first, by using the PKG_CONFIG_PATH environment variable.

The dependencies do not include GLU, as GLFW does not need it. On OS X, 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 -lGLU to your link flags.

See the manpage and other documentation for pkg-config and your compiler and linker for more information on how to link programs.

With Xcode on OS X

If you are using the dynamic library version of GLFW, simply 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.

With command-line on OS X

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.:

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 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 OS X native version of GLFW.

Last update on Sun Nov 4 2018 for GLFW 3.0.4

Including the GLFW header file

You should include the GLFW header in the source files where you use OpenGL or GLFW.

This header defines all the constants and declares all the types and function prototypes of the GLFW API. By default it also includes the OpenGL header from your development environment. See option macros below for how to select OpenGL ES headers and more.

The GLFW header also defines any platform-specific macros needed by your OpenGL header, so that it can be included without needing any window system headers.

It does this only when needed, so if window system headers are included, the GLFW header does not try to redefine those symbols. The reverse is not true, i.e. windows.h cannot cope if any Win32 symbols have already been defined.

• Use the GLFW header to include OpenGL or OpenGL ES headers portably
• Do not include window system headers unless you will use those APIs directly
• If you do need such headers, include them before the GLFW header

If you are using an OpenGL extension loading library such as glad, the extension loader header should be included before the GLFW one. GLFW attempts to detect any OpenGL or OpenGL ES header or extension loader header included before it and will then disable the inclusion of the default OpenGL header. Most extension loaders also define macros that disable similar headers below it.

Both of these mechanisms depend on the extension loader header defining a known macro. If yours doesn’t or you don’t know which one your users will pick, the GLFW_INCLUDE_NONE macro will explicitly to prevent the GLFW header from including the OpenGL header. This will also allow you to include the two headers in any order.

GLFW header option macros

These macros may be defined before the inclusion of the GLFW header and affect its behavior.

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.

Note GLFW does not provide any of the API headers mentioned below. They are provided by your development environment or your OpenGL, OpenGL ES or Vulkan SDK, and most of them can be downloaded from the Khronos Registry.

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.

GLFW_INCLUDE_ES1 makes the GLFW header include the OpenGL ES 1.x GLES/gl.h header instead of the regular OpenGL header.

GLFW_INCLUDE_ES2 makes the GLFW header include the OpenGL ES 2.0 GLES2/gl2.h header instead of the regular OpenGL header.

GLFW_INCLUDE_ES3 makes the GLFW header include the OpenGL ES 3.0 GLES3/gl3.h header instead of the regular OpenGL header.

GLFW_INCLUDE_ES31 makes the GLFW header include the OpenGL ES 3.1 GLES3/gl31.h header instead of the regular OpenGL header.

GLFW_INCLUDE_ES32 makes the GLFW header include the OpenGL ES 3.2 GLES3/gl32.h header instead of the regular OpenGL header.

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, unless GLFW detects the inclusion guards of any OpenGL, OpenGL ES or extension loader header it knows about.

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.

GLFW_INCLUDE_VULKAN makes the GLFW header include the Vulkan vulkan/vulkan.h header in addition to any selected OpenGL or OpenGL ES header.

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.

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 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.

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 by David Drysdale.

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 .

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 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.

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 With CMake and installed GLFW binaries.

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.

Add the root directory of the GLFW source tree to your project. This will add the glfw target to your project.

Once GLFW has been added, link your application against the glfw target. This adds the GLFW library and its link-time dependencies as it is currently configured, the include directory for the GLFW header and, when applicable, the GLFW_DLL macro.

Note that the glfw target does not depend on OpenGL, as GLFW loads any OpenGL, OpenGL ES or Vulkan libraries it needs at runtime. If your application calls OpenGL directly, instead of using a modern extension loader library, use the OpenGL CMake package.

If OpenGL is found, the OpenGL::GL target is added to your project, containing library and include directory paths. Link against this like any other library.

For a minimal example of a program and GLFW sources built with CMake, see the GLFW CMake Starter on GitHub.

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 With CMake and GLFW source.

With a few changes to your CMakeLists.txt you can locate the package and target files generated when GLFW is installed.

Once GLFW has been added to the project, link against it with the glfw target. This adds the GLFW library and its link-time dependencies, the include directory for the GLFW header and, when applicable, the GLFW_DLL macro.

Note that the glfw target does not depend on OpenGL, as GLFW loads any OpenGL, OpenGL ES or Vulkan libraries it needs at runtime. If your application calls OpenGL directly, instead of using a modern extension loader library, use the OpenGL CMake package.

If OpenGL is found, the OpenGL::GL target is added to your project, containing library and include directory paths. Link against this like any other library.

With makefiles and pkg-config on Unix

GLFW supports 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:

If you are using the shared version of the GLFW library, omit the —static flag.

You can also use the glfw3.pc file without installing it first, by using the PKG_CONFIG_PATH environment variable.

The dependencies do not include OpenGL, as GLFW loads any OpenGL, OpenGL ES or Vulkan libraries it needs at runtime. If your application calls OpenGL directly, instead of using a modern extension loader library, you should add the gl pkg-config package.

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 and IOKit frameworks to the project as dependencies. They can all be found in /System/Library/Frameworks .

With command-line on macOS

It is recommended that you use pkg-config 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:

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.

Note Your machine may have libGL.*.dylib style OpenGL library, but that is for the X Window System and will not work with the macOS native version of GLFW.

Last update on Wed Sep 16 2020 for GLFW 3.3.3