Xmake Build Utility

xmake is a lightweight, cross-platform build utility based on Lua. It functions as a combined Build backend, Project Generator, Package Manager, and supports Remote/Distributed builds and Caching.

It is designed to be a modern alternative to Make/Ninja, CMake/Meson, and package managers like Vcpkg/Conan, providing a concise and intuitive configuration syntax via xmake.lua files.

Use the github-action-setup-xmake action to install XMake in your CI environment.

uses: xmake-io/github-action-setup-xmake@v1
with:
  xmake-version: latest

You can install xmake using one-line scripts for various environments. For other methods like building from source or using system package managers, refer to the official Installation Guide.

### With cURL
```bash
curl -fsSL https://xmake.io/shget.text | bash

With Wget

wget https://xmake.io/shget.text -O - | bash

With PowerShell

irm https://xmake.io/psget.text | iex

Use the github-action-setup-xmake action to quickly set up the Xmake environment in your CI pipeline.

uses: xmake-io/github-action-setup-xmake@v1
with:
  xmake-version: latest

Use the xmake-gradle plugin to integrate native C/C++ library compilation into an Android/Gradle build process. Once applied, xmakeBuild tasks are automatically injected into the standard assemble tasks.

plugins {
  id 'org.tboox.gradle-xmake-plugin' version '1.1.5'
}

android {
    externalNativeBuild {
        xmake {
            path "jni/xmake.lua"
        }
    }
}

Xmake uses a caching mechanism to avoid unnecessary reconfigurations. A reconfiguration (recheck) is triggered if:

1. The --clean or --check flag is used.
2. Project files (tracked via mtimes) have been modified.
3. The recheck flag is set in the local cache.
4. The Xmake core files have been updated (detected via os.mtime of core/main.lua).
5. The host system has changed.

When a recheck is triggered, Xmake clears several caches, including config, detect, option, package, and toolchain, to ensure a consistent build environment.

When using the --files option, you can provide space-separated or environment-variable-expanded patterns. You can also specify files to exclude by using the pipe | character within the pattern string.

Pattern Syntax:

• path/to/*.cpp: Matches all .cpp files in a directory.
• path/to/*.cpp|path/to/exclude/*.cpp: Matches .cpp files but excludes those in the specified directory.

Note: The plugin translates these patterns into Lua patterns for matching against the project's source and header files.

xmake format --files="src/*.cpp|src/third_party/*.cpp"

If a specific project file is not provided via -F or --file, xmake uses a search algorithm to find the root xmake.lua:

1. It starts from the directory of the provided file (or the current working directory).
2. It traverses upwards through parent directories.
3. It returns the first directory in the hierarchy that contains an xmake.lua file.
4. If no such file is found, it defaults to the provided file path.

When using the AppImage packaging plugin, keep the following requirements in mind:

• Platform: Only supported on Linux.
• Main Executable: The package must contain at least one binary target. The plugin attempts to find the executable in the usr/bin directory of the installation root or by searching the bindir.
• Icon Files: Supported formats are strictly .png, .svg, or .xpm. If an iconfile is provided, it must exist at the specified path.
• Tooling: The plugin requires appimagetool. If not found on the system, it will attempt to install it via the appimage package set.

The runself plugin is a packaging mechanism for Xmake that uses makeself to create self-extracting shell script archives. It is designed for Unix-like systems (it returns early on Windows).

When a package is packed using runself, the plugin:

1. Locates or installs makeself.sh.
2. Generates a .lsm specfile with variables replaced from the package's specvars.
3. Archives the package's source files and components.
4. Generates a __setup__.sh script containing the installation commands (e.g., cp, rm, mkdir, mv, cd) defined in the package.
5. Invokes makeself with --gzip, --sha256, and --lsm flags to produce the final output file.

Note: This plugin is intended to be used within the Xmake packaging framework via the pack plugin system.

The WiX plugin translates Xmake installation commands into WiX XML elements. This allows your standard install rules to drive the MSI creation:

Note on cp (Copy): The plugin automatically groups files destined for the same directory into a single WiX <Component> to ensure efficient installation and proper GUID management.