# Building

## Dependencies & Getting the source

> - https://github.com/bkaradzic/bx

> - https://github.com/bkaradzic/bimg

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:

> - http://gnuwin32.sourceforge.net/packages/make.htm

> - http://gnuwin32.sourceforge.net/packages/coreutils.htm

> - http://gnuwin32.sourceforge.net/packages/libiconv.htm

> - http://gnuwin32.sourceforge.net/packages/libintl.htm

Note

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

## Build

bgfx uses 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:

> - `--with-tools`

> - `--with-amalgamated` (see below)

> - `--with-shared-lib`

> - `--with-profiler` (see https://bkaradzic.github.io/bgfx/bgfx.html#_CPPv4N4bgfx9CallbackIE)

> - `--with-examples` (see https://bkaradzic.github.io/bgfx/examples.html)

> - `--with-sdl` to use SDL2 for the examples.

> - `--with-glfw` to use GLFW3 for the examples.

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 to set working directory for an Xcode project from GENie 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).

### WinRT / UWP

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

For more options, see 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 (for macOS/iOS/iPadOS/tvOS use 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

> - https://github.com/bkaradzic/bgfx.cmake

> - https://github.com/JoshuaBrookover/bgfx.cmake#bgfxcmake

> - https://github.com/pr0g/sdl-bgfx-imgui-starter#sdl-bgfx-imgui-starter

> - https://github.com/yuki-koyama/hello-bgfx

> - https://github.com/ataulien/bgfx-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