Platformer in OpenGL
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

347 lines
14 KiB

5 years ago
  1. /*!
  2. @page build_guide Building applications
  3. @tableofcontents
  4. This is about compiling and linking applications that use GLFW. For information on
  5. how to write such applications, start with the
  6. [introductory tutorial](@ref quick_guide). For information on how to compile
  7. the GLFW library itself, see @ref compile_guide.
  8. This is not a tutorial on compilation or linking. It assumes basic
  9. understanding of how to compile and link a C program as well as how to use the
  10. specific compiler of your chosen development environment. The compilation
  11. and linking process should be explained in your C programming material and in
  12. the documentation for your development environment.
  13. @section build_include Including the GLFW header file
  14. In the source files of your application where you use OpenGL or GLFW, you should
  15. include the GLFW header file, i.e.:
  16. @code
  17. #include <GLFW/glfw3.h>
  18. @endcode
  19. The GLFW header declares the GLFW API and by default also includes the OpenGL
  20. header of your development environment, which in turn defines all the constants,
  21. types and function prototypes of the OpenGL API.
  22. The GLFW header also defines everything necessary for your OpenGL header to
  23. function. For example, under Windows you are normally required to include
  24. `windows.h` before the OpenGL header, which would pollute your code namespace
  25. with the entire Win32 API.
  26. Instead, the GLFW header takes care of this for you, not by including
  27. `windows.h`, but by duplicating only the very few necessary parts of it. It
  28. does this only when needed, so if `windows.h` _is_ included, the GLFW header
  29. does not try to redefine those symbols. The reverse is not true, i.e.
  30. `windows.h` cannot cope if any of its symbols have already been defined.
  31. In other words:
  32. - Do _not_ include the OpenGL headers yourself, as GLFW does this for you
  33. - Do _not_ include `windows.h` or other platform-specific headers unless you
  34. plan on using those APIs directly
  35. - If you _do_ need to include such headers, do it _before_ including
  36. the GLFW header and it will handle this
  37. If you are using an OpenGL extension loading library such as
  38. [glad](https://github.com/Dav1dde/glad), the extension loader header should
  39. either be included _before_ the GLFW one, or the `GLFW_INCLUDE_NONE` macro
  40. (described below) should be defined.
  41. @subsection build_macros GLFW header option macros
  42. These macros may be defined before the inclusion of the GLFW header and affect
  43. its behavior.
  44. `GLFW_DLL` is required on Windows when using the GLFW DLL, to tell the compiler
  45. that the GLFW functions are defined in a DLL.
  46. The following macros control which OpenGL or OpenGL ES API header is included.
  47. Only one of these may be defined at a time.
  48. `GLFW_INCLUDE_GLCOREARB` makes the GLFW header include the modern
  49. `GL/glcorearb.h` header (`OpenGL/gl3.h` on OS X) instead of the regular OpenGL
  50. header.
  51. `GLFW_INCLUDE_ES1` makes the GLFW header include the OpenGL ES 1.x `GLES/gl.h`
  52. header instead of the regular OpenGL header.
  53. `GLFW_INCLUDE_ES2` makes the GLFW header include the OpenGL ES 2.0 `GLES2/gl2.h`
  54. header instead of the regular OpenGL header.
  55. `GLFW_INCLUDE_ES3` makes the GLFW header include the OpenGL ES 3.0 `GLES3/gl3.h`
  56. header instead of the regular OpenGL header.
  57. `GLFW_INCLUDE_ES31` makes the GLFW header include the OpenGL ES 3.1 `GLES3/gl31.h`
  58. header instead of the regular OpenGL header.
  59. `GLFW_INCLUDE_VULKAN` makes the GLFW header include the Vulkan `vulkan/vulkan.h`
  60. header instead of the regular OpenGL header.
  61. `GLFW_INCLUDE_NONE` makes the GLFW header not include any OpenGL or OpenGL ES API
  62. header. This is useful in combination with an extension loading library.
  63. If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h`
  64. header (`OpenGL/gl.h` on OS X) is included.
  65. The following macros control the inclusion of additional API headers. Any
  66. number of these may be defined simultaneously, and/or together with one of the
  67. above macros.
  68. `GLFW_INCLUDE_GLEXT` makes the GLFW header include the appropriate extension
  69. header for the OpenGL or OpenGL ES header selected above after and in addition
  70. to that header.
  71. `GLFW_INCLUDE_GLU` makes the header include the GLU header in addition to the
  72. header selected above. This should only be used with the standard OpenGL header
  73. and only for compatibility with legacy code. GLU has been deprecated and should
  74. not be used in new code.
  75. @note GLFW does not provide any of the API headers mentioned above. They must
  76. be provided by your development environment or your OpenGL, OpenGL ES or Vulkan
  77. SDK.
  78. @note None of these macros may be defined during the compilation of GLFW itself.
  79. If your build includes GLFW and you define any these in your build files, make
  80. sure they are not applied to the GLFW sources.
  81. @section build_link Link with the right libraries
  82. GLFW is essentially a wrapper of various platform-specific APIs and therefore
  83. needs to link against many different system libraries. If you are using GLFW as
  84. a shared library / dynamic library / DLL then it takes care of these links.
  85. However, if you are using GLFW as a static library then your executable will
  86. need to link against these libraries.
  87. On Windows and OS X, the list of system libraries is static and can be
  88. hard-coded into your build environment. See the section for your development
  89. environment below. On Linux and other Unix-like operating systems, the list
  90. varies but can be retrieved in various ways as described below.
  91. A good general introduction to linking is
  92. [Beginner's Guide to Linkers](http://www.lurklurk.org/linkers/linkers.html) by
  93. David Drysdale.
  94. @subsection build_link_win32 With MinGW or Visual C++ on Windows
  95. The static version of the GLFW library is named `glfw3`. When using this
  96. version, it is also necessary to link with some libraries that GLFW uses.
  97. When linking an application under Windows that uses the static version of GLFW,
  98. you must link with `opengl32`. On some versions of MinGW, you must also
  99. explicitly link with `gdi32`, while other versions of MinGW include it in the
  100. set of default libraries along with other dependencies like `user32` and
  101. `kernel32`. If you are using GLU, you must also link with `glu32`.
  102. The link library for the GLFW DLL is named `glfw3dll`. When compiling an
  103. application that uses the DLL version of GLFW, you need to define the `GLFW_DLL`
  104. macro _before_ any inclusion of the GLFW header. This can be done either with
  105. a compiler switch or by defining it in your source code.
  106. An application using the GLFW DLL does not need to link against any of its
  107. dependencies, but you still have to link against `opengl32` if your application
  108. uses OpenGL and `glu32` if it uses GLU.
  109. @subsection build_link_cmake_source With CMake and GLFW source
  110. This section is about using CMake to compile and link GLFW along with your
  111. application. If you want to use an installed binary instead, see @ref
  112. build_link_cmake_package.
  113. With just a few changes to your `CMakeLists.txt` you can have the GLFW source
  114. tree built along with your application.
  115. When including GLFW as part of your build, you probably don't want to build the
  116. GLFW tests, examples and documentation. To disable these, set the corresponding
  117. cache variables before adding the GLFW source tree.
  118. @code
  119. set(GLFW_BUILD_DOCS OFF CACHE BOOL "" FORCE)
  120. set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE)
  121. set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
  122. @endcode
  123. Then add the root directory of the GLFW source tree to your project. This
  124. will add the `glfw` target and the necessary cache variables to your project.
  125. @code{.cmake}
  126. add_subdirectory(path/to/glfw)
  127. @endcode
  128. Once GLFW has been added to the project, link against it with the `glfw` target.
  129. This adds all link-time dependencies of GLFW as it is currently configured,
  130. the include directory for the GLFW header and, when applicable, the
  131. [GLFW_DLL](@ref build_macros) macro.
  132. @code{.cmake}
  133. target_link_libraries(myapp glfw)
  134. @endcode
  135. Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
  136. OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
  137. If your application calls OpenGL directly, instead of using a modern
  138. [extension loader library](@ref context_glext_auto) you can find it by requiring
  139. the OpenGL package.
  140. @code{.cmake}
  141. find_package(OpenGL REQUIRED)
  142. @endcode
  143. If OpenGL is found, the `OPENGL_FOUND` variable is true and the
  144. `OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
  145. @code{.cmake}
  146. target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
  147. target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
  148. @endcode
  149. The OpenGL CMake package also looks for GLU. If GLU is found, the
  150. `OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
  151. `OPENGL_glu_LIBRARY` cache variables can be used.
  152. @code{.cmake}
  153. target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
  154. @endcode
  155. @note GLU has been deprecated and should not be used in new code, but some
  156. legacy code requires it.
  157. @subsection build_link_cmake_package With CMake and installed GLFW binaries
  158. This section is about using CMake to link GLFW after it has been built and
  159. installed. If you want to build it along with your application instead, see
  160. @ref build_link_cmake_source.
  161. With just a few changes to your `CMakeLists.txt`, you can locate the package and
  162. target files generated when GLFW is installed.
  163. @code{.cmake}
  164. find_package(glfw3 3.2 REQUIRED)
  165. @endcode
  166. Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
  167. OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
  168. If your application calls OpenGL directly, instead of using a modern
  169. [extension loader library](@ref context_glext_auto) you can find it by requiring
  170. the OpenGL package.
  171. @code{.cmake}
  172. find_package(OpenGL REQUIRED)
  173. @endcode
  174. If OpenGL is found, the `OPENGL_FOUND` variable is true and the
  175. `OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
  176. @code{.cmake}
  177. target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
  178. target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
  179. @endcode
  180. The OpenGL CMake package also looks for GLU. If GLU is found, the
  181. `OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
  182. `OPENGL_glu_LIBRARY` cache variables can be used.
  183. @code{.cmake}
  184. target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
  185. @endcode
  186. @note GLU has been deprecated and should not be used in new code, but some
  187. legacy code requires it.
  188. @subsection build_link_pkgconfig With makefiles and pkg-config on Unix
  189. GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/),
  190. and the `glfw3.pc` pkg-config file is generated when the GLFW library is built
  191. and is installed along with it. A pkg-config file describes all necessary
  192. compile-time and link-time flags and dependencies needed to use a library. When
  193. they are updated or if they differ between systems, you will get the correct
  194. ones automatically.
  195. A typical compile and link command-line when using the static version of the
  196. GLFW library may look like this:
  197. @code{.sh}
  198. cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
  199. @endcode
  200. If you are using the shared version of the GLFW library, simply omit the
  201. `--static` flag.
  202. @code{.sh}
  203. cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
  204. @endcode
  205. You can also use the `glfw3.pc` file without installing it first, by using the
  206. `PKG_CONFIG_PATH` environment variable.
  207. @code{.sh}
  208. env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
  209. @endcode
  210. The dependencies do not include OpenGL or GLU, as GLFW loads any OpenGL, OpenGL
  211. ES or Vulkan libraries it needs at runtime and does not use GLU. On OS X, GLU
  212. is built into the OpenGL framework, so if you need GLU you don't need to do
  213. anything extra. If you need GLU and are using Linux or BSD, you should add the
  214. `glu` pkg-config package.
  215. @code{.sh}
  216. cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`
  217. @endcode
  218. @note GLU has been deprecated and should not be used in new code, but some
  219. legacy code requires it.
  220. If you are using the static version of the GLFW library, make sure you don't
  221. link statically against GLU.
  222. @code{.sh}
  223. cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --static --libs glfw3` `pkg-config --libs glu`
  224. @endcode
  225. @subsection build_link_xcode With Xcode on OS X
  226. If you are using the dynamic library version of GLFW, simply add it to the
  227. project dependencies.
  228. If you are using the static library version of GLFW, add it and the Cocoa,
  229. OpenGL, IOKit and CoreVideo frameworks to the project as dependencies. They can
  230. all be found in `/System/Library/Frameworks`.
  231. @subsection build_link_osx With command-line on OS X
  232. It is recommended that you use [pkg-config](@ref build_link_pkgconfig) when
  233. building from the command line on OS X. That way you will get any new
  234. dependencies added automatically. If you still wish to build manually, you need
  235. to add the required frameworks and libraries to your command-line yourself using
  236. the `-l` and `-framework` switches.
  237. If you are using the dynamic GLFW library, which is named `libglfw.3.dylib`, do:
  238. @code{.sh}
  239. cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo
  240. @endcode
  241. If you are using the static library, named `libglfw3.a`, substitute `-lglfw3`
  242. for `-lglfw`.
  243. Note that you do not add the `.framework` extension to a framework when linking
  244. against it from the command-line.
  245. The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing
  246. special to do when using GLU. Also note that even though your machine may have
  247. `libGL`-style OpenGL libraries, they are for use with the X Window System and
  248. will _not_ work with the OS X native version of GLFW.
  249. */