1/*! 2 3@page build_guide Building applications 4 5@tableofcontents 6 7This is about compiling and linking applications that use GLFW. For information on 8how to write such applications, start with the 9[introductory tutorial](@ref quick_guide). For information on how to compile 10the GLFW library itself, see @ref compile_guide. 11 12This is not a tutorial on compilation or linking. It assumes basic 13understanding of how to compile and link a C program as well as how to use the 14specific compiler of your chosen development environment. The compilation 15and linking process should be explained in your C programming material and in 16the documentation for your development environment. 17 18 19@section build_include Including the GLFW header file 20 21You should include the GLFW header in the source files where you use OpenGL or 22GLFW. 23 24@code 25#include <GLFW/glfw3.h> 26@endcode 27 28This header declares the GLFW API and by default also includes the OpenGL header 29from your development environment. See below for how to control this. 30 31The GLFW header also defines any platform-specific macros needed by your OpenGL 32header, so it can be included without needing any window system headers. 33 34For example, under Windows you are normally required to include `windows.h` 35before the OpenGL header, which would bring in the whole Win32 API. The GLFW 36header duplicates the small number of macros needed. 37 38It does this only when needed, so if `windows.h` _is_ included, the GLFW header 39does not try to redefine those symbols. The reverse is not true, i.e. 40`windows.h` cannot cope if any of its symbols have already been defined. 41 42In other words: 43 44 - Do _not_ include the OpenGL headers yourself, as GLFW does this for you 45 - Do _not_ include `windows.h` or other platform-specific headers unless you 46 plan on using those APIs directly 47 - If you _do_ need to include such headers, do it _before_ including 48 the GLFW header and it will handle this 49 50If you are using an OpenGL extension loading library such as 51[glad](https://github.com/Dav1dde/glad), the extension loader header should 52be included _before_ the GLFW one. 53 54@code 55#include <glad/gl.h> 56#include <GLFW/glfw3.h> 57@endcode 58 59Alternatively the @ref GLFW_INCLUDE_NONE macro (described below) can be used to 60prevent the GLFW header from including the OpenGL header. 61 62@code 63#define GLFW_INCLUDE_NONE 64#include <GLFW/glfw3.h> 65#include <glad/gl.h> 66@endcode 67 68 69@subsection build_macros GLFW header option macros 70 71These macros may be defined before the inclusion of the GLFW header and affect 72its behavior. 73 74@anchor GLFW_DLL 75__GLFW_DLL__ is required on Windows when using the GLFW DLL, to tell the 76compiler that the GLFW functions are defined in a DLL. 77 78The following macros control which OpenGL or OpenGL ES API header is included. 79Only one of these may be defined at a time. 80 81@note GLFW does not provide any of the API headers mentioned below. They are 82provided by your development environment or your OpenGL, OpenGL ES or Vulkan 83SDK, and most of them can be downloaded from the 84[Khronos Registry](https://www.khronos.org/registry/). 85 86@anchor GLFW_INCLUDE_GLCOREARB 87__GLFW_INCLUDE_GLCOREARB__ makes the GLFW header include the modern 88`GL/glcorearb.h` header (`OpenGL/gl3.h` on macOS) instead of the regular OpenGL 89header. 90 91@anchor GLFW_INCLUDE_ES1 92__GLFW_INCLUDE_ES1__ makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h` 93header instead of the regular OpenGL header. 94 95@anchor GLFW_INCLUDE_ES2 96__GLFW_INCLUDE_ES2__ makes the GLFW header include the OpenGL ES 2.0 97`GLES2/gl2.h` header instead of the regular OpenGL header. 98 99@anchor GLFW_INCLUDE_ES3 100__GLFW_INCLUDE_ES3__ makes the GLFW header include the OpenGL ES 3.0 101`GLES3/gl3.h` header instead of the regular OpenGL header. 102 103@anchor GLFW_INCLUDE_ES31 104__GLFW_INCLUDE_ES31__ makes the GLFW header include the OpenGL ES 3.1 105`GLES3/gl31.h` header instead of the regular OpenGL header. 106 107@anchor GLFW_INCLUDE_ES32 108__GLFW_INCLUDE_ES31__ makes the GLFW header include the OpenGL ES 3.2 109`GLES3/gl32.h` header instead of the regular OpenGL header. 110 111@anchor GLFW_INCLUDE_NONE 112__GLFW_INCLUDE_NONE__ makes the GLFW header not include any OpenGL or OpenGL ES 113API header. This is useful in combination with an extension loading library. 114 115If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h` 116header (`OpenGL/gl.h` on macOS) is included. 117 118The following macros control the inclusion of additional API headers. Any 119number of these may be defined simultaneously, and/or together with one of the 120above macros. 121 122@anchor GLFW_INCLUDE_VULKAN 123__GLFW_INCLUDE_VULKAN__ makes the GLFW header include the Vulkan 124`vulkan/vulkan.h` header in addition to any selected OpenGL or OpenGL ES header. 125 126@anchor GLFW_INCLUDE_GLEXT 127__GLFW_INCLUDE_GLEXT__ makes the GLFW header include the appropriate extension 128header for the OpenGL or OpenGL ES header selected above after and in addition 129to that header. 130 131@anchor GLFW_INCLUDE_GLU 132__GLFW_INCLUDE_GLU__ makes the header include the GLU header in addition to the 133header selected above. This should only be used with the standard OpenGL header 134and only for compatibility with legacy code. GLU has been deprecated and should 135not be used in new code. 136 137@note None of these macros may be defined during the compilation of GLFW itself. 138If your build includes GLFW and you define any these in your build files, make 139sure they are not applied to the GLFW sources. 140 141 142@section build_link Link with the right libraries 143 144GLFW is essentially a wrapper of various platform-specific APIs and therefore 145needs to link against many different system libraries. If you are using GLFW as 146a shared library / dynamic library / DLL then it takes care of these links. 147However, if you are using GLFW as a static library then your executable will 148need to link against these libraries. 149 150On Windows and macOS, the list of system libraries is static and can be 151hard-coded into your build environment. See the section for your development 152environment below. On Linux and other Unix-like operating systems, the list 153varies but can be retrieved in various ways as described below. 154 155A good general introduction to linking is 156[Beginner's Guide to Linkers](https://www.lurklurk.org/linkers/linkers.html) by 157David Drysdale. 158 159 160@subsection build_link_win32 With MinGW or Visual C++ on Windows 161 162The static version of the GLFW library is named `glfw3`. When using this 163version, it is also necessary to link with some libraries that GLFW uses. 164 165When using MinGW to link an application with the static version of GLFW, you 166must also explicitly link with `gdi32`. Other toolchains including MinGW-w64 167include it in the set of default libraries along with other dependencies like 168`user32` and `kernel32`. 169 170The link library for the GLFW DLL is named `glfw3dll`. When compiling an 171application that uses the DLL version of GLFW, you need to define the @ref 172GLFW_DLL macro _before_ any inclusion of the GLFW header. This can be done 173either with a compiler switch or by defining it in your source code. 174 175 176@subsection build_link_cmake_source With CMake and GLFW source 177 178This section is about using CMake to compile and link GLFW along with your 179application. If you want to use an installed binary instead, see @ref 180build_link_cmake_package. 181 182With a few changes to your `CMakeLists.txt` you can have the GLFW source tree 183built along with your application. 184 185When including GLFW as part of your build, you probably don't want to build the 186GLFW tests, examples and documentation. To disable these, set the corresponding 187cache variables before adding the GLFW source tree. 188 189@code 190set(GLFW_BUILD_DOCS OFF CACHE BOOL "" FORCE) 191set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE) 192set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE) 193@endcode 194 195Add the root directory of the GLFW source tree to your project. This will add 196the `glfw` target to your project. 197 198@code{.cmake} 199add_subdirectory(path/to/glfw) 200@endcode 201 202Once GLFW has been added, link your application against the `glfw` target. 203This adds the GLFW library and its link-time dependencies as it is currently 204configured, the include directory for the GLFW header and, when applicable, the 205@ref GLFW_DLL macro. 206 207@code{.cmake} 208target_link_libraries(myapp glfw) 209@endcode 210 211Note that the `glfw` target does not depend on OpenGL, as GLFW loads any OpenGL, 212OpenGL ES or Vulkan libraries it needs at runtime. If your application calls 213OpenGL directly, instead of using a modern 214[extension loader library](@ref context_glext_auto), use the OpenGL CMake 215package. 216 217@code{.cmake} 218find_package(OpenGL REQUIRED) 219@endcode 220 221If OpenGL is found, the `OpenGL::GL` target is added to your project, containing 222library and include directory paths. Link against this like above. 223 224@code{.cmake} 225target_link_libraries(myapp OpenGL::GL) 226@endcode 227 228 229@subsection build_link_cmake_package With CMake and installed GLFW binaries 230 231This section is about using CMake to link GLFW after it has been built and 232installed. If you want to build it along with your application instead, see 233@ref build_link_cmake_source. 234 235With a few changes to your `CMakeLists.txt` you can locate the package and 236target files generated when GLFW is installed. 237 238@code{.cmake} 239find_package(glfw3 3.3 REQUIRED) 240@endcode 241 242Once GLFW has been added to the project, link against it with the `glfw` target. 243This adds the GLFW library and its link-time dependencies, the include directory 244for the GLFW header and, when applicable, the @ref GLFW_DLL macro. 245 246@code{.cmake} 247target_link_libraries(myapp glfw) 248@endcode 249 250Note that the `glfw` target does not depend on OpenGL, as GLFW loads any OpenGL, 251OpenGL ES or Vulkan libraries it needs at runtime. If your application calls 252OpenGL directly, instead of using a modern 253[extension loader library](@ref context_glext_auto), use the OpenGL CMake 254package. 255 256@code{.cmake} 257find_package(OpenGL REQUIRED) 258@endcode 259 260If OpenGL is found, the `OpenGL::GL` target is added to your project, containing 261library and include directory paths. Link against this like above. 262 263@code{.cmake} 264target_link_libraries(myapp OpenGL::GL) 265@endcode 266 267 268@subsection build_link_pkgconfig With makefiles and pkg-config on Unix 269 270GLFW supports [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/), 271and the `glfw3.pc` pkg-config file is generated when the GLFW library is built 272and is installed along with it. A pkg-config file describes all necessary 273compile-time and link-time flags and dependencies needed to use a library. When 274they are updated or if they differ between systems, you will get the correct 275ones automatically. 276 277A typical compile and link command-line when using the static version of the 278GLFW library may look like this: 279 280@code{.sh} 281cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --static --libs glfw3) 282@endcode 283 284If you are using the shared version of the GLFW library, omit the `--static` 285flag. 286 287@code{.sh} 288cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --libs glfw3) 289@endcode 290 291You can also use the `glfw3.pc` file without installing it first, by using the 292`PKG_CONFIG_PATH` environment variable. 293 294@code{.sh} 295env PKG_CONFIG_PATH=path/to/glfw/src cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --libs glfw3) 296@endcode 297 298The dependencies do not include OpenGL, as GLFW loads any OpenGL, OpenGL ES or 299Vulkan libraries it needs at runtime. If your application calls OpenGL 300directly, instead of using a modern 301[extension loader library](@ref context_glext_auto), you should add the `gl` 302pkg-config package. 303 304@code{.sh} 305cc $(pkg-config --cflags glfw3 gl) -o myprog myprog.c $(pkg-config --libs glfw3 gl) 306@endcode 307 308 309@subsection build_link_xcode With Xcode on macOS 310 311If you are using the dynamic library version of GLFW, add it to the project 312dependencies. 313 314If you are using the static library version of GLFW, add it and the Cocoa, 315OpenGL and IOKit frameworks to the project as dependencies. They can all be 316found in `/System/Library/Frameworks`. 317 318 319@subsection build_link_osx With command-line on macOS 320 321It is recommended that you use [pkg-config](@ref build_link_pkgconfig) when 322building from the command line on macOS. That way you will get any new 323dependencies added automatically. If you still wish to build manually, you need 324to add the required frameworks and libraries to your command-line yourself using 325the `-l` and `-framework` switches. 326 327If you are using the dynamic GLFW library, which is named `libglfw.3.dylib`, do: 328 329@code{.sh} 330cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit 331@endcode 332 333If you are using the static library, named `libglfw3.a`, substitute `-lglfw3` 334for `-lglfw`. 335 336Note that you do not add the `.framework` extension to a framework when linking 337against it from the command-line. 338 339@note Your machine may have `libGL.*.dylib` style OpenGL library, but that is 340for the X Window System and will not work with the macOS native version of GLFW. 341 342*/ 343