ContextQMD
Back to Bgfx

Building

docs/build.rst

latest7.2 KB
Original Source

Building

Dependencies & Getting the source

The directories for bx, bimg, and bgfx should all be siblings of each other. So clone the repositories next to each other:

::

git clone https://github.com/bkaradzic/bx.git
git clone https://github.com/bkaradzic/bimg.git
git clone https://github.com/bkaradzic/bgfx.git

Quick Start for Windows

These are step for users who use Windows with Visual Studio.

Enter bgfx directory:

::

cd bgfx

Generate Visual Studio 2019 project files:

::

..\bx\tools\bin\windows\genie --with-examples vs2022

Open bgfx solution in Visual Studio 2019:

::

start .build\projects\vs2022\bgfx.sln

.. note:: For more detailed prerequisites and build steps on other platforms see below.

Prerequisites

Android


Download Android NDK (r23 or newer):

 - https://developer.android.com/tools/sdk/ndk/index.html

Set following environment variables:

::

    setx ANDROID_NDK_ROOT <path to AndroidNDK directory>


Linux
~~~~~

::

    sudo apt-get install libgl1-mesa-dev x11proto-core-dev libx11-dev

Windows

Windows users download GnuWin32 utilities:

.. note:: MSYS, Cygwin, etc. shells are not supported! You must use use cmd.exe with provided makefiles.

Build

bgfx uses GENie - Project generator tool <https://github.com/bkaradzic/genie#genie---project-generator-tool>__ to generate project files for various platforms. Binaries of GENie for Linux, macOS, and Windows are included in the bx repository. GENie can generate a useful list of options relevant to the project using the --help flag. Most platform-specific examples below do not explicitly use the genie executable, but a convenience makefile instead. For more control, you can directly use genie to generate the project files.

General (Makefile wrapper)


::

    cd bgfx
    make

After calling ``make``, some directories in ``.build/projects/\*`` will be generated.
All intermediate files, libraries and executables generated by the compiler will be inside this
``.build`` directory structure. Deleting ``.build`` directory at any time is safe.

::

    make <configuration>

Configuration is ``<platform>-<debug/release>[32/64]``. For example:

::

    linux-release64, wasm-debug, wasm-release, osx-debug, osx-release, android-arm64-release, etc.


General (Directly with GENie)

Inspect the available options by invoking GENie with the --help option (where <platform> is linux, windows, or darwin): ::

../bx/tools/bin/<platform>/genie --help

Select the options you want, such as:

There are also many platform-specific options.

.. note:: If you wish to use the OpenGL backend, specifying a minimum API version is possible through setting the BGFX_CONFIG environment variable when running genie. For example:

::

  # Unix:
  export BGFX_CONFIG=RENDERER_OPENGL_MIN_VERSION=40
  # Windows:
  set BGFX_CONFIG=RENDERER_OPENGL_MIN_VERSION=40

  ../bx/tools/bin/<platform>/genie <... your options ...>

The same can be done for OpenGL ES.

Then generate your project files with the options. Your project folder is in .build/projects/. For more help on specific platforms, see below and read the makefile in the bgfx repository) for examples on how to use GENie.

For gmake projects, specify compile using:

::

make config=<config> -C .build/projects/<platform>-gmake

Where <config> is something like release64, debug64 (or equivalent 32 bit), and <platform> is the platform you chose.

Windows


Visual Studio 2019 command line:

::

    make vs2022-release64

Visual Studio 2019 IDE:

::

    start .build/projects/vs2022/bgfx.sln

macOS
~~~~~

There are two options when working on macOS: Xcode command-line builds, or within the XCode graphical development environment.

For the Xcode command line:

::

    make osx-release
    cd examples/runtime
    ../../.build/osx64_clang/bin/examples.app/Contents/MacOS/examplesRelease

Or for Xcode IDE:

::

    ../bx/tools/bin/darwin/genie --with-combined-examples --xcode=osx xcode9
    open .build/projects/xcode9-osx/bgfx.xcworkspace

Due to the `inability <https://github.com/bkaradzic/genie/blob/master/docs/scripting-reference.md#debugdirpath>`__
to set working directory for an Xcode project from `GENie <https://github.com/bkaradzic/genie#genie---project-generator-tool>`__
configuration file, it has to be set manually for each example project:

1. Open *"Edit scheme..."* dialog for a given project.
2. Select *"Run"* settings.
3. Check *"Use custom working directory"* and enter following path:
   ``${PROJECT_DIR}/../../../examples/runtime``.

Linux
~~~~~

::

    make linux-release64

For more options, see `General (directly with GENie) <#general-directly-with-genie>`_.

WinRT / UWP

::

..\bx\tools\bin\windows\genie --vs=winstore100 vs2022

For more options, see General (directly with GENie) <#general-directly-with-genie>_. Build the resulting solution and deploy to device.

.. note:: Shaders will need to be compiled with the appropriate target profile for your platform.

Amalgamated Build

For ease of integration with other build systems, the bgfx library can be built with a single .cpp file. It's only necessary to build src/amalgamated.cpp <https://github.com/bkaradzic/bgfx/blob/master/src/amalgamated.cpp>__ (for macOS/iOS/iPadOS/tvOS use src/amalgamated.mm <https://github.com/bkaradzic/bgfx/blob/master/src/amalgamated.mm>__ instead) inside a different build system.

Tools

To build bgfx project files for tools, use --with-tools option:

::

..\bx\tools\bin\windows\genie --with-tools vs2022

Alternative build systems

CMake

fips is a high-level build system wrapper written in Python for C/C++ projects. https://github.com/floooh/fips#fips

Conan package https://github.com/firefalcom/bgfx-conan

Minimal example without bgfx's example harness

This project demonstrates minimal amount of code needed to integrate bgfx with GLFW, but without any of existing bgfx example harness. It also demonstrates how to build bgfx with alternative build system.

https://github.com/jpcy/bgfx-minimal-example