bgfx/docs/build.rst

Building
========

Dependencies
------------

https://github.com/bkaradzic/bx

https://github.com/bkaradzic/bimg

Getting Source
--------------

::

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

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 vs2019

Open bgfx solution in Visual Studio 2019:

::

    start .build\projects\vs2019\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 platform. Binaries for Linux, macOS, and Windows are included in
bx repository.

General
~~~~~~~

::

    cd bgfx
    make

After calling ``make``, .build/projects/\* directory will be generated.
All intermediate files generated by compiler will be inside .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.

Windows
~~~~~~~

Visual Studio 2019 command line:

::

    make vs2019-release64

Visual Studio 2019 IDE:

::

    start .build/projects/vs2019/bgfx.sln

Xcode
~~~~~

Xcode command line:

::

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

Xcode IDE:

::

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

Due to `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

WinRT / UWP
~~~~~~~~~~~

::

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

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 to other build system bgfx library can be built
with 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 different build system.

Tools
-----

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

::

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


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