Skip to content

compiling.md

Latest commit

 

History

History
114 lines (100 loc) · 6.68 KB

compiling.md

File metadata and controls

114 lines (100 loc) · 6.68 KB

Compiling

Quick start

Use the guide below to get B3D Framework up and running as quickly as possible. Scroll further below for advanced build options that allow for more customization.

  • Install git (https://git-scm.com) and CMake 3.31.0 or higher (https://cmake.org)
    • Ensure they are added to your PATH environment variable
  • Install other dependencies
  • Run the following commands in the terminal/command line:
    • git clone https://github.com/GameFoundry/bsf.git
    • cd bsf
    • mkdir Build
    • cd Build
    • cmake -G "$generator$" ..
      • Where $generator$ should be replaced with any of the supported generators. Some common ones:
        • Visual Studio 17 2022 - Visual Studio 2022
        • Unix Makefiles
        • Ninja
        • Xcode
        • See all valid generators: cmake-generators
      • Optionally provide the CMAKE_INSTALL_PREFIX to override the default install path:
        • cmake -G "$generator$" -DCMAKE_INSTALL_PREFIX=/path/to/install ..
    • cmake --build . --config Release
      • Alternatively you can also run your build system manually (depending on your choice of generator):
        • Visual Studio solution is present at bsf/Build/bsf.sln
        • XCode project is present at bsf/Build
        • Makefiles are present at bsf/Build
    • cmake --build . --config Release --target install
      • Alternatively you can run the install target in your chosen build tool
      • Note that files install to the default install folder, unless you have overridden it as specified above

Customizing the build

Additional variables allow you to pick between the render API (Vulkan, Null), audio module (FMOD, OpenAudio) among other options. Run CMake to see all options. Note that non-default CMake options might require additional dependencies to be installed, see here.

Modify CMAKE_INSTALL_PREFIX to choose where the library gets installed after the install target is ran (e.g. make install, or running the INSTALL target in Visual Studio/XCode).

Modify CMAKE_BUILD_TYPE to pick what kind of a build you want. Note that this is ignored for workflow generators like Visual Studio or XCode, in which you can pick this within the IDE itself. Supported values are:

  • Debug - Builds and unoptimized version with debug symbols. This is generally what you want for development.
  • RelWithDebInfo - Builds an optimized version with debug symbols and various debug checks enabled.
  • MinSizeRel - Builds an optimized version attempting to keep the resultant binary as small as possible. Debug checks are disabled.
  • Release - Builds an optimized version with no debug checks.

You can choose to use a different CMake generator than those specified above, as long as the platform/compiler is supported:

  • Supported platforms:
    • Windows 10/11
    • Linux (currently non functional while major refactor is in progress)
    • macOS 10.11 or newer (currently non functional while major refactor is in progress)
  • Supported compilers:
    • MSVC++ 17.0 (Visual Studio 2022)
    • GCC 7.0 (or newer) (currently non functional while major refactor is in progress)
    • Clang 5.0 (or newer) (currently non functional while major refactor is in progress)
    • Apple LLVM 9.0.0 (XCode 9) (currently non functional while major refactor is in progress)

Third party dependencies

B3D Framework relies on a variety of third party dependencies. A set of pre-compiled dependencies are provided for every supported platform/compiler and these will be fetched automatically by the build process. If required, the dependencies can also be compiled manually by following this guide. This can be required if the pre-compiled dependencies don't work with your platform (e.g. unsupported Linux distro) or if you wish to update to a newer dependency version.

Note that prebuilt dependencies only come as 64-bit, if you wish to build as 32-bit you will need to compile them manually.

Other dependencies

The following dependencies will need to be installed manually. Which ones are required depend on the selected CMake options and your usage of B3D Framework (check text of each entry below).

Windows

  • Windows SDK
    • Version 10.0.26100.0, but others may work as well

Linux

  • X11
    • Debian/Ubuntu: apt-get install libx11-dev libxcursor-dev libxrandr-dev libxi-dev
  • LibUUID
    • Debian/Ubuntu: apt-get install uuid-dev
  • LibICU
    • Debian/Ubuntu: apt-get install libicu-dev
  • Bison & Flex (Optional)
    • Only needed if you plan on changing BSL syntax (B3D_BUILD_BSL_PARSER option in CMake)
    • Debian/Ubuntu: apt-get install bison flex
  • (Or equivalent packages for your distribution)

macOS

  • Homebrew
    • /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Xcode 9
    • Grab from App Store
    • After install make sure to run: xcode-select -install
  • LibUUID
    • brew install ossp-uuid
  • Flex (Optional)
    • Only needed if you plan on changing BSL syntax (B3D_BUILD_BSL_PARSER option in CMake)
    • brew install flex
  • Bison (Optional)
    • Only needed if you plan on changing BSL syntax (B3D_BUILD_BSL_PARSER option in CMake)
    • brew install bison
    • Make sure old version of Bison that comes with Xcode is overriden:
      • Add this to $HOME/.bash_profile: export PATH="/usr/local/opt/bison/bin:$PATH"
      • mv /usr/bin/bison /usr/bin/bison-2.3

All OS

  • *Vulkan SDK 1.4.321.1
    • Only needed if you selected the Vulkan render API during build configuration (currently the only option, so you need to do this)
    • https://lunarg.com/vulkan-sdk/
    • Set up VULKAN_SDK environment variable pointing to your installation
    • Additional setup for MacOS (currently not supported, as we're refactoring the macOS backend)
      • Set up the following environment variables:
        • VULKAN_SDK = $SDK_DIR$/macOS
        • VK_LAYER_PATH = $SDK_DIR$/macOS/etc/vulkan/explicit_layer.d
        • VK_ICD_FILENAMES = $SDK_DIR$/macOS/etc/vulkan/icd.d/MoltenVK_icd.json
      • Replacing $SDK_DIR$ with the directory where you extracted the SDK
  • FMOD Low Level Programmer API 1.08.02 (Optional)