Skip to content
xmake-ioPublic

About

A XMake integration in Zed Editor

Resources

Code of conduct

Contributing

Stars

18 stars

Watchers

2 watching

Forks

Repository files navigation

xmake-zed

XMake integration for Zed editor

Introduction

An XMake integration for Zed with automatic language-server installation, syntax highlighting, build tasks, and in-editor debugging.

Install xmake first and open a project that contains xmake.lua.

See the xmake repository and the website to learn the build system itself.

Features

  • Language Server (xmake_ls)

  • Syntax highlighting for the xmake APIs

  • Code Intelligence

  • Symbol Navigation

  • Build, run, and debug tasks

  • DAP locator for CodeLLDB / GDB

  • compile_commands.json generation into .zed/

  • Project Templates

  • Language server: xmake_ls, started when an xmake.lua file is open. It provides completion, diagnostics, hover, go to definition, and find references for xmake.lua

  • Outline: tree-sitter symbols for targets, options, rules, and tasks

Syntax highlighting

  • Target APIs: target, set_kind, set_version, set_description, set_default
  • File APIs: add_files, add_headerfiles, add_installfiles, remove_files
  • Include APIs: add_includedirs, add_sysincludedirs, add_defines, add_undefines
  • Linking APIs: add_links, add_linkdirs, add_syslinks, add_frameworks, add_deps
  • Compiler APIs: add_cflags, add_cxxflags, add_ldflags, set_warnings, set_optimize
  • Rule APIs: add_rules, rule, on_load, on_build, before_build, after_build
  • Option APIs: option, add_options, set_default, set_showmenu
  • Package APIs: add_requires, add_packages, add_repositories, add_requireconfs
  • Task APIs: task, on_run, set_menu
  • Utility APIs: is_plat, is_arch, is_mode, is_host, has_config, get_config
  • Global Modules: os, path, string, table, math, io, debug, coroutine, hash, utils

Platform Support

Platform Architecture Auto-Install
macOS ARM64 (Apple Silicon) ✅
macOS x64 (Intel) ✅
Linux x64 ✅
Linux ARM64 ✅
Linux RISC-V set linuxVariant to riscv64
Windows x64 ✅
Windows ARM64 ✅
Windows x86 (32-bit) ✅

Installation

  1. Open the command palette and run zed: extensions.
  2. Search for XMake and install it.

Opening xmake.lua downloads xmake_ls. Syntax highlighting uses the Lua grammar shipped with this extension. A separate Lua extension is not required.

Tasks

Zed shows tasks in task: spawn, not in the command palette. They are available while xmake.lua is the active file. To use them from a C or C++ file, copy languages/xmake/tasks.json into Zed's global tasks file yourself: ~/.config/zed/tasks.json on macOS and Linux, %APPDATA%\Zed\tasks.json on Windows. The extension does not write that file.

Optional keybinding in ~/.config/zed/keymap.json:

[
  {
    "context": "Workspace",
    "bindings": {
      "ctrl-shift-b": ["task::Spawn", { "task_name": "xmake: build" }]
    }
  }
]

Useful tasks:

Task What it runs
xmake: build xmake
xmake: run xmake run
xmake: debug configure debug mode, then build
xmake: debug in terminal debug build, then xmake run -d (lldb/gdb in the terminal)
xmake: generate compile_commands write .zed/compile_commands.json for clangd

Create tasks are listed under Creating a project.

Debugging

Zed's built-in C/C++ adapters (CodeLLDB, GDB) are used. This extension registers an xmake debug locator. It turns an xmake build or xmake run task into a debug session: the build runs first, then Zed launches the binary reported by target:targetfile().

Zed blocks that second step until this extension is allowed to run xmake. The manifest already lists process:exec. Grant it in Zed settings, then restart Zed. Without the grant the build still succeeds and the debugger reports that no locator completed.

{
  "extension": {
    "granted_extension_capabilities": [
      { "kind": "process:exec", "command": "xmake", "args": ["**"] }
    ]
  }
}

On Windows, grant xmake.exe the same way. xmake.cmd and xmake.bat are listed in the manifest for the same reason.

On macOS, CodeLLDB is told that /tmp and /var are /private/tmp and /private/var. Otherwise a binary built through one name and a breakpoint set through the other never stop.

xmake: debug is the task that matches "compile in debug mode and debug inside Zed". It runs xmake f -m debug -y, builds, and hands the binary to CodeLLDB or GDB. xmake run <target> -- args is the same flow for one target: the build step becomes xmake build <target>, and the arguments after the target are passed to the program. The program starts in the target's set_rundir, or in the binary's directory when that is unset. xmake run -w <dir> overrides it. A named target whose binary is not on disk is not replaced with a different target.

  1. Set breakpoints in the program source.
  2. Run debugger: start (debugger::Start). If the tasks are only the language tasks, xmake.lua has to be the active file. After you copy them into the global tasks file, it does not.
  3. Pick xmake: debug, xmake: build, or xmake: run.

xmake: debug in terminal uses xmake's own xmake run -d (system lldb/gdb/windbg) instead of the Zed debug adapter. It does not appear in the Zed debugger list.

IntelliSense (compile_commands.json)

xmake: generate compile_commands runs xmake project -k compile_commands --lsp=clangd .zed. That writes .zed/compile_commands.json. Ignore that file. The task also creates a .clangd file if you do not already have one:

CompileFlags:
  CompilationDatabase: .zed

If you already manage clangd yourself, set:

