xmake-vscode

A XMake integration in Visual Studio Code

Introduction

A XMake integration in Visual Studio Code.

You need install xmake first and a project with xmake.lua.

Please see xmake-github and website if you want to know more about xmake.

Features

Project Management: Create new projects, add files, and manage project structure
Language Support: Colorization and syntax highlighting for xmake.lua files
IntelliSense: Auto-completion for XMake APIs and functions
Status Bar: Quick access to build configuration and actions
Command Palette: Full integration with VS Code commands
Configuration Management: Configure platforms, architectures, toolchains, and build modes
Build System: Build, rebuild, clean, and package projects
Run and Debug: Integrated debugging with multiple debugger support
Problem Detection: Real-time error and warning detection
Macro Recording: Record and playback command sequences
File Explorer: Dedicated XMake project explorer with target management
Task Integration: VS Code tasks support for XMake commands

Quickstart

Colorization and Completion Lists

StatusBar

statusbar

Commands

Configuration

Build

Run and Debug

Record and Playback

Problem

IntelliSense

xmake-vscode will generate .vscode/compile_commands.json file, so you need only add it to .vscode/c_cpp_properties.json to enable IntelliSense.

Automatic Generation Modes

The extension provides three modes for automatic generation of compile_commands.json:

onFileChange (default): Generate compile_commands.json when xmake.lua files change
onBuild: Generate compile_commands.json after building the project
disabled: Disable automatic generation (manual generation via "XMake: UpdateIntellisense" command is still available)

You can configure this in VSCode settings with xmake.autoGenerateCompileCommands.

for example (.vscode/c_cpp_properties.json):

{
    "configurations": [
        {
            "compileCommands": ".vscode/compile_commands.json"
        }
    ],
    "version": 4
}

How can I generate c_cpp_properties.json?

These configuration settings are stored in your project's c_cpp_properties.json file. To edit this file, in VS Code, select C/C++: Edit Configurations (UI) from the Command Palette (⇧⌘P):

Please see IntelliSense for cross-compiling

Debugging

Debug via launch configurations (launch.json) is accessible only with Run->Start Debugging (not F5 keybinding) or via Launch Debug command.

attribute	type
name	string	Required. Launch configuration name, as you want it to appear in the Run and Debug panel.
type	string	Required. Set to `xmake`.
request	string	Required. Session initiation method:`launch` or `attach`.
target	string	Required. XMake target.
env	object	Additional environment variables. `{"PATH" : "some/path"}`
args	string ❘ [string]	Command line parameters. If not defined args are taken from `debuggingTargetsArguments` config.
cwd	string	If not defined xmake will use the target directory.
stopAtEntry	boolean	If set to true, the debugger should stop at the entry-point of the target (ignored on attach). Default value is false.
terminal	string	Destination of stdio streams: `console` for Debug Console `integrated` (default) for VSCode integrated terminal `external` for a new terminal window `newExternal` for a new terminal window but only with cli application (only cpptools / with lldb it will be converted to `external`)

Example:

{
    "configurations": [
    {
       "name": "XMake Debug",
        "type": "xmake",
        "request": "launch",
        "target": "example",
        "stopAtEntry": true
    }
  ]
}

Debugger extension

You can choose the debugger extension with xmake.debugConfigType, set it to:

default for cpptools debugger
codelldb for lldb debugger

Envs behaviour

