Raylib CMake VSCode Setup

What You Will Build

By the end of this tutorial, you will have a working C++ project that opens a Raylib window, draws text on the screen, displays FPS, and builds through CMake inside Visual Studio Code.

The final setup includes:

• A clean C++ project folder
• Visual Studio Code configured for C++ and CMake
• CMake as the build configuration system
• Ninja as the build backend
• vcpkg as the C++ package manager
• Raylib installed as a project dependency
• A working main.cpp file that creates a game window

This is a strong beginner setup because it avoids manual include paths, manual library linking, and random copy paste configuration. Once the workflow is working, you can reuse the same structure for libraries like ImGui, fmt, SDL, Box2D, Chipmunk, and more.

Why This Setup Is Worth Learning

C++ setup can be annoying. That is the honest truth. Unlike languages with built-in package workflows, C++ often requires you to understand compilers, build systems, package managers, include paths, linkers, and architecture targets.

The good news is that this setup removes most of that pain once you understand the workflow.

• Raylib gives you a simple library for graphics, input, audio, and game loops.
• CMake defines how the project is built.
• Ninja builds the project quickly.
• vcpkg installs and manages Raylib for you.
• Visual Studio Code gives you a lightweight editor with CMake integration.

This stack is not the only way to write C++ games, but it is a practical workflow for learning, prototyping, and building small to medium projects without turning your project folder into chaos.

Tools You Need

Before creating the project, install the required tools.

• Visual Studio Code
• CMake
• Ninja
• vcpkg
• Raylib

You also need a C++ compiler. On Windows, that usually means one of these:

• MSVC through Visual Studio Build Tools
• MinGW
• Clang

For beginners on Windows, MSVC is usually the safest option because it integrates well with CMake and vcpkg. MinGW and Clang can also work, but they require more attention to toolchain and triplet compatibility.

Verify the Tools Are Installed

After installing CMake, Ninja, and vcpkg, open a terminal and check that your system can find them.

cmake --version
ninja --version
vcpkg version

If each command prints version information, the tools are available from your terminal.

If one of the commands is not recognized, the tool is either not installed correctly or not added to your system PATH. Do not skip this check. If your terminal cannot find the tools, Visual Studio Code and CMake will likely fail later too.

Create the Project Folder

Create a clean project folder. Avoid spaces in the folder name because spaces can create path issues with some tools and scripts.

Good folder names:

MyRaylibProject
RaylibStarter
CppGameSandbox

Bad folder names:

My Raylib Project
new project final
raylib test copy 2

Keep it simple. For this guide, use:

MyRaylibProject

Open the folder in Visual Studio Code. On Windows, you can right click the folder and choose Open with Code. You can also open Visual Studio Code first and select the folder manually.

Install Required Visual Studio Code Extensions

Visual Studio Code needs extensions to understand C++ and CMake projects properly.

Install these extensions:

• C/C++ by Microsoft
• CMake Tools by Microsoft

The C++ extension gives IntelliSense, code navigation, and basic debugging support. The CMake Tools extension lets you configure, build, and run CMake projects from inside Visual Studio Code.

After installing the extensions, reload Visual Studio Code if needed.

Understand the Project Structure

A clean Raylib CMake project usually contains these files:

MyRaylibProject/
  CMakeLists.txt
  CMakePresets.json
  vcpkg.json
  main.cpp

Each file has a specific job:

• main.cpp contains your C++ code.
• CMakeLists.txt tells CMake how to build the executable.
• vcpkg.json declares external dependencies like Raylib.
• CMakePresets.json stores the configure and build settings.

This structure is much cleaner than manually downloading Raylib, copying headers, linking library files, and hoping everything works.

Create the vcpkg Manifest

In the project root, create a file named vcpkg.json.

Add this content:

{
  "name": "my-raylib-project",
  "version-string": "0.1.0",
  "dependencies": [
    "raylib"
  ]
}

This file tells vcpkg that your project depends on Raylib. When you run vcpkg in manifest mode, it reads this file, downloads Raylib, builds it if needed, and makes it available to CMake.

This is the clean way to manage C++ dependencies. Instead of manually installing Raylib globally and linking it by hand, the dependency is declared directly inside your project.

