docs/build.dox

/*!

@page build Building applications

@tableofcontents

This is about compiling and linking applications that use GLFW.  For information on
how to write such applications, start with the [introductory tutorial](@ref quick).
For information on how to compile the GLFW library itself, see the @ref compile
guide.

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.

@section build_include 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.:

@code
#include <GLFW/glfw3.h>
@endcode

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](https://github.com/Dav1dde/glad), the extension loader header should
either be included _before_ the GLFW one, or the `GLFW_INCLUDE_NONE` macro
(described below) should be defined.


@subsection build_macros 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.

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

`GLFW_INCLUDE_GLU` makes the header include the GLU header _in addition to_ the
header selected above.  This should only be used 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 or OpenGL ES SDK.


@section build_link 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](http://www.lurklurk.org/linkers/linkers.html) by
David Drysdale.


@subsection build_link_win32 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.


@subsection build_link_cmake_source With CMake and GLFW source

With just a few changes to your `CMakeLists.txt` you can have the GLFW source
tree built along with your application.

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.

@code{.cmake}
add_subdirectory(path/to/glfw)
@endcode

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

@code{.cmake}
include_directories(path/to/glfw/include)
@endcode

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.

@code{.cmake}
target_link_libraries(myapp glfw ${GLFW_LIBRARIES})
@endcode

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.

@code{.cmake}
target_link_libraries(myapp glfw ${OPENGL_glu_LIBRARY} ${GLFW_LIBRARIES})
@endcode


@subsection build_link_cmake_pkgconfig 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.

@code{.cmake}
find_package(PkgConfig REQUIRED)
@endcode

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

@code{.cmake}
pkg_search_module(GLFW REQUIRED glfw3)
@endcode

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.

@code{.cmake}
include_directories(${GLFW_INCLUDE_DIRS})
@endcode

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

@code{.cmake}
target_link_libraries(simple ${GLFW_LIBRARIES})
@endcode

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

@code{.cmake}
target_link_libraries(simple ${GLFW_STATIC_LIBRARIES})
@endcode


@subsection build_link_pkgconfig With pkg-config on OS X or other Unix

GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/),
and the `glfw3.pc` pkf-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:

@code{.sh}
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
@endcode

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

@code{.sh}
cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
@endcode

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

@code{.sh}
env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
@endcode

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

@code{.sh}
cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`
@endcode

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

@code{.sh}
cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --static --libs glfw3` `pkg-config --libs glu`
@endcode


@subsection build_link_xcode 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, CoreVideo and Carbon frameworks to the project as dependencies.
They can all be found in `/System/Library/Frameworks`.

@note GLFW needs the Carbon framework only to access the current keyboard layout
via the Text Input Source Services.  This is one of the non-deprecated parts of
the Carbon API and the only way to access this information on OS X.


@subsection build_link_osx With command-line on OS X

It is recommended that you use [pkg-config](@ref build_link_pkgconfig) 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:

@code{.sh}
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo
@endcode

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.

*/