|
|
@@ -1,15 +1,14 @@
|
|
|
Building
|
|
|
========
|
|
|
|
|
|
-Dependencies
|
|
|
-------------
|
|
|
+Dependencies & Getting the source
|
|
|
+---------------------------------
|
|
|
|
|
|
-https://github.com/bkaradzic/bx
|
|
|
+ - https://github.com/bkaradzic/bx
|
|
|
+ - https://github.com/bkaradzic/bimg
|
|
|
|
|
|
-https://github.com/bkaradzic/bimg
|
|
|
-
|
|
|
-Getting Source
|
|
|
---------------
|
|
|
+The directories for `bx`, `bimg`, and `bgfx` should all be siblings of each other.
|
|
|
+So clone the repositories next to each other:
|
|
|
|
|
|
::
|
|
|
|
|
|
@@ -17,8 +16,8 @@ Getting Source
|
|
|
git clone https://github.com/bkaradzic/bimg.git
|
|
|
git clone https://github.com/bkaradzic/bgfx.git
|
|
|
|
|
|
-Quick Start
|
|
|
------------
|
|
|
+Quick Start for Windows
|
|
|
+-----------------------
|
|
|
|
|
|
These are step for users who use Windows with Visual Studio.
|
|
|
|
|
|
@@ -83,20 +82,22 @@ 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.
|
|
|
+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
|
|
|
-~~~~~~~
|
|
|
+General (Makefile wrapper)
|
|
|
+~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
::
|
|
|
|
|
|
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.
|
|
|
+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.
|
|
|
|
|
|
::
|
|
|
|
|
|
@@ -108,6 +109,55 @@ 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
|
|
|
~~~~~~~
|
|
|
|
|
|
@@ -123,10 +173,12 @@ Visual Studio 2019 IDE:
|
|
|
|
|
|
start .build/projects/vs2019/bgfx.sln
|
|
|
|
|
|
-Xcode
|
|
|
+macOS
|
|
|
~~~~~
|
|
|
|
|
|
-Xcode command line:
|
|
|
+There are two options when working on macOS: Xcode command-line builds, or within the XCode graphical development environment.
|
|
|
+
|
|
|
+For the Xcode command line:
|
|
|
|
|
|
::
|
|
|
|
|
|
@@ -134,14 +186,14 @@ Xcode command line:
|
|
|
cd examples/runtime
|
|
|
../../.build/osx64_clang/bin/examples.app/Contents/MacOS/examplesRelease
|
|
|
|
|
|
-Xcode IDE:
|
|
|
+Or for 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>`__
|
|
|
+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:
|
|
|
|
|
|
@@ -157,6 +209,8 @@ Linux
|
|
|
|
|
|
make linux-release64
|
|
|
|
|
|
+For more options, see `General (directly with GENie) <#general-directly-with-genie>`_.
|
|
|
+
|
|
|
WinRT / UWP
|
|
|
~~~~~~~~~~~
|
|
|
|
|
|
@@ -164,19 +218,21 @@ 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 to other build system bgfx library can be built
|
|
|
-with single .cpp file. It's only necessary to 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 different build system.
|
|
|
+instead) inside a different build system.
|
|
|
|
|
|
Tools
|
|
|
-----
|
|
|
@@ -199,7 +255,7 @@ Alternative build systems
|
|
|
- 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.
|
|
|
+**fips** is a high-level build system wrapper written in Python for C/C++ projects.
|
|
|
https://github.com/floooh/fips#fips
|
|
|
|
|
|
**Conan** package
|
Martijn Courteaux