272 lines
7.2 KiB
ReStructuredText
272 lines
7.2 KiB
ReStructuredText
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 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 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 vs2019-release64
|
|
|
|
Visual Studio 2019 IDE:
|
|
|
|
::
|
|
|
|
start .build/projects/vs2019/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 vs2019
|
|
|
|
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 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 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
|