Try doing the same on Flutter Desktop for Windows, and you will hit a brick wall.

By default, Flutter’s Windows toolchain compiles every flavor into the exact same build directory (build\windows\x64\runner\Debug\), outputs the exact same executable name, and locks native DLLs when running. Try running two flavors at once to test live socket communication, and MSBuild will fail with file-lock errors.

Here is an architectural breakdown of why this happens, how Flutter’s internal tools parse Windows builds, and how you can run multiple Windows flavors side by side with full Hot Reload and debugging.

The Core Problems

1. Build Collision and File Locks

When you run:

flutter run -d windows --flavor customer -t lib/main_customer.dart

and then try running station in another terminal, MSBuild attempts to write to the exact same directory: build\windows\x64\runner\Debug\. Because the first instance is currently running, Windows places an exclusive lock on flutter_windows.dll and the application binary. The second build crashes immediately with:

LINK : fatal error LNK1104: cannot open file '...app.exe'

2. The Infamous null.exe Crash

To isolate flavors, the natural instinct is to change the binary name dynamically in windows/CMakeLists.txt:

if(NOT "$ENV{APP_FLAVOR}" STREQUAL "")
  set(BINARY_NAME "my_app_$ENV{APP_FLAVOR}")
endif()

CMake will compile my_app_customer.exe without issues. But right after MSBuild completes, flutter run fails with:

ProcessException: Failed to find "build\windows\x64\runner\Debug\null.exe" in the search path.

Why does this happen?

Inside flutter_tools (packages/flutter_tools/lib/src/windows/build_windows.dart), Flutter uses a rigid regular expression to determine what binary it just compiled:

final RegExp binaryNameRegExp = RegExp(
  r'^\s*set\(BINARY_NAME\s*"([^"]+)"\s*\)\s*$', 
  multiLine: true,
);

Flutter doesn’t actually evaluate your CMake scripting logic. It runs a regex scan over windows/CMakeLists.txt. When you wrap set(BINARY_NAME ...) inside CMake conditionals or use string interpolations like "$ENV{APP_FLAVOR}", the regex fails to find a static literal match. It defaults to null, appends .exe, and looks for null.exe.

3. The Installation Prefix Privilege Error

When CMake runs its INSTALL target, it tries to bundle assets beside the executable. If the build directories aren't strictly isolated, or if CMake’s default prefix isn't explicitly forced to the binary directory, MSBuild falls back to Windows defaults:

file cannot create directory: C:/Program Files/your_app. Maybe need administrative privileges.

The Solution Architecture

To achieve clean, parallel debugging for multiple flavors on Windows:

1. Isolate output directories: Direct each flavor to its own folder (build\windows\x64\<flavor>\).
2. Dynamic C++ targets: Inject target properties in windows/runner/CMakeLists.txt based on the flavor environment variable.
3. Bypass the regex bug with --use-application-binary: Point Flutter directly to the compiled .exe, skipping the tool’s faulty binary discovery step.
4. Automate pre-launch validation: Use an IDE task hook (VS Code task or IntelliJ Before-Launch target) to ensure native binaries exist before launching the Dart VM.

Step 1: Patching windows/CMakeLists.txt

Open your root windows/CMakeLists.txt.

First, configure dynamic naming while keeping string compatibility safe:

# The name of the executable created for the application.
if(NOT "$ENV{APP_FLAVOR}" STREQUAL "")
  set(BINARY_NAME "my_app_$ENV{APP_FLAVOR}")
elseif(NOT "$ENV{FLUTTER_APP_FLAVOR}" STREQUAL "")
  set(BINARY_NAME "my_app_$ENV{FLUTTER_APP_FLAVOR}")
else()
  set(BINARY_NAME "my_app")
endif()

Next, locate the installation section and force CMAKE_INSTALL_PREFIX unconditionally to avoid the C:/Program Files permission trap:

# === Installation ===
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)

# Unconditionally force install prefix to the bundle directory
set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "Installation prefix" FORCE)

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")

Step 2: Isolating the Runner Output

In windows/runner/CMakeLists.txt, find the add_executable(${BINARY_NAME} ...) block. Right after the closing parenthesis ), configure the target's runtime output directories:

add_executable(${BINARY_NAME} WIN32
  "flutter_window.cpp"
  "main.cpp"
  "utils.cpp"
  "win32_window.cpp"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
  "Runner.rc"
  "runner.exe.manifest"
)

