Skip to content

README.md

Latest commit

 

History

History
249 lines (198 loc) · 18.5 KB

README.md

File metadata and controls

249 lines (198 loc) · 18.5 KB

Methane Kit Build Instructions

Prerequisites

  • Common
    • CMake 3.18 or later
    • Git (is required to fetch external dependent repositories using CPM)
  • Windows
    • Windows 10 RS5 (build 1809) or later
    • Visual Studio 2022 with MSVC v143 or later
    • Windows 10 SDK (latest)
    • Visual C++ ATL Support (required by DXC)
  • Linux
    • Ubuntu 20.04 or later
    • GCC 9 or later
    • X11, XCB, LCov (optional for code coverage) libraries
    sudo apt-get update && sudo apt-get install build-essential git cmake lcov xcb libx11-dev libx11-xcb-dev libxcb-sync-dev libxcb-randr0-dev
  • MacOS
    • MacOS 13 "Ventura" or later
    • XCode 14 or later with command-line tools
  • iOS / tvOS
    • All MacOS prerequisites from above
    • iOS or tvOS simulator for running app in virtual environment
    • iOS or tvOS device with Apple Development Certificate (can be created with Apple ID from Xcode)

Fetch Sources

Notes

  • Since v0.6, Methane Kit does not use Git submodules anymore and uses CPM.cmake to fetch dependent repositories during the CMake configuration stage. Therefore, it is possible to acquire sources with the git clone command or to download them as a ZIP archive using the Code > Download ZIP button.
  • All External dependencies are fetched to the Build/Output/ExternalsCache/... directory, which can be changed by adding -DCPM_SOURCE_CACHE=<cache_path> to the CMake configuration command.
  • Consider enabling paths longer than 260 symbols in Windows to allow CMake to generate build subdirectories normally. Long paths can be enabled with this command run from an Administrator PowerShell terminal:
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

First time initialization

git clone https://github.com/MethanePowered/MethaneKit.git
cd MethaneKit

Update sources to latest revision

cd MethaneKit
git pull

Building from Sources

Windows Build with Visual Studio

Start Command Prompt, go to MethaneKit root directory and either start auxiliary build script or build with CMake command line to generate Visual Studio 2022 solution:

set OUTPUT_DIR=Build\Output\VisualStudio\Win64-DX
cmake -S . -B %OUTPUT_DIR%\Build -G "Visual Studio 17 2022" -A x64 -DCMAKE_INSTALL_PREFIX="%cd%\%OUTPUT_DIR%\Install"
cmake --build %OUTPUT_DIR%\Build --config Release --target install

Methane Graphics RHI is built using DirectX 12 graphics API by default on Windows. Vulkan graphics API can be used instead by adding cmake generator option -DMETHANE_GFX_VULKAN_ENABLED:BOOL=ON. Auxiliary build script Build/Windows/Build.bat can make it more simple for you:

./Build/Windows/Build.bat [--vs2019] [--win32] [--debug] [--vulkan] [--graphviz] [--tracy] [--itt] [--cpu_profile] [--gpu_profile] [--logs] [--analyze SONAR_TOKEN]

Alternatively root CMakeLists.txt can be opened directly in Visual Studio or any other IDE with native CMake support and built using CMake presets.

Run built applications from the installation directory Build\Output\VisualStudio\Win64-DX\Install\Apps

Linux Build with Unix Makefiles

Start Terminal, go to MethaneKit root directory, generate Unix Makefiles and build them with CMake command line:

OUTPUT_DIR=Build/Output/Linux
cmake -S . -B $OUTPUT_DIR/Build -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX="$(pwd)/$OUTPUT_DIR/Install"
cmake --build $OUTPUT_DIR/Build --config Release --target install --parallel 8

Methane Graphics RHI is built using Vulkan graphics API on Linux. Auxiliary build script Build/Unix/Build.sh can make it more simple for you:

./Build/Unix/Build.sh [--debug] [--graphviz] [--analyze SONAR_TOKEN]

Alternatively root CMakeLists.txt can be opened directly in any IDE with native CMake support and built using CMake presets.

Run built applications from the installation directory Build/Output/Linux/Install/Apps. Note that in Ubuntu Linux even GUI applications should be started from "Terminal" app, because of noexec permission set on user's home directory by security reasons.

MacOS Build with XCode