{
  "lsp": {
    "clangd": {
      "binary": {
        "arguments": ["--compile-commands-dir=.zed"]
      }
    }
  }
}

Creating a project

Every template from xmake create --list (xmake 3.1) is a global task named xmake: create …. You do not need xmake.lua open. xmake: create project help prints the same list from xmake.

The first create writes the project into the folder you have open, so xmake.lua is at that folder's root and build, run, and debug find it. The target is named app, or lib for a library. The folder name is not used. A folder called try would otherwise become namespace try in the C# template, and that does not compile.

A later create in that same folder does not overwrite the first project. It adds project2, then project3, and inserts includes("project2") at the top of the root xmake.lua. xmake at the root builds every included project.

Language Console Static Shared Module
C yes yes yes binary and shared
C++ yes yes yes binary and shared
C# yes yes yes
CUDA yes yes yes
D yes yes yes
Fortran yes yes yes
Go yes yes
Kotlin yes yes yes
Nim yes yes yes
Objective-C yes
Objective-C++ yes
Pascal yes yes
Rust yes yes yes
Swift yes
Vala yes yes yes
Zig yes yes yes

C and C++ also have an xmake.cli task. C++ adds Qt (console, static, shared, Quick, Quick static, widget, widget static) and wxWidgets. Objective-C adds Xcode bundle, framework, iOS app, iOS app with framework, macOS app, and macOS app with framework. Objective-C++ adds the Xcode bundle and framework.

xmake 3.1 has no TBOX create template, and Pascal has no static library template. Those tasks are not invented here.

Configuration

Using System-Installed xmake_ls

If you already have xmake_ls installed via your package manager or built from source, the extension will automatically detect and use it from your PATH.

# Example: Install from source
cargo install --git https://github.com/CppCXY/xmake_ls xmake_ls

Custom Binary Path

Override the binary location in your Zed settings (~/.config/zed/settings.json):

{
  "lsp": {
    "xmake-ls": {
      "binary": {
        "path": "/custom/path/to/xmake_ls"
      }
    }
  }
}

Linux Variant Selection

Linux users can choose their preferred binary variant. Add to your Zed settings:

{
  "lsp": {
    "xmake-ls": {
      "settings": {
        "linuxVariant": "musl"
      }
    }
  }
}

Available Linux Variants

Variant Description Best For
x64-glibc.2.17 Default for x86_64 Ubuntu 16.04+, Debian 8+, RHEL/CentOS 7+
x64 Newer glibc Recent distros (Ubuntu 20.04+, Fedora 30+)
aarch64-glibc.2.17 Default for ARM64 ARM-based servers, Raspberry Pi 3+
musl Alpine Linux libc Alpine Linux, embedded systems, containers
riscv64 RISC-V architecture RISC-V hardware

Variant Selection Guide:

  • Don't know? Leave linuxVariant as auto (x86_64 → x64-glibc.2.17, ARM64 → aarch64-glibc.2.17)
  • Alpine Linux, containers: Use musl
  • RISC-V: Set linuxVariant to riscv64 (auto does not pick RISC-V)
  • Newer x86_64 distros: Use x64

Binary Detection Priority

The extension checks for xmake_ls in the following order:

  1. Custom path from Zed settings (highest priority)
  2. System installation on the worktree PATH (xmake_ls / xmake_ls.exe)
  3. Cached download from previous extension installation
  4. Auto-download from GitHub releases (with platform/variant detection)

Troubleshooting

View Extension Logs

Run Zed from the terminal to see detailed logs:

zed --foreground

Force Re-download

Remove the cached binary to trigger a fresh download:

# macOS
rm -rf ~/Library/Application\ Support/Zed/extensions/work/xmake

# Linux
rm -rf ~/.local/share/zed/extensions/work/xmake

# Windows
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Zed\extensions\work\xmake"

Build succeeds, debugger says no locator completed

The build task runs in the terminal. The locator runs inside the extension and is refused until process:exec for xmake is granted. Add the settings block in Debugging and restart Zed.

Lua files in an xmake project

This language is Lua plus the xmake API, using the Lua grammar. Only files named xmake.lua are associated automatically. To use it for every .lua file in one project, add this to that project's .zed/settings.json yourself:

"file_types": {
  "xmake": ["/**/*.lua", "?:/**/*.lua"]
}

A build with several languages stops on one missing compiler

Projects created in the same folder are linked with includes, so xmake and xmake run build every target. error: cannot get program for cs means the saved configuration has no C# compiler. xmake looks for dotnet. Run xmake: clean configuration, then build again. xmake: Clang toolchain only saves clang as the C/C++ toolchain (xmake f --toolchain=clang -y).

Language Server Not Starting

  1. Verify xmake_ls is executable:

    xmake_ls --version
  2. Check Zed's language server status:

    • Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
    • Type "Zed: Open Log"
    • Look for xmake_ls errors
  3. Try manual installation:

    # Download for your platform from:
    # https://github.com/CppCXY/xmake_ls/releases/latest

Linux: Wrong Binary Variant

If you're getting glibc version errors, explicitly set your variant:

{
  "lsp": {
    "xmake-ls": {
      "settings": {
        "linuxVariant": "musl"
      }
    }
  }
}

How to contribute?

Please see CONTRIBUTING for details.

Resources

License

Apache License 2.0 - See LICENSE for details.

Acknowledgments

  • XMake build system by Ruki Wang
  • xmake_ls language server by CppCXY
  • Zed editor team

About

A XMake integration in Zed Editor

Resources

Code of conduct

Contributing

Stars

18 stars

Watchers

2 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages