unreal-clang

English | 简体中文

A VS Code extension that resolves intermediate build-product conflicts in Unreal Engine projects when MSVC is used for compiling and debugging while Clang/clangd is used for code intelligence (completion, navigation, diagnostics).

It runs UnrealBuildTool's GenerateClangDatabase mode for you, then rewrites the generated compile_commands.json and response files so that all Clang intermediates are redirected into an isolated directory and never overwrite the artifacts produced by your MSVC builds.

The Problem

A common UE workflow on Windows is:

• Build and debug the project with the MSVC toolchain (Visual Studio / Rider).
• Use clangd inside VS Code for fast, accurate code intelligence, which requires a compile_commands.json compilation database.

Generating that database with UnrealBuildTool -mode=GenerateClangDatabase -Compiler=Clang makes Clang emit its own intermediate products — object files (.obj), forced-include headers (/FI), precompiled headers, and nested response (.rsp) files — into the same Build intermediate directories that MSVC uses. The two toolchains then overwrite each other's products, triggering unnecessary full rebuilds when switching between debugging and code-intelligence workflows.

How It Works

The Unreal Clang Setup command performs the whole pipeline:

1. Resolves and validates the UnrealBuildTool path (it must respond to --help).
2. Resolves the .uproject path — from settings, or by auto-detecting a .uproject file in the workspace root.
3. Invokes UnrealBuildTool to generate the Clang compilation database:

   UnrealBuildTool -mode=GenerateClangDatabase -project="<Project>.uproject" \
     -Target="<Project>Editor Win64 Development" \
     -OutputDir="<ProjectRoot>/build" \
     -Compiler="Clang" [-CompilerVersion="<version>"]
   

4. Post-processes the generated <ProjectRoot>/build/compile_commands.json:
   • For every compile command, the referenced .rsp response file is parsed and a rewritten copy is written to <ProjectRoot>/Build/.UnrealClang/.
   • Nested response-file references (@file.rsp) and forced-include directives (/FI"...") are redirected into the isolated directory; the referenced files are physically moved there.
   • Object output paths (/Fo"...") are redirected into the isolated directory so Clang objects never collide with MSVC objects.
   • Duplicate base names are de-conflicted automatically (Name.rsp, Name_1.rsp, ...).
   • The compile command in compile_commands.json is updated to point at the rewritten response file.
5. Restarts the clangd language server (if installed and active) so the new database is picked up immediately.

After setup, MSVC builds and Clang-based code intelligence coexist without clobbering each other's intermediates.

Features

• One-command clang database generation via UnrealBuildTool.
• Automatic isolation of Clang intermediate products (response files, forced includes, object files).
• Auto-detection of the .uproject file in the workspace root.
• Configurable compiler and compiler version.
• Progress notification with cancellation support; concurrent runs are prevented.
• Detailed logs in the Unreal Clang output channel.
• Automatic clangd restart after a successful setup.

Requirements

• Windows (the workflow targets Win64 and MSVC/Clang toolchains).
• Unreal Engine with a working UnrealBuildTool (must be on PATH or configured explicitly).
• The clangd VS Code extension for code intelligence (recommended).
• VS Code ^1.130.0.

Usage

1. Open the root directory of your Unreal project (the folder containing the .uproject file) in VS Code, or set the project path explicitly in settings.
2. Make sure UnrealBuildTool is reachable — either on your PATH or configured via the unreal-clang.UnrealBuildTool.path setting.
3. Open the Command Palette (Ctrl+Shift+P) and run Unreal Clang Setup.
4. Wait for the progress notification to finish. On success clangd restarts automatically and code intelligence is ready.

If a path cannot be resolved, an error message is shown; check the Unreal Clang output channel for the exact UnrealBuildTool invocation and failure details.

Extension Settings

Generated Artifacts

On Windows the filesystem is case-insensitive, so build and Build refer to the same directory.

Development

The extension is written in TypeScript (ESM), bundled with Vite, and packaged with pnpm.

Project Structure

.
├── src
│   ├── main.ts       # Extension entry point; registers the setup command
│   ├── commands.ts   # "Unreal Clang Setup" command with progress/cancellation
│   ├── Processor.ts  # Rewrites compile_commands.json and .rsp files
│   ├── util.ts       # UBT invocation, path validation, clangd restart helpers
│   ├── constant.ts   # Constants and user-facing tips
│   └── logger.ts     # Output-channel logger ("Unreal Clang")
├── test
│   └── main.test.ts  # Extension tests (run under vscode-test/Mocha)
├── vite.config.ts    # Vite (Node/ES) bundle configuration
└── package.json      # Extension manifest, commands and settings

Scripts

To debug locally, open the repository in VS Code and press F5 to launch an Extension Development Host, then run Unreal Clang Setup from the Command Palette.