bgfx/docs/build.rst

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

 - ``--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 <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**

 - 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