Xmake Env Vars

Xmake Environment Variables

Xmake reads a handful of XMAKE_* environment variables to relocate config, enable profiling, load user-wide defaults, and more. They take precedence over the matching xmake g global setting when both are present.

List them all

xmake show -l envs

Shows every recognized variable, its description, and the currently resolved value on your system.

Reference

Paths

| Variable | Purpose | Default | | --- | --- | --- | | XMAKE_PROGRAM_DIR | Where xmake's Lua scripts live | xmake install dir | | XMAKE_PROGRAM_FILE | Which xmake binary to use | resolved from PATH | | XMAKE_GLOBALDIR | Root for xmake g global config (creates .xmake/ inside) | ~ | | XMAKE_CONFIGDIR | Where per-project .xmake/ cache goes | project dir | | XMAKE_TMPDIR | Temp scratch | /tmp/.xmake / %TEMP%\.xmake | | XMAKE_RAMDIR | Optional ramdisk for temp files — fastest | unset | | XMAKE_PKG_INSTALLDIR | Package install root | $XMAKE_GLOBALDIR/.xmake/packages | | XMAKE_PKG_CACHEDIR | Package cache dir | $XMAKE_GLOBALDIR/.xmake/cache | | XMAKE_LOGFILE | Log everything xmake does to this file | unset |

Typical uses:

# Use a local source checkout of xmake (developing xmake itself — see xmake-dev skill)
export XMAKE_PROGRAM_DIR=/path/to/xmake/xmake
export XMAKE_PROGRAM_FILE=/path/to/xmake/core/build/xmake

# Keep project .xmake out of the repo root
export XMAKE_CONFIGDIR=/tmp/myproject-xmake

# Put packages on a fast disk
export XMAKE_PKG_INSTALLDIR=/mnt/fast/xmake-packages
export XMAKE_PKG_CACHEDIR=/mnt/fast/xmake-cache

# Ram-disk temp for crazy-fast configures
export XMAKE_RAMDIR=/dev/shm/xmake

Output / behavior

| Variable | Values | Purpose | | --- | --- | --- | | XMAKE_COLORTERM | nocolor / color8 / color256 / truecolor | Force color mode | | XMAKE_PROFILE | stuck / trace / perf:call / perf:tag / perf:process | Profiling / stuck debug — see xmake-troubleshooting | | XMAKE_ROOT | y | Allow running as root (off by default — unsafe) | | XMAKE_LOGFILE | path | Mirror xmake output to a log file | | XMAKE_THEME | theme name | Equivalent to xmake g --theme=... |

User-wide defaults: XMAKE_RCFILES

Xmake loads a user-specified "rc" file before any xmake.lua is parsed. Use it for global toolchains, default repos, company-wide policies — anything you want every project on the machine to pick up.

# Unix: colon-separated multiple files
export XMAKE_RCFILES=~/.xmake/xmakerc.lua:/etc/xmake/xmakerc.lua

# Windows: semicolon-separated
set XMAKE_RCFILES=C:\xmake\xmakerc.lua;D:\proj\xmakerc.lua

Example ~/.xmake/xmakerc.lua:

-- Always enable debug+release modes
add_rules("mode.debug", "mode.release")

-- Company-wide package repo
add_repositories("mycompany https://github.com/mycompany/xmake-repo.git")

-- Pin a preferred toolchain
toolchain("mygcc")
    set_kind("standalone")
    set_toolset("cc", "gcc-11")
    set_toolset("cxx", "g++-11")
toolchain_end()

Precedence: rc files load before the project xmake.lua, so the project can still override anything they set.

Precedence rules

For settings that have both an env var and a xmake g equivalent:

1. Env var (highest)
2. xmake g global config
3. Project-level xmake f config
4. Built-in default

So XMAKE_COLORTERM=nocolor xmake always disables color, regardless of xmake g --theme.

Inspecting from scripts

From inside a script-domain hook:

on_load(function (target)
    local configdir = os.getenv("XMAKE_CONFIGDIR")
    if configdir then
        print("using config dir %s", configdir)
    end
end)

os.getenv is one of the few env-reading APIs allowed in the description domain as read-only — fine for conditional config flags.

Common uses

# CI: disable color, log everything
XMAKE_COLORTERM=nocolor XMAKE_LOGFILE=build.log xmake

# Debug a stuck build
XMAKE_PROFILE=stuck xmake f -c

# Profile configure
XMAKE_PROFILE=perf:process xmake f -c

# Dev xmake from a checkout
source scripts/srcenv.profile         # sets XMAKE_PROGRAM_DIR + _FILE

# Cache-aware CI
XMAKE_PKG_CACHEDIR=$HOME/ci-cache/xmake-pkg xmake

Pitfalls

• Forgetting XMAKE_PROGRAM_DIR after a dev test. Leaves xmake pointing at a stale checkout. unset XMAKE_PROGRAM_DIR to restore.
• XMAKE_RCFILES breaks projects. A rc file that force-adds rules/toolchains can clash with a project that configures its own. Scope rc files carefully; prefer description-only.
• XMAKE_ROOT=y. Works, but running as root is dangerous — prefer a regular user.
• Env var precedence over xmake g. If xmake g --color256 seems ignored, check whether XMAKE_COLORTERM is exported.
• Logfile silently filling the disk. XMAKE_LOGFILE appends; rotate it yourself if enabled permanently.

When to branch out

• Developing xmake source and switching XMAKE_PROGRAM_* → xmake-dev
• Profiling / stuck debug (XMAKE_PROFILE) → xmake-troubleshooting
• Color / theme knobs → xmake-theme, xmake-color-output

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xmake-io
• Source: xmake-io/xmake-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.