Methane Kit Build Instructions

Prerequisites
Fetch Sources
- First time initialization
- Update sources to latest revision
Building from Sources
CMake Generator
- CMake Options
- CMake Presets

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!