You can choose the behaviour between xmake envs and envs that are defined in launch.json For an xmake envs that are like this {"PATH: "path/from/xmake"} and in launch.json {"PATH": "path/from/config"}.

Default is merge.

With xmake.envBehaviour set to merge, the result is: {"PATH": "path/from/xmake;path/from/config"}.
With xmake.envBehaviour set to erase, the result is: {"PATH": "path/from/xmake"}
And with xmake.envBehaviour set to override, the result is: {"PATH": "path/from/config"}.

XMake envs will only be replaced for the same key, if another xmake env key is present, it will be present in the final result.

Global Configuration

We can configure them in settings.json

Basic Configuration

{
    "xmake.executable": "xmake",
    "xmake.logLevel": "normal",
    "xmake.buildLevel": "normal",
    "xmake.buildDirectory": "${workspaceRoot}/build",
    "xmake.workingDirectory": "${workspaceRoot}"
}

Advanced Configuration

{
    "xmake.executable": "xmake",
    "xmake.logLevel": "normal",
    "xmake.buildLevel": "normal",
    "xmake.buildDirectory": "${workspaceRoot}/build",
    "xmake.installDirectory": "",
    "xmake.packageDirectory": "",
    "xmake.workingDirectory": "${workspaceRoot}",
    "xmake.androidNDKDirectory": "",
    "xmake.QtDirectory": "",
    "xmake.WDKDirectory": "",
    "xmake.compileCommandsDirectory": ".vscode",
    "xmake.compileCommandsBackend": "clangd",
    "xmake.additionalConfigArguments": [],
    "xmake.runningTargetsArguments": {
        "default": []
    },
    "xmake.debuggingTargetsArguments": {
        "default": []
    },
    "xmake.debugConfigType": "default",
    "xmake.customDebugConfig": {},
    "xmake.envBehaviour": "merge",
    "xmake.enableSyntaxCheck": true,
    "xmake.runMode": "runOnly"
}

Status Bar Configuration

Control which buttons appear in the status bar:

{
    "xmake.status.showProject": false,
    "xmake.status.showXMake": true,
    "xmake.status.showPlatform": false,
    "xmake.status.showArch": false,
    "xmake.status.showMode": false,
    "xmake.status.showToolchain": false,
    "xmake.status.showTarget": false,
    "xmake.status.showBuild": true,
    "xmake.status.showRun": true,
    "xmake.status.showDebug": true
}

Configuration Options Details

Option	Type	Default	Description
xmake.executable	string	"xmake"	The xmake executable name / path
xmake.logLevel	string	"normal"	Log Level: `verbose`, `normal`, `minimal`
xmake.buildLevel	string	"normal"	Build Output Level: `verbose`, `normal`, `debug`
xmake.runMode	string	"runOnly"	Run Mode: `runOnly`, `buildRun`
xmake.buildDirectory	string	"${workspaceRoot}/build"	Build Output Directory
xmake.installDirectory	string	""	Install Output Directory
xmake.packageDirectory	string	""	Package Output Directory
xmake.workingDirectory	string	"${workspaceRoot}"	Project Working Directory
xmake.androidNDKDirectory	string	""	Android NDK Directory
xmake.QtDirectory	string	""	Qt Directory
xmake.WDKDirectory	string	""	Windows Driver Kit Directory
xmake.compileCommandsDirectory	string	".vscode"	compile_commands.json file directory
xmake.compileCommandsBackend	string	"clangd"	LSP backend for compile_commands
xmake.autoGenerateCompileCommands	string	"onFileChange"	Automatic generation mode: `onFileChange`, `onBuild`, `disabled`
xmake.additionalConfigArguments	array	[]	Additional config arguments, e.g. `["--cc=gcc", "--myopt=xxx"]`
xmake.runningTargetsArguments	object	{"default": []}	Running targets arguments, e.g. `{"targetName": ["args", "..."]}`
xmake.debuggingTargetsArguments	object	{"default": []}	Debugging targets arguments
xmake.debugConfigType	string	"default"	Debug configuration type: `default`, `codelldb`, `lldb-dap`, `gdb-dap`
xmake.customDebugConfig	object	{}	Custom debugging configurations
xmake.envBehaviour	string	"merge"	Environment behaviour: `erase`, `merge`, `override`
xmake.enableSyntaxCheck	boolean	true	Enable Lua syntax check

XMake Explorer

The extension provides a dedicated XMake Explorer in the Activity Bar for project management.

Features

Project Overview: View all targets and their configurations
Target Management: Build, rebuild, clean, run, and debug individual targets
Configuration Panel: Quick access to platform, architecture, mode, and toolchain settings
Context Menu: Right-click actions for quick operations

Explorer Actions

Build All: Build all targets in the project
Rebuild All: Clean and build all targets
Clean All: Clean all build artifacts
Run All: Run all executable targets
Configure: Open configuration settings

Available Commands

Access all XMake commands through the Command Palette (Ctrl+Shift+P or Cmd+Shift+P):

Project Commands

XMake: CreateProject: Create a new XMake project
XMake: NewFiles: Add new files to the project
XMake: Show Explorer: Show/hide the XMake Explorer

Configuration Commands

XMake: Configure: Configure the project
XMake: Clean Configure: Clean and reconfigure the project
XMake: Set Target Platform: Set the target platform
XMake: Set Target Architecture: Set the target architecture
XMake: Set Build Mode: Set the build mode (debug/release)
XMake: Set Default Target: Set the default target
XMake: toolchain: Set the toolchain

Build Commands

XMake: Build: Build the current target
XMake: BuildAll: Build all targets
XMake: Rebuild: Rebuild the current target
XMake: Clean: Clean the current target
XMake: CleanAll: Clean all targets

Run and Debug Commands

XMake: Run: Run the current target
XMake: BuildRun: Build and run the target
XMake: Debug: Start debugging
XMake: Launch Debug: Launch with debugger

Package and Install Commands

XMake: Package: Package the project
XMake: Install: Install the project
XMake: Uninstall: Uninstall the project

Utility Commands

XMake: BeginMacro: Start recording commands
XMake: EndMacro: Stop recording commands
XMake: RunMacro: Run recorded macro
XMake: RunLastCommand: Repeat the last command
XMake: UpdateIntellisense: Update IntelliSense configuration

Task Integration

The extension supports VS Code tasks for XMake operations. Create a .vscode/tasks.json file:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "XMake: Build",
            "type": "xmake",
            "task": "build",
            "problemMatcher": ["$gcc"],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "XMake: Clean",
            "type": "xmake",
            "task": "clean",
            "problemMatcher": []
        },
        {
            "label": "XMake: Run",
            "type": "xmake",
            "task": "run",
            "problemMatcher": []
        }
    ]
}