# Isolate flavor output directories
set(TARGET_FLAVOR "")
if(NOT "$ENV{APP_FLAVOR}" STREQUAL "")
  set(TARGET_FLAVOR "$ENV{APP_FLAVOR}")
elseif(NOT "$ENV{FLUTTER_APP_FLAVOR}" STREQUAL "")
  set(TARGET_FLAVOR "$ENV{FLUTTER_APP_FLAVOR}")
endif()

if(NOT "${TARGET_FLAVOR}" STREQUAL "")
  set_target_properties(${BINARY_NAME} PROPERTIES
    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/runner/${TARGET_FLAVOR}/$<CONFIG>"
    RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}/runner/${TARGET_FLAVOR}/Debug"
    RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}/runner/${TARGET_FLAVOR}/Release"
    RUNTIME_OUTPUT_DIRECTORY_PROFILE "${CMAKE_BINARY_DIR}/runner/${TARGET_FLAVOR}/Profile"
  )
endif()

Step 3: Automating Native Builds via Pre-Launch Script

Because we use --use-application-binary, Flutter expects the binary to already exist on disk. To make this completely automatic, create a lightweight PowerShell script at scripts/ensure_binary.ps1:

param(
    [Parameter(Mandatory=$true)][string]$Flavor,
    [Parameter(Mandatory=$true)][string]$Target
)

$binaryPath = "build\windows\x64\$Flavor\runner\$Flavor\Debug\my_app_$Flavor.exe"

# If binary is already compiled, skip CMake entirely
if (Test-Path $binaryPath) {
    exit 0
}

Write-Host "[Pre-Run] Native binary for '$Flavor' not found. Compiling..." -ForegroundColor Cyan

$env:APP_FLAVOR = $Flavor
flutter build windows --debug --flavor $Flavor --target $Target

if (Test-Path $binaryPath) {
    Write-Host "[Pre-Run] Binary compiled successfully." -ForegroundColor Green
    exit 0
} else {
    Write-Error "[Pre-Run] Failed to build $binaryPath."
    exit 1
}

If the .exe exists, the script exits in ~20 milliseconds. If you ran flutter clean or just cloned the repo, it compiles the native debug binary automatically before launching.

Step 4: IDE Configurations

For VS Code

Define the build check in .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Ensure customer Binary",
      "type": "shell",
      "command": "powershell.exe",
      "args": [
        "-ExecutionPolicy", "Bypass",
        "-File", "${workspaceFolder}/scripts/ensure_binary.ps1",
        "-Flavor", "customer",
        "-Target", "lib/main_customer.dart"
      ],
      "presentation": { "reveal": "silent" }
    }
  ]
}

Attach it to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Windows (Customer)",
      "request": "launch",
      "type": "dart",
      "program": "lib/main_customer.dart",
      "preLaunchTask": "Ensure customer Binary",
      "args": [
        "-d", "windows",
        "--flavor", "customer",
        "--use-application-binary=${workspaceFolder}/build/windows/x64/customer/runner/customer/Debug/my_app_customer.exe"
      ]
    }
  ],
  "compounds": [
    {
      "name": "All Flavors",
      "configurations": ["Windows (Customer)", "Windows (Station)"]
    }
  ]
}

For IntelliJ / Android Studio

Store your configurations in .idea/runConfigurations/ as project-level XML files so your entire team has them immediately.

Create .idea/runConfigurations/Ensure_customer_Binary.xml:

<component name="ProjectRunConfigurationManager">
  <configuration default="false" name="Ensure customer Binary" type="ShConfigurationType">
    <option name="SCRIPT_TEXT" value="powershell.exe -ExecutionPolicy Bypass -File &quot;$PROJECT_DIR$/scripts/ensure_binary.ps1&quot; -Flavor customer -Target lib/main_customer.dart" />
    <option name="INDEPENDENT_SCRIPT_WORKING_DIRECTORY" value="true" />
    <option name="SCRIPT_WORKING_DIRECTORY" value="$PROJECT_DIR$" />
    <method v="2" />
  </configuration>
</component>

Create .idea/runConfigurations/Windows_customer.xml:

