GLFW: Building applications

GLFW

- Documentation
- Download
- Media
- Community

Building applications

This is about compiling and linking applications that use GLFW. For information on how to write such applications, start with the introductory tutorial. For information on how to compile the GLFW library itself, see Compiling GLFW.

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.

# Including the GLFW header file

In the source files of your application where you use OpenGL or GLFW, you should include the GLFW header file, i.e.:

#include <GLFW/glfw3.h>

The GLFW header declares the GLFW API and by default also includes the OpenGL header of your development environment, which in turn defines all the constants, types and function prototypes of the OpenGL API.

The GLFW header also defines everything necessary for your OpenGL header to function. For example, under Windows you are normally required to include `windows.h` before the OpenGL header, which would pollute your code namespace with the entire Win32 API.

Instead, the GLFW header takes care of this for you, not by including `windows.h`, but by duplicating only the very few necessary parts of it. 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, the extension loader header should either be included before the GLFW one, or the `GLFW_INCLUDE_NONE` macro (described below) should be defined.

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

`GLFW_INCLUDE_GLCOREARB` makes the GLFW 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 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_VULKAN` makes the GLFW header include the Vulkan `vulkan/vulkan.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 OS X) 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.

`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
  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.
  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 OS X, 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 linking an application 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 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.

An application using the GLFW DLL does not need to link against any of its dependencies, but you still have to link against `opengl32` if your application uses OpenGL and `glu32` if it uses GLU.

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

set(GLFW_BUILD_DOCS OFF CACHE BOOL "" FORCE)
set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE)
set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)

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.

add_subdirectory(path/to/glfw)

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

target_link_libraries(myapp glfw)

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 you can find it by requiring the OpenGL package.

find_package(OpenGL REQUIRED)

If OpenGL is found, the `OPENGL_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.

target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
target_link_libraries(myapp ${OPENGL_gl_LIBRARY})

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.

target_link_libraries(myapp ${OPENGL_glu_LIBRARY})

Note
  GLU has been deprecated and should not be used in new code, but some legacy code requires it.

## 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 just a few changes to your `CMakeLists.txt`, you can locate the package and target files generated when GLFW is installed.

find_package(glfw3 3.2 REQUIRED)

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 you can find it by requiring the OpenGL package.

find_package(OpenGL REQUIRED)

If OpenGL is found, the `OPENGL_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.

target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
target_link_libraries(myapp ${OPENGL_gl_LIBRARY})

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.

target_link_libraries(myapp ${OPENGL_glu_LIBRARY})

Note
  GLU has been deprecated and should not be used in new code, but some legacy code requires it.

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

cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`

If you are using the shared version of the GLFW library, simply omit the `--static` flag.

cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`

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

env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`

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 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 the `glu` pkg-config package.

cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`

Note
  GLU has been deprecated and should not be used in new code, but some legacy code requires it.

If you are using the static version of the GLFW library, make sure you don't link statically against GLU.

cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --static --libs glfw3` `pkg-config --libs glu`

## 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. They can all be found in `/System/Library/Frameworks`.

## With command-line on OS X

It is recommended that you use pkg-config when building from the command line on OS X. 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:

cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo

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