Build documentation improvements (#3362)

* Some documentation improvements: extra info on using GENie.

* Some grammer.

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
+The directories for `bx`, `bimg`, and `bgfx` should all be siblings of each other.
-
+So clone the repositories next to each other:
-Getting Source
---------------
 
 ::
 
@@ -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
+to generate project files for various platforms. Binaries of GENie for Linux, macOS, and Windows are included in
-bx repository.
+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.
+After calling ``make``, some directories in ``.build/projects/\*`` will be generated.
-All intermediate files generated by compiler will be inside .build
+All intermediate files, libraries and executables generated by the compiler will be inside this
-directory structure. Deleting .build directory at any time is safe.
+``.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
+For ease of integration with other build systems, the bgfx library can be built
-with single .cpp file. It's only necessary to build
+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

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