Getting started with Mesa

Mesa is intimidating at first—it's a huge codebase with multiple drivers, compiler infrastructure, and decades of history. But it's also well-organized once you understand the structure. Here's what I've learned while getting started with Mesa contribution.

Understanding the codebase

Mesa's source tree is organized by driver and component. The main directories you'll care about:

• src/amd/ — AMD-specific code (RADV, RadeonSI, ACO compiler)
• src/intel/ — Intel drivers and compiler
• src/compiler/nir/ — NIR intermediate representation
• src/vulkan/ — Common Vulkan code shared between drivers
• src/gallium/ — Gallium driver infrastructure

If you're working on AMD Vulkan (RADV), you'll spend most of your time in src/amd/vulkan/ for the driver code and src/amd/compiler/ for ACO.

Building Mesa

Mesa uses Meson as its build system. Basic build:

meson setup build -Dvulkan-drivers=amd -Dgallium-drivers= -Dbuildtype=debug
ninja -C build

The -Dvulkan-drivers=amd builds only RADV (faster than building everything). Debug builds include symbols and assertions which are essential when you're learning the code.

To use your custom Mesa build without installing it system-wide, set these environment variables:

export VK_ICD_FILENAMES=/path/to/build/src/amd/vulkan/radeon_icd.x86_64.json
export LD_LIBRARY_PATH=/path/to/build/src/amd/vulkan:$LD_LIBRARY_PATH

Reading the code

Start by tracing a simple API call. For example, in RADV:

• vkCreateGraphicsPipelines is in radv_pipeline.c
• This calls into shader compilation in radv_shader.c
• Which eventually calls ACO in aco_interface.cpp
• ACO does instruction selection, optimization, register allocation
• Final binary is embedded in the pipeline object

Following the code path for one operation teaches you how the pieces fit together. Use grep and cscope liberally.

Debugging tools

Mesa has extensive debugging infrastructure via environment variables:

• RADV_DEBUG=shaders — Dumps shader assembly
• RADV_DEBUG=checkir — Validates NIR after each pass
• ACO_DEBUG=validateir — Validates ACO IR
• NIR_PRINT=1 — Prints NIR before compilation

These are invaluable for understanding what the compiler is doing. When something breaks, comparing the shader dumps before and after your change tells you exactly what went wrong.

RenderDoc for graphics debugging

RenderDoc is essential for debugging graphics issues. It captures a frame, shows you every draw call, lets you inspect pipeline state, shader inputs/outputs, and even debug shaders step-by-step.

When a game renders incorrectly, RenderDoc shows you which draw call is wrong, what shaders are running, what textures are bound, etc. Much faster than print debugging.

Making your first contribution

Start small. Look for:

• Compiler warnings in the build output
• TODOs in the code
• Issues tagged "good first issue" on GitLab
• Documentation improvements

My first kernel patch was fixing old unused code that generated warnings. Trivial fix, but it taught me the patch submission workflow and how to respond to maintainer feedback.

For Mesa, the process is:

• Make your changes
• Run meson test to verify you didn't break anything
• Format your commit message properly (check existing commits for style)
• Push to GitLab and create a merge request
• Wait for CI and reviewer feedback

Be prepared for feedback. Maintainers will ask you to change things, restructure commits, or explain your reasoning. This is normal and how you learn to write better code.

Community interaction

Join the Matrix channels:

• #radv:matrix.org — RADV development
• #dri-devel:matrix.org — General Mesa development
• #nir:matrix.org — Compiler discussions

Don't be afraid to ask questions. The community is helpful as long as you've done your homework first (read the code, tried debugging, searched the issue tracker).

What I'm learning

I'm currently studying ACO's register allocator and instruction scheduler. The code is cleaner than I expected—good variable names, reasonable comments, clear structure.

What's interesting is seeing compiler theory applied to real hardware constraints. Textbook compiler courses teach you register allocation as graph coloring, but ACO has to deal with:

• Multiple register files (VGPR vs SGPR on AMD)
• Variable register sizes (wave32 vs wave64 mode)
• Latency hiding through high register usage
• Spilling to scratch memory when you run out

The gap between theory and practice is where interesting problems live.