Xcode Setup

XCode is the preferred development IDE on Apple devices and while it’s technically possible to use other IDEs, it’s highly discouraged to do so because of compatibility issues and just in general overcomplicating things too much - so because we don’t hate ourselves, we are going to go to the app store and download the latest version of XCode.

This guide uses version 16.4, but any version after 9.x should work since metal-cpp requires C++17 features.

Once it’s installed, open it and create a new project:

• Open Xcode and select File > New > Project
• Choose macOS and Command Line Tool, then click next
• in Product Name put the name of your project, fill in the Organization Identifier and make sure the Language is C++
• Once the project is created go to where you put your metal-cpp.zip file, unzip it and drop it into your xcode project, under the project’s folder and hit finish

In order to get started with Metal in C++, we first need to download the official Metal Api C++ Bindings from the official Apple Developer website

Scroll down the page and you’ll find a list of available versions such as:

- metal-cpp_macOS26_iOS26-beta.zip
- metal-cpp_macOS15.2_iOS18.2.zip
- metal-cpp_macOS15_iOS18.zip
- metal-cpp_macOS15_iOS18-beta.zip
- metal-cpp_macOS14.2_iOS17.2.zip
- [...]

For this tutorial, we’ll use the metal-cpp_macOS26_iOS26-beta version, you can use the latest version that fits your system.

Now that we have done this, we need to make sure xcode can find our metal-cpp bindings so go over to the Build Settings, under the Search Paths section and add $(PROJECT_DIR)/metal-cpp to the Header Search Paths.

Go to Build Phases > Link Binary With Libraries and add these:

Foundation.framework
Metal.framework
QuartzCore.framework
IOKit.framework
CoreVideo.framework
Cocoa.framework

Here is what they are for in short:

• Foundation.framework: it provides essential data types and utilities (e.g., strings, arrays, dates, file management, threading), almost every app uses this — it’s the backbone of Objective-C and Swift standard libraries.
• Metal.framework: this is apple’s graphics and compute API for high-performance rendering and parallel computation, it’s used to interact directly with the GPU for rendering 2D/3D graphics or performing GPU tasks.
• QuartzCore.framework: it provides Core Animation (CA) classes like CAMetalLayer, which you need to present rendered Metal content to the screen - it’s the bridge between your Metal render pass and the display.
• IOKit.framework: Provides an interface for communicating with hardware devices and drivers at a low level. Useful for accessing system hardware features like USB devices, GPUs, and other peripherals.
• CoreVideo.framework: Handles video processing and buffer management, providing optimized support for handling image buffers and syncing video frames with display refresh cycles. Often used alongside Metal for video rendering and capture.
• Cocoa.framework: The primary framework for building macOS applications, providing the full set of APIs for windowing, event handling, UI components, and application lifecycle management. Foundation is part of Cocoa, but Cocoa adds UI and app infrastructure layers.

Apple requires private implementation macros to be defined in one .cpp file, so create a new file called mtl_implementation.cpp and add this:

#define NS_PRIVATE_IMPLEMENTATION
#define CA_PRIVATE_IMPLEMENTATION
#define MTL_PRIVATE_IMPLEMENTATION

#include <Foundation/Foundation.hpp>
#include <Metal/Metal.hpp>
#include <QuartzCore/QuartzCore.hpp>

Finally, inside the main.cpp file, test Metal by creating a default device, just to see if it works and everything links correctly:

#include <iostream>

// include metal bindings
#include <Metal/Metal.hpp>

int main(int argc, const char * argv[])
{
    // just to test things out, create a metal device
    MTL::Device* device = MTL::CreateSystemDefaultDevice();

    std::cout << "My First Metal App!\n";

    return 0;
}

Build And Run

Build (Cmd+B) and Run (Cmd+R) the project. If everything works, congratulations — Metal is up and running!

Download The Project Files

If you encounter issues with the code or simply want to test with the correct setup, you can download the latest project files below:

Download Project Files