Available Task Types

build: Build the project
clean: Clean build artifacts
run: Run the target
package: Package the project
install: Install the project
configure: Configure the project

Key Bindings

The extension provides the following default key bindings:

Key	Command	Description
`F5`	`xmake.onDebug`	Start debugging (when xmake is enabled)

You can customize these key bindings in VS Code preferences.

Platform-Specific Configuration

The extension supports platform-specific configuration. You can use platform prefixes in your settings:

{
    "xmake.executable": "xmake",
    "windows.xmake.executable": "xmake.exe",
    "linux.xmake.executable": "/usr/bin/xmake",
    "osx.xmake.executable": "/usr/local/bin/xmake"
}

Supported platform prefixes:

windows for Windows
linux for Linux
osx for macOS

Troubleshooting

Common Issues

XMake not found

Ensure XMake is installed and accessible in your system PATH
Use xmake.executable setting to specify the full path to xmake executable

IntelliSense not working

Check your xmake.autoGenerateCompileCommands setting:
- Set to onFileChange to generate when xmake.lua changes
- Set to onBuild to generate after building
- Set to disabled and use XMake: UpdateIntellisense command manually
Run XMake: UpdateIntellisense command to generate compile_commands.json manually
Ensure your .vscode/c_cpp_properties.json references the correct compile commands file
Check that the C/C++ extension is installed and enabled

Debugging not working

Verify your launch.json configuration has the correct target name
Check that the debugger extension (C/C++ or CodeLLDB) is installed
Ensure the debug configuration type matches your debugger extension

Build fails

Check the output panel for detailed error messages
Verify your xmake.lua configuration is correct
Ensure all required dependencies and tools are installed

Getting Help

Documentation: XMake Official Documentation
Issues: GitHub Issues
Community:
- Reddit
- Discord
- Telegram
- QQ Group

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Donation

If you find this extension helpful, consider supporting the project:

XMake

tboox

xmake-vscode

Introduction

Features

Quickstart

Colorization and Completion Lists

StatusBar

Commands

Configuration

Build

Run and Debug

Record and Playback

Problem

IntelliSense

Automatic Generation Modes

How can I generate c_cpp_properties.json?

Debugging

Configurations related to debugging

Debugger extension

Envs behaviour

Global Configuration

Basic Configuration

Advanced Configuration

Status Bar Configuration

Configuration Options Details

XMake Explorer

Features

Explorer Actions

Available Commands

Project Commands

Configuration Commands

Build Commands

Run and Debug Commands

Package and Install Commands

Utility Commands

Task Integration

Available Task Types

Key Bindings

Platform-Specific Configuration

Troubleshooting

Common Issues

Getting Help

Contributing

License

Donation