<component name="ProjectRunConfigurationManager">
  <configuration default="false" name="Windows (Customer)" type="FlutterRunConfigurationType" factoryName="Flutter">
    <option name="additionalArgs" value="-d windows --flavor customer --use-application-binary=$PROJECT_DIR$\build\windows\x64\customer\runner\customer\Debug\my_app_customer.exe" />
    <option name="buildFlavor" value="customer" />
    <option name="filePath" value="$PROJECT_DIR$/lib/main_customer.dart" />
    <envs>
      <env name="APP_FLAVOR" value="customer" />
    </envs>
    <method v="2">
      <option name="RunConfigurationTask" enabled="true" run_configuration_name="Ensure customer Binary" run_configuration_type="ShConfigurationType" />
    </method>
  </configuration>
</component>

The Workflow in Practice

With this setup:

• Hitting Run / F5: The pre-launch script checks for the binary. If present, it skips native compilation and starts in seconds.
• Pure Dart Changes: Dart kernel compilation and debugging proceed normally. Hot Reload and Hot Restart work across all running instances without CMake interfering.
• Side-by-Side Debugging: Launching your Customer app alongside your Station app gives each instance its own runtime folder, its own DLL bundle, and its own debugging port.

No file locks, no null.exe crashes, and true multi-flavor parity on Windows.

Or… Skip the Entire Manual Setup

If reading through CMake rules, PowerShell execution bypasses, and IDE runner XMLs felt tedious, you don’t actually have to do any of this by hand.

I automated the entire workflow into an open-source CLI tool and published it to pub.dev: windows_flavourizer.

What the package handles for you:

• Auto-Discovery: Scans your project for existing main_<flavor>.dart entry points, Gradle productFlavors, or Flavorizr configurations—no need to list flavors manually if they exist.
• Scaffolding: Creates any missing lib/main_<flavor>.dart starter files automatically.
• CMake Patching: Updates root and runner CMakeLists.txt files with runtime directory isolation and forced bundle paths.
• IDE Profiles: Generates complete .vscode/ (with compound launchers) and .idea/ run configurations with attached pre-launch tasks.

Getting Started

Activate the tool globally from pub.dev:

dart pub global activate windows_flavourizer

Navigate to your Flutter project root and run:

# Automatically detects flavors and generates configs for both VS Code and IntelliJ
windows_flavourizer

# Or specify your targets and flavors explicitly
windows_flavourizer -f customer,station,rider --ide all

Reload your IDE, hit Run on your flavors, and enjoy isolated, concurrent multi-flavor debugging on Windows.

At one point, I decided to teach myself game development. However, I hit a wall early on: Unreal Engine and Unity were out of the question due to my hardware limitations. Instead of giving up, I found a YouTube channel called GamesWithGabe about making games using LWJGL3 (Lightweight Java Game Library).

That spark of curiosity led me down a rabbit hole of low-level programming. I eventually built my own engine from scratch — it could only play Mario, but it was mine, and it worked!

Eventually, I picked up Flutter because I loved the idea of building beautiful mobile apps. Flutter feels like playing with LEGO; you use widgets as building bricks to assemble your UI piece by piece. But I couldn’t stay away from graphics for long. I eventually had a “lightbulb” moment: Why not combine Flutter with computer graphics?

The final spark of inspiration came while discussing the last chapter of Flutter Engineering by Majid Hajian with my Flutter Book Club. Yes, it’s an actual club! We spend our time geeking out over everything from deep-dive backend architecture to our favorite anime—and it was that community energy that finally pushed me to hit 'publish' in this article.

What Exactly Are Shaders?

Shaders are small, specialized programs that run directly on your GPU (Graphics Processing Unit). Their job is to manipulate data to produce a final color or image on your screen.

Shaders work in a pipeline, meaning they are assembled in stages where the output of one stage becomes the input for the next. While there are several types, we usually focus on the “Big Two”:

• Vertex Shader: This is the first stage. It receives data directly from your application — things like vertices (points in 3D space), texture coordinates, and transformation matrices. Its job is to calculate the position of these points and transform them into a “normalized” form the screen can understand.
• Fragment Shader: This is the final stage, and it’s where the magic happens. It determines the color of every single pixel on your screen.

To give you an idea of the workload: if you have a standard 1920 by 1080 display, the fragment shader has to run over 2,073,600 times just to output a single frame!

Note: There are also Geometry and Tessellation shaders that can be chained in between to add even more detail, but those are a bit outside the scope of this introduction.

Shaders in the Flutter Universe

In Flutter, you don’t typically touch the vertex shader. That’s handled internally for you by the Canvas and the underlying rendering engine (like Impeller or Skia).

However, Flutter gives us the power to write our own Fragment Shaders. You can write your custom logic, attach it to a Paint object, and then wrap it all in a CustomPainter widget.

Fragment shaders are, in my opinion, the best thing since sliced bread. They allow you to replicate high-end visual effects that would be impossible with standard widgets, such as:

• Chromatic Aberration (that “glitchy” color-shift look)
• Dynamic Reflections
• Bloom and Glow effects

What’s Next?

Now that we have the theory down, it’s time to get our hands dirty. In this article, we’re going to walk through how to set up a fragment shader in Flutter, pair it with a CustomPainter, and render a procedural checkerboard pattern on the screen.

Ready? Let’s dive in.

That “bridge” between your code and the GPU can feel a bit abstract at first, but in Flutter, it follows a very specific hand-off process.

Think of it as a relay race: your Shader has the data, the Paint object holds the instructions, and the CustomPainter is the athlete that actually runs the race on the screen.

1. The CustomPainter (The Logic)

The CustomPainter is a class where you tell Flutter what to draw. It gives you a Canvas (your drawing surface) and a Size (how much space you have).

import 'package:flutter/material.dart';

class CheckerboardPainter extends CustomPainter {
  final FragmentShader shader;

  CheckerboardPainter(this.shader);

  @override
  void paint(Canvas canvas, Size size) {
    // 1. Create a Paint object
    final paint = Paint();

    // 2. Attach your shader to the paint object
    // This tells the GPU: "Use this shader program for whatever I draw next"
    paint.shader = shader;

    // 3. Draw a rectangle that covers the whole area
    canvas.drawRect(Rect.fromLTWH(0, 0, size.width, size.height), paint);
  }

  @override
  bool shouldRepaint(covariant CustomPainter oldDelegate) => true;
}

2. The Paint Object (The Bridge)

The Paint object is the most important part of this equation. It’s not just a "color" picker; it's a configuration object for the specialized hardware. When you say paint.shader = shader, you are effectively uploading your custom code to the GPU's "instruction manual" for that specific draw call.

3. The CustomPaint Widget (The Canvas)

Finally, you need to actually put this on your UI tree. You use the CustomPaint widget to give your painter a home.

// Inside your Widget build method:
CustomPaint(
  size: Size(300, 300), // How big the "canvas" should be
  painter: CheckerboardPainter(myLoadedShader),
)

Now that the basics has been set up, we would need to make some minor changes to our pubspec.yaml file. For this example, we would be adding a shader called checkerboard.frag

flutter:

  shaders:
    - shaders/checkerboard.frag

Then we would need to create a FlutterProgram which contains the FragmentShader.

import 'dart:developer' show log;
import 'dart:ui';

class ShaderFactory {
  static Future<FragmentShader?> loadShader(String shaderName) async {
    try {
      FragmentProgram program = await FragmentProgram.fromAsset(
        'packages/my_awesome_shader_app/shaders/$shaderName',
      );
      return program.fragmentShader();
    } catch (e) {
      log('Failed to load shader $shaderName: $e');
      return null;
    } 
  }
}

Note: I used my_awesome_shader_app as it is the actual name of the project as specified in pubspec.yaml.

The Final Piece: Uniforms and Memory Locations

We are almost at the finish line! But there is one more piece of the puzzle: How do we send data from our Flutter code to the shader?

Suppose you want to change the colors of your checkerboard dynamically without rebuilding the entire app. You need a way to "talk" to the GPU while it’s running. The answer is Uniforms.

Think of a Uniform as a constant variable that you send directly from your CPU (Dart code) to the GPU. It’s "uniform" because its value stays the same for every single pixel processed during a single draw call.

1. Data Types and "Packing"
   Uniforms can handle various data types: float, int, vectors, and matrices.
   A color is usually represented as RGBA or RGB. While you could send three separate floats for Red, Green, and Blue, it’s much cleaner to pack them into a single vec3 (a 3-component vector).
2. The Concept of "Locations"
   This is the part where you need to pay close attention. When you send data to a shader in Flutter, you have to tell it exactly where that data should go.

You can think of Uniform Locations as specific slots in memory. In Flutter’s fragment shaders, these locations are index-based and start at 0.

Here is the kicker: Locations are based on floats.

• If you send one float, it takes up index 0.
• If you send a vec3 (which contains 3 floats), it occupies indices 0, 1, and 2.
• The next uniform you send would then start at index 3.

Why this matters: When you use the setFloat(index, value) method in Dart, you aren't just pointing to a variable name; you are pointing to a specific spot in the GPU's memory "waiting room." If you get the index wrong, your colors will look... well, very weird.

