mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-21 20:44:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improved build guide slightly

Browse Source 
This was adapted to 3.3-stable from
b864e4baeb.
This commit is contained in:
Camilla Löwy 2024-02-20 19:23:52 +01:00
parent 3af1a1f514
commit 07efe9068e
1 changed files with 94 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
docs/build.dox
View File

@ -160,20 +160,94 @@ A good general introduction to linking is
David Drysdale.
@subsection build_link_win32 With MinGW or Visual C++ on Windows
@subsection build_link_win32 With Visual C++ and GLFW binaries
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.
If you are using a downloaded
[binary archive](https://www.glfw.org/download.html), first make sure you have
the archive matching the architecture you are building for (32-bit or 64-bit),
or you will get link errors. Also make sure you are using the binaries for your
version of Visual C++ or you may get other link errors.
When using MinGW to link an application with the static version of GLFW, you
must also explicitly link with `gdi32`. Other toolchains including MinGW-w64
include it in the set of default libraries along with other dependencies like
`user32` and `kernel32`.
There are two version of the static GLFW library in the binary archive, because
it needs to use the same base run-time library variant as the rest of your
executable.
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 @ref
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.
One is named `glfw3.lib` and is for projects with the _Runtime Library_ project
option set to _Multi-threaded DLL_ or _Multi-threaded Debug DLL_. The other is
named `glfw3_mt.lib` and is for projects with _Runtime Library_ set to
_Multi-threaded_ or _Multi-threaded Debug_. To use the static GLFW library you
will need to add `path/to/glfw3.lib` or `path/to/glfw3_mt.lib` to the
_Additional Dependencies_ project option.
If you compiled a GLFW static library yourself then there will only be one,
named `glfw3.lib`, and you have to make sure the run-time library variant
matches.
The DLL version of the GLFW library is named `glfw3.dll`, but you will be
linking against the `glfw3dll.lib` link library. To use the DLL you will need
to add `path/to/glfw3dll.lib` to the _Additional Dependencies_ project option.
All of its dependencies are already listed there by default, but when building
with the DLL version of GLFW, you also need to define the @ref GLFW_DLL. This
can be done either in the _Preprocessor Definitions_ project option or by
defining it in your source code before including the GLFW header.
@code
#define GLFW_DLL
#include <GLFW/glfw3.h>
@endcode
All link-time dependencies for GLFW are already listed in the _Additional
Dependencies_ option by default.
@subsection build_link_mingw With MinGW-w64 and GLFW binaries
This is intended for building a program from the command-line or by writing
a makefile, on Windows with [MinGW-w64](https://www.mingw-w64.org/) and GLFW
binaries. These can be from a downloaded and extracted
[binary archive](https://www.glfw.org/download.html) or by compiling GLFW
yourself. The paths below assume a binary archive is used.
If you are using a downloaded binary archive, first make sure you have the
archive matching the architecture you are building for (32-bit or 64-bit) or you
will get link errors.
Note that the order of source files and libraries matter for GCC. Dependencies
must be listed after the files that depend on them. Any source files that
depend on GLFW must be listed before the GLFW library. GLFW in turn depends on
`gdi32` and must be listed before it.
If you are using the static version of the GLFW library, which is named
`libglfw3.a`, do:
@code{.sh}
gcc -o myprog myprog.c -I path/to/glfw/include path/to/glfw/lib-mingw-w64/libglfw3.a -lgdi32
@endcode
If you are using the DLL version of the GLFW library, which is named
`glfw3.dll`, you will need to use the `libglfw3dll.a` link library.
@code{.sh}
gcc -o myprog myprog.c -I path/to/glfw/include path/to/glfw/lib-mingw-w64/libglfw3dll.a -lgdi32
@endcode
The resulting executable will need to find `glfw3.dll` to run, typically by
keeping both files in the same directory.
When you are building with the DLL version of GLFW, you will also need to define
the @ref GLFW_DLL macro. This can be done in your source files, as long as it
done before including the GLFW header:
@code
#define GLFW_DLL
#include <GLFW/glfw3.h>
@endcode
It can also be done on the command-line:
@code{.sh}
gcc -o myprog myprog.c -D GLFW_DLL -I path/to/glfw/include path/to/glfw/lib-mingw-w64/libglfw3dll.a -lgdi32
@endcode
@subsection build_link_cmake_source With CMake and GLFW source
@ -271,7 +345,10 @@ target_link_libraries(myapp OpenGL::GL)
@endcode
@subsection build_link_pkgconfig With makefiles and pkg-config on Unix
@subsection build_link_pkgconfig With pkg-config and GLFW binaries on Unix
This is intended for building a program from the command-line or by writing
a makefile, on macOS or any Unix-like system like Linux, FreeBSD and Cygwin.
GLFW supports [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/),
and the `glfw3.pc` pkg-config file is generated when the GLFW library is built
@ -322,13 +399,13 @@ OpenGL and IOKit frameworks to the project as dependencies. They can all be
found in `/System/Library/Frameworks`.
@subsection build_link_osx With command-line on macOS
@subsection build_link_osx With command-line or makefile on macOS
It is recommended that you use [pkg-config](@ref build_link_pkgconfig) when
building from the command line on macOS. 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.
using installed GLFW binaries from the command line on macOS. 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: