From edd145fe4fdc37bc326a29ae0d21e321c9257d37 Mon Sep 17 00:00:00 2001 From: Martijn Courteaux Date: Sun, 6 Oct 2024 08:14:07 +0200 Subject: [PATCH] Build documentation improvements (#3362) * Some documentation improvements: extra info on using GENie. * Some grammer. --- docs/build.rst | 104 +++++++++++++++++++++++++++++++++++----------- docs/overview.rst | 2 +- 2 files changed, 81 insertions(+), 25 deletions(-) diff --git a/docs/build.rst b/docs/build.rst index 3fd670d25..b965aa7d1 100644 --- a/docs/build.rst +++ b/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 `__ -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 ``-[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 ```` is ``linux``, ``windows``, or ``darwin``): +:: + + ../bx/tools/bin//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//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= -C .build/projects/-gmake + +Where ```` is something like ``release64``, ``debug64`` (or equivalent 32 bit), and +```` 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 `__ +Due to the `inability `__ to set working directory for an Xcode project from `GENie `__ 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 `__ (for macOS/iOS/iPadOS/tvOS use `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 diff --git a/docs/overview.rst b/docs/overview.rst index 28ca7b1bf..ff43fa362 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -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