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 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 `__ 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 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 ~~~~~~~ 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 `__ to set working directory for an Xcode project from `GENie `__ 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 `__ (for macOS/iOS/iPadOS/tvOS use `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