For our checkerboard, we’ll need two vec3 uniforms—one for each of our alternating colors.

Putting it into Practice: The Checkerboard Shader

Enough with the theory—let’s get our hands on some code. To build our checkerboard, we’re going to use a bit of math to tell the GPU how to decide which color belongs on which pixel.

We’ll be using the gl_FragCoord, which gives us the precise coordinates of the pixel currently being processed. By dividing these coordinates into "tiles" and using some clever arithmetic, we can create a repeating pattern without using a single image asset.

We will also be adding one extra uniform uResolution, which is also size of the canvas being drawn.

Here is the GLSL code for our procedural checkerboard:

#version 320 es
precision mediump float;

// These are our uniforms. 
// Remember: color1 starts at location 0, color2 starts at location 3!
layout(location = 0) uniform vec3 uColor1;
layout(location = 3) uniform vec3 uColor2;
layout(location = 6) uniform vec2 uResolution;

out vec4 fragColor;

void main() {
    // 1. Define the size of our squares (in pixels)
    float tileSize = 50.0;

    // 2. Determine which "grid cell" the current pixel belongs to
    // We divide the coordinate by the tile size and use floor() 
    // to get integer steps (0, 1, 2, 3...)
    vec2 grid = floor(gl_FragCoord.xy / tileSize);

    // 3. The Checkerboard Math
    // By adding the X and Y grid positions and using mod 2, 
    // we get a flipping pattern of 0.0 and 1.0
    float check = mod(grid.x + grid.y, 2.0);

    // 4. Pick the color based on the result
    // If check is 0, we use color1. If it's 1, we use color2.
    vec3 finalColor = mix(uColor1, uColor2, check);

    fragColor = vec4(finalColor, 1.0);
}

Why the mod() function?

The mod() (modulo) function is the secret sauce of procedural patterns. In our case, mod(grid.x + grid.y, 2.0) calculates the remainder of our grid sum divided by 2.

Imagine moving across the screen:

At grid cell (0,0), the sum is 0. 0 % 2 = 0.

At grid cell (1,0), the sum is 1. 1 % 2 = 1.

At grid cell (1,1), the sum is 2. 2 % 2 = 0.

This creates that classic alternating "0, 1, 0, 1" pattern both horizontally and vertically, which perfectly maps to our two colors.

Writing code like this is why my ‘Mario engine’ could run on almost anything — procedural graphics are incredibly lightweight compared to loading heavy textures!

Wiring up the shader

The last thing we need to do is to send over the uniforms to the fragment shader.

void setCustomUniforms(FragmentShader shader, List<Color> colors) {
    int floatIndex = 0;
    
    // Sending over uColor1
    shader.setFloat(floatIndex++, colors[0].r);
    shader.setFloat(floatIndex++, colors[0].g);
    shader.setFloat(floatIndex++, colors[0].b);

    // Sending over uColor2
    shader.setFloat(floatIndex++, colors[1].r);
    shader.setFloat(floatIndex++, colors[1].g);
    shader.setFloat(floatIndex++, colors[1].b);

    // Sending over uResolution
    shader.setFloat(floatIndex++, 300.0); // width of the canvas
    shader.setFloat(floatIndex++, 300.0); // height of the canvas
  }

After everything has been wired together and you run your app, you should see this beautiful pattern.

What Next?

This checkerboard is just the tip of the iceberg. Now that you’ve seen how to bridge the gap between Dart and the GPU, the possibilities are limited only by your imagination.

Shaders aren't just for static patterns; they are the key to high-performance, cinematic UI. You can take this implementation much further by exploring these areas:

• Time-Based Animations: Pass a uTimeuniform to create flowing gradients, pulsing glows, or shifting colors.
• Interactive Visuals: Use a GestureDetectorto feed touch coordinates into your shader, making your UI react physically to the user's finger.
• Advanced Masking: Combine CustomPaint with ClipPath to create unique, procedurally generated shapes that would be impossible with standard widgets.

The world of computer graphics is vast and vibrant. By mastering fragment shaders, you’re moving beyond simply "using" a framework and starting to paint directly onto the screen's hardware.

Final Thought: Whether you’re building a simple app or a complex game engine, remember that every pixel is a canvas. Don't be afraid to experiment, break things, and see what happens when you push the GPU to its limits.

Till next time—Happy Fluttering!

What’s the first shader effect you’re planning to build?