Build documentation improvements (#3362)
* Some documentation improvements: extra info on using GENie. * Some grammer.
This commit is contained in:
Martijn Courteaux
GitHub
parent
e488a07f1b
commit
edd145fe4f
104
docs/build.rst
104
docs/build.rst
@ -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
|
||||
|
||||
@ -34,7 +34,7 @@ Supported Platforms
|
||||
|
||||
- Android (14+)
|
||||
- iOS/iPadOS/tvOS (16.0+)
|
||||
- Linux
|
||||
- Linux (both X11 and Wayland)
|
||||
- macOS (13.0+)
|
||||
- PlayStation 4
|
||||
- RaspberryPi
|
||||
|
||||
Loading…
Reference in New Issue
Block a user