mirror of
https://github.com/glfw/glfw.git
synced 2024-11-10 00:51:47 +00:00
parent
b6f7ead3c5
commit
3b95970482
330
docs/compile.dox
330
docs/compile.dox
@ -10,164 +10,156 @@ build applications that use GLFW, see @ref build_guide.
|
||||
|
||||
@section compile_cmake Using CMake
|
||||
|
||||
@note GLFW behaves like most other libraries that use CMake so this guide mostly
|
||||
describes the basic configure/generate/compile sequence. If you are already
|
||||
familiar with this from other projects, you may want to focus on the @ref
|
||||
compile_deps and @ref compile_options sections for GLFW-specific information.
|
||||
|
||||
GLFW uses [CMake](https://cmake.org/) to generate project files or makefiles
|
||||
for a particular development environment. If you are on a Unix-like system such
|
||||
as Linux or FreeBSD or have a package system like Fink, MacPorts, Cygwin or
|
||||
Homebrew, you can install its CMake package. If not, you can download
|
||||
installers for Windows and macOS from the
|
||||
[CMake website](https://cmake.org/).
|
||||
for your chosen development environment. To compile GLFW, first generate these
|
||||
files with CMake and then use them to compile the GLFW library.
|
||||
|
||||
@note CMake only generates project files or makefiles. It does not compile the
|
||||
actual GLFW library. To compile GLFW, first generate these files for your
|
||||
chosen development environment and then use them to compile the actual GLFW
|
||||
library.
|
||||
If you are on Windows and macOS you can
|
||||
[download CMake](https://cmake.org/download/) from their site.
|
||||
|
||||
If you are on a Unix-like system such as Linux, FreeBSD or Cygwin or have
|
||||
a package system like Fink, MacPorts or Homebrew, you can install its CMake
|
||||
package.
|
||||
|
||||
CMake is a complex tool and this guide will only show a few of the possible ways
|
||||
to set up and compile GLFW. The CMake project has their own much more detailed
|
||||
[CMake user guide](https://cmake.org/cmake/help/latest/guide/user-interaction/)
|
||||
that includes everything in this guide not specific to GLFW. It may be a useful
|
||||
companion to this one.
|
||||
|
||||
|
||||
@subsection compile_deps Dependencies
|
||||
@subsection compile_deps Installing dependencies
|
||||
|
||||
Once you have installed CMake, make sure that all other dependencies are
|
||||
available. On some platforms, GLFW needs a few additional packages to be
|
||||
installed. See the section for your chosen platform and development environment
|
||||
below.
|
||||
The C/C++ development environments in Visual Studio, Xcode and MinGW come with
|
||||
all necessary dependencies for compiling GLFW, but on Unix-like systems like
|
||||
Linux and FreeBSD you will need a few extra packages.
|
||||
|
||||
|
||||
@subsubsection compile_deps_msvc Dependencies for Visual C++ on Windows
|
||||
@subsubsection compile_deps_x11 Dependencies for X11 on Unix-like systems
|
||||
|
||||
The Windows SDK bundled with Visual C++ already contains all the necessary
|
||||
headers, link libraries and tools except for CMake. Move on to @ref
|
||||
compile_generate.
|
||||
To compile GLFW for X11, you need to have the X11 development packages
|
||||
installed. They are not needed to build or run programs that use GLFW.
|
||||
|
||||
|
||||
@subsubsection compile_deps_mingw Dependencies for MinGW or MinGW-w64 on Windows
|
||||
|
||||
Both the MinGW and the MinGW-w64 packages already contain all the necessary
|
||||
headers, link libraries and tools except for CMake. Move on to @ref
|
||||
compile_generate.
|
||||
|
||||
|
||||
@subsubsection compile_deps_mingw_cross Dependencies for MinGW or MinGW-w64 cross-compilation
|
||||
|
||||
Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages. For
|
||||
example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages
|
||||
for 32- and 64-bit version of MinGW-w64, while Debian GNU/Linux and derivatives
|
||||
like Ubuntu have the `mingw-w64` package for both.
|
||||
|
||||
GLFW has CMake toolchain files in the `CMake/` directory that set up
|
||||
cross-compilation of Windows binaries. To use these files you add an option
|
||||
when running `cmake` to generate the project files or makefiles:
|
||||
On Debian and derivates like Ubuntu the `xorg-dev` meta-package pulls in the
|
||||
development packages for all of X11.
|
||||
|
||||
@code{.sh}
|
||||
cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> .
|
||||
sudo apt install xorg-dev
|
||||
@endcode
|
||||
|
||||
The exact toolchain file to use depends on the prefix used by the MinGW or
|
||||
MinGW-w64 binaries on your system. You can usually see this in the /usr
|
||||
directory. For example, both the Debian/Ubuntu and Cygwin MinGW-w64 packages
|
||||
have `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct
|
||||
invocation would be:
|
||||
On FreeBSD the X11 headers are installed along the end-user X11 packages, so if
|
||||
you have an X server running you should have the headers as well. If not,
|
||||
install the `xorgproto` package.
|
||||
|
||||
@code{.sh}
|
||||
cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake .
|
||||
pkg install xorgproto
|
||||
@endcode
|
||||
|
||||
For more details see the article
|
||||
[CMake Cross Compiling](https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/CrossCompiling) on
|
||||
the CMake wiki.
|
||||
On Cygwin the `xorgproto` package in the Devel section of the GUI installer will
|
||||
install the headers and other development related files for all of X11.
|
||||
|
||||
Once you have this set up, move on to @ref compile_generate.
|
||||
Once you have the required depdendencies, move on to @ref compile_generate.
|
||||
|
||||
|
||||
@subsubsection compile_deps_xcode Dependencies for Xcode on macOS
|
||||
@subsubsection compile_deps_wayland Dependencies for Wayland on Unix-like systems
|
||||
|
||||
Xcode comes with all necessary tools except for CMake. The required headers
|
||||
and libraries are included in the core macOS frameworks. Xcode can be
|
||||
downloaded from the Mac App Store or from the ADC Member Center.
|
||||
To compile GLFW for Wayland, you need to have the Wayland and xkbcommon
|
||||
development packages installed. They are not needed to build or run programs
|
||||
that use GLFW.
|
||||
|
||||
Once you have Xcode installed, move on to @ref compile_generate.
|
||||
On Debian and derivates like Ubuntu you will need the `libwayland-dev`,
|
||||
`libxkbcommon-dev` and `wayland-protocols` packages.
|
||||
|
||||
@code{.sh}
|
||||
sudo apt install libwayland-dev libxkbcommon-dev wayland-protocols
|
||||
@endcode
|
||||
|
||||
@subsubsection compile_deps_x11 Dependencies for Linux and X11
|
||||
On FreeBSD you will need the `wayland`, `libxkbcommon` and `wayland-protocols`
|
||||
packages.
|
||||
|
||||
To compile GLFW for X11, you need to have the X11 packages installed, as well as
|
||||
the basic development tools like GCC and make. For example, on Ubuntu and other
|
||||
distributions based on Debian GNU/Linux, you need to install the `xorg-dev`
|
||||
package, which pulls in all X.org header packages.
|
||||
@code{.sh}
|
||||
pkg install wayland libxkbcommon wayland-protocols
|
||||
@endcode
|
||||
|
||||
Once you have installed the necessary packages, move on to @ref
|
||||
compile_generate.
|
||||
|
||||
|
||||
@subsubsection compile_deps_wayland Dependencies for Linux and Wayland
|
||||
|
||||
To compile GLFW for Wayland, you need to have the Wayland packages installed,
|
||||
as well as the basic development tools like GCC and make. For example, on
|
||||
Ubuntu and other distributions based on Debian GNU/Linux, you need to install
|
||||
the `libwayland-dev` package, which contains all Wayland headers and pulls in
|
||||
wayland-scanner, as well as the `wayland-protocols` package.
|
||||
|
||||
Once you have installed the necessary packages, move on to @ref
|
||||
compile_generate.
|
||||
|
||||
|
||||
@subsubsection compile_deps_osmesa Dependencies for Linux and OSMesa
|
||||
|
||||
To compile GLFW for OSMesa, you need to install the OSMesa library and header
|
||||
packages. For example, on Ubuntu and other distributions based on Debian
|
||||
GNU/Linux, you need to install the `libosmesa6-dev` package. The OSMesa library
|
||||
is required at runtime for context creation and is loaded on demand.
|
||||
|
||||
Once you have installed the necessary packages, move on to @ref
|
||||
compile_generate.
|
||||
Once you have the required depdendencies, move on to @ref compile_generate.
|
||||
|
||||
|
||||
@subsection compile_generate Generating build files with CMake
|
||||
|
||||
Once you have all necessary dependencies it is time to generate the project
|
||||
files or makefiles for your development environment. CMake needs to know two
|
||||
paths for this: the path to the _root_ directory of the GLFW source tree (i.e.
|
||||
_not_ the `src` subdirectory) and the target path for the generated files and
|
||||
compiled binaries. If these are the same, it is called an in-tree build,
|
||||
otherwise it is called an out-of-tree build.
|
||||
files or makefiles for your development environment. CMake needs two paths for
|
||||
this:
|
||||
|
||||
One of several advantages of out-of-tree builds is that you can generate files
|
||||
and compile for different development environments using a single source tree.
|
||||
- the path to the root directory of the GLFW source tree (not its `src`
|
||||
subdirectory)
|
||||
- the path to the directory where the generated build files and compiled
|
||||
binaries will be placed
|
||||
|
||||
@note This section is about generating the project files or makefiles necessary
|
||||
to compile the GLFW library, not about compiling the actual library.
|
||||
If these are the same, it is called an in-tree build, otherwise it is called an
|
||||
out-of-tree build.
|
||||
|
||||
Out-of-tree builds are recommended as they avoid cluttering up the source tree.
|
||||
They also allow you to have several build directories for different
|
||||
configurations all using the same source tree.
|
||||
|
||||
A common pattern when building a single configuration is to have a build
|
||||
directory named `build` in the root of the source tree.
|
||||
|
||||
|
||||
@subsubsection compile_generate_cli Generating files with the CMake command-line tool
|
||||
@subsubsection compile_generate_gui Generating files with the CMake GUI
|
||||
|
||||
To make an in-tree build, enter the _root_ directory of the GLFW source tree
|
||||
(i.e. _not_ the `src` subdirectory) and run CMake. The current directory is
|
||||
used as target path, while the path provided as an argument is used to find the
|
||||
source tree.
|
||||
Start the CMake GUI and set the paths to the source and build directories
|
||||
described above. Then press _Configure_ and _Generate_.
|
||||
|
||||
@code{.sh}
|
||||
cd <glfw-root-dir>
|
||||
cmake .
|
||||
@endcode
|
||||
If you wish change any CMake variables in the list, press _Configure_ and then
|
||||
_Generate_ to have the new values take effect. The variable list will be
|
||||
populated after the first configure step.
|
||||
|
||||
To make an out-of-tree build, make a directory outside of the source tree, enter
|
||||
it and run CMake with the (relative or absolute) path to the root of the source
|
||||
tree as an argument.
|
||||
|
||||
@code{.sh}
|
||||
mkdir glfw-build
|
||||
cd glfw-build
|
||||
cmake <glfw-root-dir>
|
||||
@endcode
|
||||
By default GLFW will use X11 on Linux and other Unix-like systems other
|
||||
than macOS. To use Wayland instead, set the `GLFW_USE_WAYLAND` option in the
|
||||
GLFW section of the variable list, then apply the new value as described above.
|
||||
|
||||
Once you have generated the project files or makefiles for your chosen
|
||||
development environment, move on to @ref compile_compile.
|
||||
|
||||
|
||||
@subsubsection compile_generate_gui Generating files with the CMake GUI
|
||||
@subsubsection compile_generate_cli Generating files with the CMake command-line tool
|
||||
|
||||
If you are using the GUI version, choose the root of the GLFW source tree as
|
||||
source location and the same directory or another, empty directory as the
|
||||
destination for binaries. Choose _Configure_, change any options you wish to,
|
||||
_Configure_ again to let the changes take effect and then _Generate_.
|
||||
To make a build directory, pass the source and build directories to the `cmake`
|
||||
command. These can be relative or absolute paths. The build directory is
|
||||
created if it doesn't already exist.
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build
|
||||
@endcode
|
||||
|
||||
It is common to name the build directory `build` and place it in the root of the
|
||||
source tree when only planning to build a single configuration.
|
||||
|
||||
@code{.sh}
|
||||
cd path/to/glfw
|
||||
cmake -S . -B build
|
||||
@endcode
|
||||
|
||||
Without other flags these will generate Visual Studio project files on Windows
|
||||
and makefiles on other platforms. You can choose other targets using the `-G`
|
||||
flag.
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build -G Xcode
|
||||
@endcode
|
||||
|
||||
By default GLFW will use X11 on Linux and other Unix-like systems other
|
||||
than macOS. To use Wayland instead, set the `GLFW_USE_WAYLAND` CMake option.
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build -D GLFW_USE_WAYLAND=1
|
||||
@endcode
|
||||
|
||||
Once you have generated the project files or makefiles for your chosen
|
||||
development environment, move on to @ref compile_compile.
|
||||
@ -177,20 +169,39 @@ development environment, move on to @ref compile_compile.
|
||||
|
||||
You should now have all required dependencies and the project files or makefiles
|
||||
necessary to compile GLFW. Go ahead and compile the actual GLFW library with
|
||||
these files, as you would with any other project:
|
||||
these files as you would with any other project.
|
||||
|
||||
With Visual Studio open `GLFW.sln` and use the Build menu. With Xcode open
|
||||
`GLFW.xcodeproj` and use the Project menu.
|
||||
|
||||
With Linux, macOS and other forms of Unix, run `make`.
|
||||
|
||||
e.g. on linux or unix,
|
||||
@code{.sh}
|
||||
cd <glfw-root-dir>
|
||||
make install
|
||||
cd path/to/build
|
||||
make
|
||||
@endcode
|
||||
or on Windows, open the .sln file in Visual Studio and build via the file menu.
|
||||
|
||||
Once the GLFW library is compiled, you are ready to build your applications,
|
||||
With MinGW, it is `mingw32-make`.
|
||||
|
||||
@code{.sh}
|
||||
cd path/to/build
|
||||
mingw32-make
|
||||
@endcode
|
||||
|
||||
Any CMake build directory can also be built with the `cmake` command and the
|
||||
`--build` flag.
|
||||
|
||||
@code{.sh}
|
||||
cmake --build path/to/build
|
||||
@endcode
|
||||
|
||||
This will run the platform specific build tool the directory was generated for.
|
||||
|
||||
Once the GLFW library is compiled you are ready to build your application,
|
||||
linking it to the GLFW library. See @ref build_guide for more information.
|
||||
|
||||
|
||||
@subsection compile_options CMake options
|
||||
@section compile_options CMake options
|
||||
|
||||
The CMake files for GLFW provide a number of options, although not all are
|
||||
available on all supported platforms. Some of these are de facto standards
|
||||
@ -206,59 +217,103 @@ Finally, if you don't want to use any GUI, you can set options from the `cmake`
|
||||
command-line with the `-D` flag.
|
||||
|
||||
@code{.sh}
|
||||
cmake -DBUILD_SHARED_LIBS=ON .
|
||||
cmake -S path/to/glfw -B path/to/build -D BUILD_SHARED_LIBS=ON
|
||||
@endcode
|
||||
|
||||
|
||||
@subsubsection compile_options_shared Shared CMake options
|
||||
@subsection compile_options_shared Shared CMake options
|
||||
|
||||
@anchor BUILD_SHARED_LIBS
|
||||
__BUILD_SHARED_LIBS__ determines whether GLFW is built as a static
|
||||
library or as a DLL / shared library / dynamic library.
|
||||
library or as a DLL / shared library / dynamic library. This is disabled by
|
||||
default, producing a static GLFW library.
|
||||
|
||||
@anchor GLFW_BUILD_EXAMPLES
|
||||
__GLFW_BUILD_EXAMPLES__ determines whether the GLFW examples are built
|
||||
along with the library. This is enabled by default unless GLFW is being built
|
||||
as a sub-project.
|
||||
as a sub-project of a larger CMake project.
|
||||
|
||||
@anchor GLFW_BUILD_TESTS
|
||||
__GLFW_BUILD_TESTS__ determines whether the GLFW test programs are
|
||||
built along with the library. This is enabled by default unless GLFW is being
|
||||
built as a sub-project.
|
||||
built as a sub-project of a larger CMake project.
|
||||
|
||||
@anchor GLFW_BUILD_DOCS
|
||||
__GLFW_BUILD_DOCS__ determines whether the GLFW documentation is built along
|
||||
with the library.
|
||||
with the library. This is enabled by default if
|
||||
[Doxygen](https://www.doxygen.nl/) is found by CMake during configuration.
|
||||
|
||||
@anchor GLFW_VULKAN_STATIC
|
||||
__GLFW_VULKAN_STATIC__ determines whether to use the Vulkan loader linked
|
||||
directly with the application.
|
||||
directly with the application. This is disabled by default.
|
||||
|
||||
|
||||
@subsubsection compile_options_win32 Windows specific CMake options
|
||||
@subsection compile_options_win32 Windows specific CMake options
|
||||
|
||||
@anchor USE_MSVC_RUNTIME_LIBRARY_DLL
|
||||
__USE_MSVC_RUNTIME_LIBRARY_DLL__ determines whether to use the DLL version or the
|
||||
static library version of the Visual C++ runtime library. If set to `ON`, the
|
||||
DLL version of the Visual C++ library is used.
|
||||
static library version of the Visual C++ runtime library. When enabled, the
|
||||
DLL version of the Visual C++ library is used. This is enabled by default.
|
||||
|
||||
@note On CMake 3.15 and later you can set the
|
||||
On CMake 3.15 and later you can set the standard CMake
|
||||
[CMAKE_MSVC_RUNTIME_LIBRARY](https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html)
|
||||
variable instead of this option.
|
||||
variable instead of this GLFW-specific option.
|
||||
|
||||
@anchor GLFW_USE_HYBRID_HPG
|
||||
__GLFW_USE_HYBRID_HPG__ determines whether to export the `NvOptimusEnablement` and
|
||||
`AmdPowerXpressRequestHighPerformance` symbols, which force the use of the
|
||||
high-performance GPU on Nvidia Optimus and AMD PowerXpress systems. These symbols
|
||||
need to be exported by the EXE to be detected by the driver, so the override
|
||||
will not work if GLFW is built as a DLL.
|
||||
will not work if GLFW is built as a DLL. This is disabled by default, letting
|
||||
the operating system and driver decide.
|
||||
|
||||
|
||||
@subsection compile_options_wayland Wayland specific CMake options
|
||||
|
||||
@anchor GLFW_USE_WAYLAND
|
||||
__GLFW_USE_WAYLAND__ determines whether to compile the library for Wayland.
|
||||
This option is only available on Linux and other Unix-like systems other than
|
||||
macOS. This is disabled by default.
|
||||
|
||||
|
||||
@section compile_mingw_cross Cross-compilation with CMake and MinGW
|
||||
|
||||
Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages. For
|
||||
example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages
|
||||
for 32- and 64-bit version of MinGW-w64, while Debian GNU/Linux and derivatives
|
||||
like Ubuntu have the `mingw-w64` package for both.
|
||||
|
||||
GLFW has CMake toolchain files in the `CMake` subdirectory that set up
|
||||
cross-compilation of Windows binaries. To use these files you set the
|
||||
`CMAKE_TOOLCHAIN_FILE` CMake variable with the `-D` flag add an option when
|
||||
configuring and generating the build files.
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build -D CMAKE_TOOLCHAIN_FILE=path/to/file
|
||||
@endcode
|
||||
|
||||
The exact toolchain file to use depends on the prefix used by the MinGW or
|
||||
MinGW-w64 binaries on your system. You can usually see this in the /usr
|
||||
directory. For example, both the Ubuntu and Cygwin MinGW-w64 packages have
|
||||
`/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct invocation
|
||||
would be:
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build -D CMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake
|
||||
@endcode
|
||||
|
||||
The path to the toolchain file is relative to the path to the GLFW source tree
|
||||
passed to the `-S` flag, not to the current directory.
|
||||
|
||||
For more details see the
|
||||
[CMake toolchain guide](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html).
|
||||
|
||||
|
||||
@section compile_manual Compiling GLFW manually
|
||||
|
||||
If you wish to compile GLFW without its CMake build environment then you will
|
||||
have to do at least some of the platform detection yourself. GLFW needs
|
||||
a configuration macro to be defined in order to know what window system it's
|
||||
a configuration macro to be defined in order to know what window system it is
|
||||
being compiled for and also has optional, platform-specific ones for various
|
||||
features.
|
||||
|
||||
@ -290,11 +345,6 @@ of @b _GLFW_VULKAN_LIBRARY, @b _GLFW_EGL_LIBRARY, @b _GLFW_GLX_LIBRARY, @b
|
||||
_GLFW_OSMESA_LIBRARY, @b _GLFW_OPENGL_LIBRARY, @b _GLFW_GLESV1_LIBRARY and @b
|
||||
_GLFW_GLESV2_LIBRARY. Otherwise, GLFW will use the built-in default names.
|
||||
|
||||
For the EGL context creation API, the following options are available:
|
||||
|
||||
- @b _GLFW_USE_EGLPLATFORM_H to use an existing `EGL/eglplatform.h` header file
|
||||
for native handle types (fallback)
|
||||
|
||||
@note None of the @ref build_macros may be defined during the compilation of
|
||||
GLFW. If you define any of these in your build files, make sure they are not
|
||||
applied to the GLFW sources.
|
||||
|
Loading…
Reference in New Issue
Block a user