Create the CMake Build File

Now create CMakeLists.txt in the project root.

Use this starter configuration:

cmake_minimum_required(VERSION 3.21)

project(MyRaylibProject LANGUAGES C CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(MyRaylibProject main.cpp)

find_package(raylib CONFIG REQUIRED)

target_link_libraries(MyRaylibProject PRIVATE raylib)

Here is what this does:

• cmake_minimum_required defines the minimum CMake version.
• project names the project and enables C and C++ languages.
• CMAKE_CXX_STANDARD sets the C++ version.
• add_executable creates an executable from main.cpp.
• find_package asks CMake to locate Raylib through vcpkg.
• target_link_libraries links Raylib to your executable.

The important part is that you should not manually add Raylib include directories or library paths. If vcpkg and CMake are configured correctly, find_package(raylib CONFIG REQUIRED) handles that for you.

Configure CMake with the vcpkg Toolchain

CMake does not automatically know where vcpkg is installed. You need to point CMake to the vcpkg toolchain file.

The toolchain file is usually here:

path-to-vcpkg/scripts/buildsystems/vcpkg.cmake

For example:

C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake

In Visual Studio Code, you can use CMake: Quick Start or create a CMakePresets.json file manually.

A simple preset can look like this:

{
  "version": 3,
  "configurePresets": [
    {
      "name": "default",
      "displayName": "Default",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/out/build/default",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "default",
      "configurePreset": "default"
    }
  ]
}

Replace the toolchain path with the real path on your machine.

This preset tells CMake three important things:

• Use Ninja as the generator.
• Put build files in out/build/default.
• Use vcpkg’s toolchain file to resolve dependencies.

Install Raylib with vcpkg

Once your vcpkg.json file exists, vcpkg knows your project needs Raylib.

From the project root, run:

vcpkg install

vcpkg will read the manifest, install Raylib, and prepare the package for CMake.

Depending on your machine and compiler setup, this may take a little time on the first run. Future runs are usually faster because dependencies are cached.

Write the First Raylib Program

Now create main.cpp in the project root.

Add this code:

#include "raylib.h"

int main()
{
    InitWindow(800, 600, "My Raylib Project");
    SetTargetFPS(60);

    while (!WindowShouldClose())
    {
        BeginDrawing();

        ClearBackground(RAYWHITE);
        DrawText("Hello from Raylib!", 200, 280, 20, BLACK);
        DrawFPS(10, 10);

        EndDrawing();
    }

    CloseWindow();

    return 0;
}

This program creates a window, runs a simple game loop, draws text, displays FPS, and closes cleanly when the window is closed.

The basic Raylib loop is easy to understand:

• InitWindow creates the window.
• SetTargetFPS limits the frame rate.
• WindowShouldClose keeps the loop running until the player closes the window.
• BeginDrawing starts the drawing phase.
• ClearBackground clears the screen.
• DrawText draws text on screen.
• DrawFPS displays frame rate.
• EndDrawing ends the frame.
• CloseWindow shuts down the window properly.

Configure, Build, and Run in Visual Studio Code

Open the CMake Tools panel in Visual Studio Code.

1. Select your configure preset.
2. Click Configure.
3. Wait for CMake to finish.
4. Click Build.
5. Run the generated executable.

If everything is correct, a Raylib window should open with the message:

Hello from Raylib!

You should also see the FPS counter in the corner.

How the Tools Work Together

This setup can feel confusing at first, so here is the simple mental model.

• vcpkg.json says what libraries your project needs.
• vcpkg downloads and prepares those libraries.
• CMakePresets.json tells CMake to use vcpkg’s toolchain.
• CMakeLists.txt defines your executable and links Raylib.
• Ninja builds the project based on CMake’s generated files.
• Visual Studio Code gives you the editor and buttons to run the workflow.

Once that clicks, C++ project setup becomes much less mysterious.

Common Problems and Fixes

Raylib Header Is Not Found

If #include "raylib.h" shows an error, CMake may not be using the vcpkg toolchain file. Check CMAKE_TOOLCHAIN_FILE inside your preset and make sure the path points to vcpkg.cmake.

CMake Cannot Find Raylib

Make sure vcpkg.json contains raylib in the dependencies list and run vcpkg install from the project root.

Ninja Is Not Found

Ninja is either not installed or not added to PATH. Run ninja --version in the terminal. If it fails, fix the installation before continuing.

CMake Cache Keeps Old Settings

Delete the build folder or use the CMake Tools command to delete cache and reconfigure. CMake can hold onto old paths, especially after changing compilers or toolchain files.

Wrong Compiler or Architecture

Make sure your compiler, vcpkg triplet, and CMake preset match. Mixing MSVC packages with a MinGW compiler, for example, can cause build or link errors.

IntelliSense Shows Errors but Build Works

This usually means Visual Studio Code IntelliSense has not caught up with CMake. Reload the window, reconfigure CMake, or make sure the C++ extension is using the compile commands generated by CMake.

Clean Project Setup Tips

If you want fewer problems in future C++ projects, follow these rules.

• Do not use spaces in project folder names.
• Keep main.cpp, CMakeLists.txt, vcpkg.json, and presets readable.
• Use one compiler setup per project until you understand toolchains better.
• Do not manually copy library files if vcpkg can manage them.
• Delete CMake cache when changing major build settings.
• Commit your config files to Git so the setup is repeatable.

The biggest beginner mistake is changing five things at once. Change one thing, reconfigure, build, and confirm. C++ setup punishes messy experimentation.

How to Expand This Project

After the basic Raylib window works, you can start turning this into a real learning project.

Add Player Movement

Use keyboard input to move a rectangle or sprite. This teaches the basics of game loops, input handling, and frame based movement.

Add Textures

Load an image file and draw it as a texture. This is the next step toward real 2D game development.

Add Audio

Raylib includes simple audio functions, so you can add sound effects and music without heavy setup.

Add More Dependencies

Once vcpkg is working, you can add more dependencies to vcpkg.json. For example, you could add libraries for formatting, physics, UI, or serialization.

Organize Source Files

Move from one main.cpp file into a proper structure with folders like src, include, and assets. Do this only after the basic setup works.

Recommended Project Structure for the Next Step

Once you move beyond the first file, a cleaner structure would look like this:

MyRaylibProject/
  assets/
  include/
  src/
    main.cpp
  CMakeLists.txt
  CMakePresets.json
  vcpkg.json

Then update CMakeLists.txt to point to src/main.cpp instead of main.cpp.

add_executable(MyRaylibProject src/main.cpp)

This keeps the project organized as it grows.

Frequently Asked Questions

Is Raylib good for learning C++ game development?

Yes. Raylib is one of the best libraries for learning game programming because it is small, readable, and does not hide everything behind a huge engine architecture.

Do I need CMake for Raylib?

Not strictly, but CMake gives you a cleaner and more scalable workflow. If you want to use external libraries properly in C++, learning CMake is worth it.

Why use vcpkg instead of manually downloading Raylib?

vcpkg makes dependencies repeatable. You declare Raylib in vcpkg.json, and the package manager handles installation and build integration.

What does Ninja do?

Ninja is a build system that executes the build files generated by CMake. It is fast and commonly used in modern C++ workflows.

Can I use this setup on macOS or Linux?

Yes, but compiler setup and vcpkg triplets differ by platform. The overall structure is the same: CMake, vcpkg, Raylib, and a compiler.

Can I use CLion instead of Visual Studio Code?

Yes. CLion has strong CMake support and can use the same CMakeLists.txt, CMakePresets.json, and vcpkg.json workflow.

Why does the setup fail after changing compiler?

CMake caches compiler and toolchain settings. Delete the build folder or clear the CMake cache before switching compilers.

Conclusion

You now have a working C++ project setup using Raylib, CMake, Ninja, vcpkg, and Visual Studio Code. This workflow gives you a clean foundation for learning game development without manually fighting include paths and linker settings.

The important lesson is not only how to run Raylib. The important lesson is understanding the connection between the tools: vcpkg manages dependencies, CMake defines the build, Ninja runs the build, and Visual Studio Code gives you the editor workflow.

Watch the full tutorial: C++ Project Setup Made Simple: Raylib, CMake, and VSCode Guide

More C++ and game development tutorials: rambod.net