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