Start Terminal, go to MethaneKit root directory, generate XCode workspace and build it with CMake command line:

OUTPUT_DIR=Build/Output/XCode/macOS
cmake -S . -B $OUTPUT_DIR/Build -G Xcode -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" -DCMAKE_INSTALL_PREFIX="$(pwd)/$OUTPUT_DIR/Install"
cmake --build $OUTPUT_DIR/Build --config Release --target install

Note that starting with XCode 12 and Clang 12 build architectures have to be specified explicitly using CMake generator command line option -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" to build the fat binary. This option should be omitted with earlier versions of Clang on macOS.

Auxiliary build script Build/Unix/Build.sh can make it more simple for you:

./Build/Unix/Build.sh [--debug] [--graphviz] [--vulkan VULKAN_SDK_PATH] [--analyze SONAR_TOKEN]

Alternatively root CMakeLists.txt can be opened directly in Visual Studio or any other IDE with native CMake support and built using CMake presets.

Methane Graphics RHI is built using Metal graphics API on MacOS by default. Vulkan graphics API can be used instead by adding cmake generator option -DMETHANE_GFX_VULKAN_ENABLED:BOOL=ON or by running Build/Unix/Build.sh --vulkan, but it requires Vulkan SDK installation with MoltenVK driver implementation on top of Metal.

Run built applications from the installation directory Build/Output/XCode/Install/Apps.

iOS and tvOS Build with XCode

Start Terminal, go to MethaneKit root directory, generate XCode workspace and build it with CMake command line:

OUTPUT_DIR=Build/Output/XCode/iOS
cmake -S . -B $OUTPUT_DIR/Build -G Xcode -DCMAKE_TOOLCHAIN_FILE="Externals/iOS-Toolchain.cmake" -DPLATFORM=[SIMULATORARM64|OS64|SIMULATOR_TVOS|TVOS] -DDEPLOYMENT_TARGET=16.0 -DENABLE_ARC:BOOL=ON [-DAPPLE_DEVELOPMENT_TEAM=12345X6ABC] -DCMAKE_INSTALL_PREFIX="$(pwd)/$OUTPUT_DIR/Install"
cmake --build $OUTPUT_DIR/Build --config Release --target install -- -allowProvisioningUpdates

Please pay attention to correctly setting the following options:

  • CMAKE_TOOLCHAIN_FILE should be set to Externals/iOS-Toolchain.cmake for iOS/tvOS build
  • PLATFORM defines Apple target platform where application will run:
    • OS64 - build for 64-bit iOS device: iPhone or iPad
    • TVOS - build for tvOS device
    • SIMULATORARM64 or SIMULATOR64 - build for iOS simulator with Arm64 or x64 architecture (depending on your Mac CPU)
    • SIMULATOR_TVOS - build for tvOS simulator
  • DEPLOYMENT_TARGET defines minimum version of the target platform
  • APPLE_DEVELOPMENT_TEAM defines development team identifier used for code signing, which is required to build for running on physical device (not required for simulator build). This identifier depends on your signing preferences in Xcode and should look like this 12345X6ABC. It can be found inside the pre-configured for signing .xcodeproj file contents (which can be opened with VSCode) by searching for the value of parameter named DEVELOPMENT_TEAM.
  • ENABLE_ARC set to ON to enable automatic reference counting in Apple Clang build.
  • Note that cmake --build command contains extra argument -allowProvisioningUpdates passed to the underlying xcodebuild command line tool, which allows Xcode to update or add missing provisioning profiles for code signing.

Auxiliary build script Build/Unix/Build.sh can make it more simple for you:

./Build/Unix/Build.sh --apple-platform [SIMULATORARM64|OS64|SIMULATOR_TVOS|TVOS] [--apple-dev-team 12345X6ABC] [--apple-deploy-target 16.0] [--debug]

Please open generated Xcode workspace, select application schema and run it on iOS / tvOS device or simulator from the Xcode IDE.

CMake Generator

CMake Options

Build options listed in table below can be used in cmake generator command line:

cmake -G [Generator] ... -D[BUILD_OPTION_NAME]:BOOL=[ON|OFF]
Build Option Name Initial Value Default Preset Profiling Preset Description
METHANE_GFX_VULKAN_ENABLED OFF ... ... Enable Vulkan graphics API instead of platform native API
METHANE_APPS_BUILD_ENABLED ON ON ON Enable applications build
METHANE_TESTS_BUILD_ENABLED ON ON OFF Enable tests build
METHANE_RHI_PIMPL_INLINE_ENABLED ON (in Release) ON (in Release) ON Enable RHI PIMPL implementation inlining
METHANE_PRECOMPILED_HEADERS_ENABLED ON (not Apple) ON (not Apple) ON (not Apple) Enable precompiled headers
METHANE_CHECKS_ENABLED ON ON ON Enable runtime checks of input arguments
METHANE_RUN_TESTS_DURING_BUILD ON OFF OFF Enable test auto-run after module build
METHANE_UNITY_BUILD_ENABLED ON ON ON Enable unity build speedup for some modules
METHANE_CODE_COVERAGE_ENABLED OFF OFF OFF Enable code coverage data collection with GCC and Clang
METHANE_SHADERS_CODEVIEW_ENABLED OFF ON ON Enable shaders code symbols viewing in debug tools
METHANE_OPEN_IMAGE_IO_ENABLED OFF OFF OFF Enable using OpenImageIO library for images loading
METHANE_COMMAND_DEBUG_GROUPS_ENABLED OFF ON ON Enable command list debug groups with frame markup
METHANE_LOGGING_ENABLED OFF OFF OFF Enable debug logging
METHANE_SCOPE_TIMERS_ENABLED OFF OFF ON Enable low-overhead profiling with scope-timers
METHANE_ITT_INSTRUMENTATION_ENABLED OFF ON ON Enable ITT instrumentation for trace capture with Intel GPA or VTune
METHANE_ITT_METADATA_ENABLED OFF OFF ON Enable ITT metadata for tasks and events like function source locations
METHANE_GPU_INSTRUMENTATION_ENABLED OFF OFF ON Enable GPU instrumentation to collect command list execution timings
METHANE_TRACY_PROFILING_ENABLED OFF OFF ON Enable realtime profiling with Tracy
METHANE_TRACY_PROFILING_ON_DEMAND OFF OFF ON Enable Tracy data collection on demand, after client connection
METHANE_MEMORY_SANITIZER_ENABLED OFF OFF OFF Enable memory address sanitizer in compiler and linker
METHANE_APPLE_CODE_SIGNING_ENABLED OFF OFF OFF Enable code signing on Apple platforms (requires APPLE_DEVELOPMENT_TEAM)
METHANE_METAL_FRAMES_SYNC_WITH_DISPATCH_SEMAPHORE OFF OFF OFF Enable Metal frame synchronization with dispatch semaphore instead of fence
METHANE_METAL_SHADER_CONVERTER_ENABLED OFF OFF OFF Enable Metal Shader Converter instead of SPIRV-Cross (Experimental)
METHANE_METAL_ARGUMENT_BUFFERS_ENABLED ON ON ON Enable Metal Argument Buffers for shader bindings with SPIRV-Cross (Experimental)

CMake Presets

CMake Presets can be used to configure and build project with a set of predefined options (CMake 3.20 is required):

cmake --preset [ConfigPresetName]
cmake --build --preset [BuildPresetName] --target install

Configure preset names [ConfigPresetName] can be listed with cmake --list-presets and are constructed according to the next schema using compatible kets according to preset matrix:

[ConfigPresetName] = [VS2022|Xcode|Make|Ninja]-[Win64|Win32|Win|Lin|Mac|iOS|tvOS]-[Sim]-[DX|VK|MTL]-[Default|Profile|Scan]
Presets Matrix VS2022 Xcode Make Ninja
Win64 DX / VK - - -
Win32 DX / VK - - -
Win - - - DX / VK
Lin - - VK VK
Mac - MTL - MTL
iOS [-Sim] - MTL - -
tvOS [-Sim] - MTL - -

Build preset names [BuildPresetName] can be listed with cmake --list-presets build and are constructed according to the same schema, but Default suffix should be replaced with Debug or Release configuration name. Only compatible configure and build presets can be used together either with the same name, or with Debug or Release instead of Default. Ninja presets should be used from "x64/x86 Native Tools Command Prompt for VS2022" command line environment on Windows or directly from Visual Studio.

GitHub Actions CI builds are configured with these CMake presets. CMake presets can be also used in VS2022 and VS Code to reproduce CI builds on the development system with a few configuration options in IDE UI.