NAME

Alien::Xmake::Project - Compose and drive an xmake project from Perl

SYNOPSIS

use v5.40;
use Alien::Xmake::Project;

my $p = Alien::Xmake::Project->new( file => 'build/xmake.lua' );
$p->set_project('myapp')->set_version('0.1.0');
$p->add_requires('zlib');

$p->target('cli')
    ->set_kind('binary')
    ->add_files('src/*.cpp')
    ->add_packages('zlib');

$p->save;                                   # writes build/xmake.lua

$p->xmake->configure(mode => 'release');    # xmake configure -F build/xmake.lua
$p->xmake->build;
$p->xmake->run;

DESCRIPTION

xmake.lua is just a Lua file. Rather than editing it by hand, this class lets you describe a project with fluent Perl method calls and then hands you a normal Alien::Xmake object. Using chains like $p->set_kind('binary')->add_files('src/*.cpp') you may drive every stage (configure, build, run, install, IDE generation, queries) directly from Perl.

CONSTRUCTOR

`new( ... )`

my $p = Alien::Xmake::Project->new(
    file => 'build/xmake.lua',   # where save() writes the build file
    yes  => 1                    # auto-confirm prompts, forwarded to Alien::Xmake
);

file

Path of the generated build file (default xmake.lua). This becomes the file => option of the Alien::Xmake handle returned by xmake, so every action reads this file via -F.
yes

Boolean. Forwarded to "new" in Alien::Xmake so captured installs (e.g. add_requires) never hang on a prompt.

METHODS

Project level

Identity

set_project( $name )
```
...->set_project( 'libobseum' )
```
Sets the project name at the top of the build file.
set_version( $version )
```
...->set_version( '0.1.0' )
```
Sets the project version string.
set_xmakever( $version )
```
...->set_xmakever( '2.9.1' )
```
Sets the minimum xmake version required to build the project.

Global options and defaults

set_config( $name, $value )
```
...->set_config( 'plat', 'windows' )
```
Sets a global configuration item that applies to the whole project.
set_defaultplat( @plats )
```
...->set_defaultplat( 'windows' )
```
Sets the default platform used when none is given on the command line.
set_defaultarchs( @archs )
```
...->set_defaultarchs( 'x86_64' )
```
Sets the default architectures used when none are given.
set_defaultmode( @modes )
```
...->set_defaultmode( 'release' )
```
Sets the default build mode(s) used when none are given.
set_allowedplats( @plats )
```
...->set_allowedplats( 'windows', 'linux', 'macosx' )
```
Whitelists the platforms the project may be built for.
set_allowedarchs( @archs )
```
...->set_allowedarchs( 'x86', 'x86_64' )
```
Whitelists the architectures the project may be built for.
set_allowedmodes( @modes )
```
...->set_allowedmodes( 'debug', 'release' )
```
Whitelists the build modes the project supports.
set_runtimes( @runtimes )
```
...->set_runtimes( 'MT', 'MD' )
```
Sets the runtime flavour(s), e.g. MT/MD on MSVC.

Global scope (applies to every target)

set_toolchains( @names )
```
...->set_toolchains( 'clang' )
```
Declares the toolchain(s) to use project-wide.
set_toolset( %pairs )
```
...->set_toolset( cc => 'gcc', cxx => 'g++' )
```
Sets the tool programs used by the toolchain, as a table of name => program pairs.
set_plat( $plat )
```
...->set_plat( 'windows' )
```
Pins the target platform for the whole project.
set_arch( $arch )
```
...->set_arch( 'x86_64' )
```
Pins the target architecture for the whole project.
set_languages( @langs )
```
...->set_languages( 'c99', 'cxx11' )
```
Sets the language standards for every target.

Structure

add_moduledirs( @dirs )
```
...->add_moduledirs( 'modules' )
```
Adds extra module search directories.
add_plugindirs( @dirs )
```
...->add_plugindirs( 'plugins' )
```
Adds extra plugin search directories.
includes( @files )
```
...->includes( 'build/config.lua' )
```
Includes other build files.
add_rules( @rules )
```
...->add_rules( 'mode.debug', 'mode.release' )
```
Adds rule names to the whole project.
add_addons( @addons )
```
...->add_addons( 'tools.xmake' )
```
Enables addons.

Packages and repositories

add_requires( @packages )
```
...->add_requires( 'zlib', { system => true } )
```
Adds project-wide package requirements. A trailing hashref becomes an options table; version strings pass through verbatim, and booleans must be real true/false (xmake expects true, not 1).
add_requireconfs( @configs )
```
...->add_requireconfs( 'zlib', { configs => { shared => true } } )
```
Overrides requirement configs. Accepts a trailing options hashref.
add_repositories( @repos )
```
...->add_repositories( 'myrepo', 'https://github.com/user/repo' )
```
Registers package repositories. Accepts a trailing options hashref.

Domain builders

target( $name )
```
...->target( 'app' )
```
Begins a target(...) block and returns a "Target builder".
option( $name )
```
...->option( 'with_foo' )
```
Begins a option(...) block and returns the "Option builder". Passing a trailing hashref instead emits the inline table form.
rule( $name )
```
...->rule( 'markdown' )
```
Begins a rule(...) block and returns the "Rule builder".
toolchain( $name )
```
...->toolchain( 'mycc' )
```
Begins a toolchain(...) block and returns the "Toolchain builder".
package( $name )
```
...->package( 'zlib' )
```
Begins a package(...) block and returns the "Package builder".
xpack( $name )
```
...->xpack( 'myapp' )
```
Begins an xpack(...) block and returns the "Xpack builder". The first call also emits includes("@builtin/xpack") so the xpack plugin is enabled.
namespace( $name, @lines )
```
...->namespace( 'core', 'add_rules("xmake.lua.lint")' )
```
Begins a namespace(...) block. Items may be raw Lua line strings or CODE refs called with the project so they can emit lines (sub { $project->... } returning the statement text or lines).

Emission and execution

save
```
...->save
```
Writes the accumulated description to file. Returns the project.
xmake
```
...->xmake
```
Returns an Alien::Xmake handle whose every action reads this project's build file (constructed once, cached).
configure( %options )
```
...->configure( mode => 'release' )
```
Configures the project via "configure" in Alien::Xmake, auto-saving file if not yet written.
build( [$target], %options )
```
...->build
```
Builds the project (or a specific target) via "build" in Alien::Xmake, auto-saving file if not yet written.
run( [$target], %options )
```
...->run( 'app' )
```
Runs the target via "run" in Alien::Xmake.
clean( [$target], %options )
```
...->clean
```
Cleans target binaries and build directories via "clean" in Alien::Xmake.
install( [$target], %options )
```
...->install
```
Installs the built artifacts via "install" in Alien::Xmake.
pack( [$name], %options )
```
...->pack
```
Packs installation archives via "pack" in Alien::Xmake, auto-saving file if not yet written.
project( [$kind], %options )
```
...->project( 'compile_commands' )
...->project( kind => 'vsxmake', modes => 'release' )
```
Generates project files (e.g. compile_commands, vsxmake, xcode, cmake, make) via "project" in Alien::Xmake. Auto-saves file if not yet written.
target_info( $name, %options )
```
...->target_info( 'app' )
```
Returns rich target metadata parsed from xmake show -t <name --format=json> via "target_info" in Alien::Xmake.

show( [$list], %options )

...->show
...->show( 'targets' )                          # list target names
...->show( 'platforms' )                        # list supported platforms
...->show( 'toolchains' )                       # list available toolchains
...->show( 'packages' )
...->show( 'options' )
...->show( 'lua', 'deps' )                      # show graph info for a config
...->show( targets => { group => 'Library' } )  # targets in a group
...->show( platforms => { pretty => 1 } )       # pretty-printed tree
...->show( targets => { format => 'json' } )    # JSON (parsed to a structure)
...->show( 'configs' )
...->show( 'arch' )                             # target architecture
...->show( 'plat' )
...->show( 'mode' )
...->show( 'host' )

Runs xmake show queries via "show" in Alien::Xmake and returns the parsed results (a list of lines, a list of names for list queries, or a decoded structure when format => 'json').

Target builder

Each method is chainable and corresponds to the same-named xmake.lua statement inside a target(...) block. A trailing hashref is emitted as an options table; true/false emit bare Lua booleans.

set_kind( $kind )
```
...->set_kind( 'binary' )
```
Sets the kind of target: binary (executable), static, shared, object, headeronly, phony.
- naming and output
  - set_basename( $name )
```
...->set_basename( 'myapp' )
```
    Overrides the base (file) name of the generated target.
  - set_filename( $name )
```
...->set_filename( 'myapp.exe' )
```
    Overrides the full file name of the generated binary/library, including extension if desired.
  - set_prefixname( $name )
```
...->set_prefixname( 'lib' )   # static lib -> libfoo.a
```
    Sets the prefix prepended to the target output file name.
  - set_suffixname( $name )
```
...->set_suffixname( 'd' )     # myapp -> myappd
```
    Sets the suffix appended to the target output file name.
  - set_extension( $ext )
```
...->set_extension( '.exe' )
```
    Sets the output file extension; calling with no argument clears a toolchain default.
  - set_strip( $level )
```
...->set_strip( 'all' )
```
    Sets the strip mode applied at link time: debug (strip debug symbols only), all (strip all symbols), none. Combined with set_symbols('debug'), a separate debug-symbol file (dSYM/pdb/.sym) is also generated.
  - set_group( $group )
```
...->set_group( 'Library' )
```
    Assigns the target to a project group, used by IDE generators to nest targets in folders.
  - set_objectdir( $dir )
```
...->set_objectdir( '$(builddir)/.objs' )
```
    Sets the directory for intermediate object files.
  - set_dependir( $dir )
```
...->set_dependir( '$(builddir)/.deps' )
```
    Sets the directory for compile dependency (.deps) files.
  - set_installdir( $dir )
```
...->set_installdir( '$(buildir)/lib' )
```
    Sets the directory into which the target's install files are placed on install.
  - set_prefixdir( $dir )
```
...->set_prefixdir( 'usr/local' )
```
    Sets the directory to strip as a prefix when installing relative paths.
- enablement and options
  - set_default( $bool )
```
...->set_default( false )
```
    Sets whether the target is built by default. Pass a real false to opt out.
  - set_enabled( $bool )
```
...->set_enabled( true )
```
    Sets whether the target is enabled at all; a disabled target is not built or used.
  - set_options( @opts )
```
...->set_options( 'with_foo' )
```
    Makes the target depend on the named project option(...) values.
  - add_options( @opts )
```
...->add_options( 'with_bar' )
```
    Adds additional option(...) requirement(s) to the target.
- compile model
  - set_warnings( $level )
```
...->set_warnings( 'all' )
```
    Sets the compiler warning level; xmake maps the abstract level to the right flag per compiler. Available levels: none, less, more, extra, pedantic, all, allextra, everything, error.
  - set_optimize( $level )
```
...->set_optimize( 'fastest' )
```
    Sets the compile optimization level; each level maps to the appropriate flag for the target compiler. Available levels: none, fast, faster, fastest, smallest, aggressive.
  - set_symbols( $level )
```
...->set_symbols( 'debug' )
...->set_symbols( 'debug', 'hidden' )
```
    Sets the debug-symbol mode. Levels may be combined: none, debug, hidden, plus the msvc-only refinements edit and embed.
  - set_fpmodels( @models )
```
...->set_fpmodels( 'fast', 'except' )
```
    Sets the floating-point compilation mode: fast, strict, except, noexcept, precise (the default). Models may be combined, but fast conflicts with precise/strict.
  - set_exceptions( @modes )
```
...->set_exceptions( 'cxx' )
```
    Enables or disables C++ / Objective-C exceptions: cxx, no-cxx, objc, no-objc. xmake picks the compiler-specific flag.
  - set_encodings( @encodings )
```
...->set_encodings( 'utf-8' )
...->set_encodings( 'source:utf-8', 'target:gb2312' )
```
    Sets the source and/or target executable encoding. A bare encoding applies to both; prefix with source: or target: for one side.
  - set_policy( $name, $value )
```
...->set_policy( 'build.warning', true )
```
    Sets a build policy for this target. See the xmake builtin-policies reference for the full list.
  - set_pcheader( $header )
```
...->set_pcheader( 'common.h' )
```
    Sets the C precompiled header.
  - set_pcxxheader( $header )
```
...->set_pcxxheader( 'common.hpp' )
```
    Sets the C++ precompiled header.
  - set_pmheader( $header )
```
...->set_pmheader( 'common.h' )
```
    Sets the Objective-C precompiled header.
  - set_pmxxheader( $header )
```
...->set_pmxxheader( 'common.hh' )
```
    Sets the Objective-C++ precompiled header.
  - set_runtimes( @runtimes )
```
...->set_runtimes( 'MD' )
```
    Sets the runtime library flavour(s). On MSVC this selects the C runtime: MT, MTd, MD, MDd; on Android/iOS it selects the C++ STL implementation: c++_static, c++_shared.
  - set_languages( @langs )
```
...->set_languages( 'c99', 'cxx11' )
```
    Sets the language standard(s). Standard C values: ansi, c89, gnu89, c90, gnu90, c99, gnu99, c11, gnu11, c17, gnu17, ..., clatest. C++ values use the cxxN form (cxx98, cxx11, cxx14, cxx17, cxx20, cxx23, ..., cxxlatest) or the C++N spelling. A C and a C++ standard may be set together.
  - add_forceincludes( @files )
```
...->add_forceincludes( 'config.h' )
```
    Force-includes the given header files in every translation unit.
  - add_vectorexts( @exts )
```
...->add_vectorexts( 'sse2', 'avx' )
```
    Enables the given vector extensions.
- content and deps
  
  Otherwise-identical statements grouped by shared semantics; each is chainable.
  - add_files( @patterns )
```
...->add_files( 'src/*.cpp' )
```
    Adds source files or glob patterns to compile.
  - remove_files( @patterns )
```
...->remove_files( 'src/old.cpp' )
```
    Removes source files/patterns previously added.
  - remove_headerfiles( @files )
```
...->remove_headerfiles( 'src/old.h' )
```
    Removes header files from the header set.
  - add_defines( @defines )
```
...->add_defines( 'NDEBUG' )
```
    Adds preprocessor macro definitions.
  - add_undefines( @defines )
```
...->add_undefines( 'DEBUG' )
```
    Undefines macros.
  - add_includedirs( @dirs )
```
...->add_includedirs( 'include' )
```
    Adds C header search directories.
  - add_sysincludedirs( @dirs )
```
...->add_sysincludedirs( '/usr/include' )
```
    Adds system header search directories.
  - add_embeddirs( @dirs )
```
...->add_embeddirs( 'assets' )
```
    Adds directories whose files are embedded into the target.
  - add_links( @libs )
```
...->add_links( 'm', 'dl' )
```
    Adds libraries to link against.
  - add_syslinks( @libs )
```
...->add_syslinks( 'pthread' )
```
    Adds system libraries to link against.
  - add_linkorders( @orders )
```
...->add_linkorders( 'liba.a', 'libb.a' )
```
    Forces link ordering across whole libs.
  - add_linkgroups( @groups )
```
...->add_linkgroups( 'pthread', 'm' )
```
    Wraps the named links in linker group flags, e.g. --start-group/--end-group.
  - add_linkdirs( @dirs )
```
...->add_linkdirs( 'lib' )
```
    Adds library search directories.
  - add_rpathdirs( @dirs )
```
...->add_rpathdirs( '$ORIGIN' )
```
    Adds runtime library search directories.
  - add_deps( @targets )
```
...->add_deps( 'core' )
```
    Declares dependencies on other targets.
  - add_rules( @rules )
```
...->add_rules( 'qt.static' )
```
    Attaches rule name(s) to this target.
  - add_packages( @packages )
```
...->add_packages( 'zlib' )
```
    Links against the given packages from add_requires.
  - add_requires( @packages )
```
...->add_requires( 'zlib' )
```
    Requires packages that are then linked into this target.
  - add_headerfiles( @files )
```
...->add_headerfiles( 'src/*.h' )
```
    Adds header files to install with the target.
  - add_installfiles( @files )
```
...->add_installfiles( 'src/readme.txt' )
```
    Adds extra files to install with the target.
  - add_extrafiles( @files )
```
...->add_extrafiles( 'src/license.txt' )
```
    Adds files that should be listed/installed but not compiled.
  - add_imports( @mods )
```
...->add_imports( 'core.base.task' )
```
    Imports xmake modules for use in the target's Lua hooks.
  - add_languages( @langs )
```
...->add_languages( 'cxx17' )
```
    Adds extra language standard(s) without replacing existing ones.
  - add_frameworks( @frameworks )
```
...->add_frameworks( 'Foundation' )
```
    Adds system frameworks to link (macOS/iOS).
  - add_frameworkdirs( @dirs )
```
...->add_frameworkdirs( '/System/Library/Frameworks' )
```
    Adds framework search directories.
  - add_values( $key, @values )
```
...->add_values( 'wasm.preloadfiles', 'src/assets/app.js' )
```
    Sets a target-specific key/value pair, e.g. the wasm preload files.
  - set_values( %pairs )
```
...->set_values( 'wasm.preloadfiles' => [ 'src/assets/app.js' ] )
```
    Replaces all values for a set of target-specific keys from a hashref.
- runtime / run
  - set_targetdir( $dir )
```
...->set_targetdir( '$(builddir)/out', { bindir => 'bin', libdir => 'lib' } )
```
    Sets the output directory for the target's files. By default output goes to build; when set, this directory is preferred. Subdirectories such as bindir/libdir may be configured via a trailing table.
  - set_rundir( $dir )
```
...->set_rundir( 'tests' )
```
    Sets the working directory used when the target runs.
  - set_runargs( @args )
```
...->set_runargs( '--verbose' )
```
    Sets default arguments passed to the target when it runs.
  - set_runenv( $name, $value )
```
...->set_runenv( 'HOME', '/tmp' )
```
    Sets a single environment variable for the running target.
  - add_runenvs( %pairs )
```
...->add_runenvs( LD_LIBRARY_PATH => 'lib' )
```
    Adds environment variables for the running target from a hashref.
  - add_tests( $name, @cmds )
```
...->add_tests( 'unit', 'test.exe' )
```
    Registers a runnable test that xmake test can invoke.
- toolchain / plat / arch
  - set_plat( $plat )
```
...->set_plat( 'windows' )
```
    Pins this target to a specific platform.
  - set_arch( $arch )
```
...->set_arch( 'x86_64' )
```
    Pins this target to a specific architecture.
  - set_toolchains( @names )
```
...->set_toolchains( 'clang' )
```
    Sets the toolchain(s) used to build this target.
  - set_toolset( %pairs )
```
...->set_toolset( cc => 'gcc', cxx => 'g++' )
```
    Sets the tool programs used by the toolchain, as a table of name => program pairs.
- flags
  
  Compile and link flags carry their compiler prefix so one method covers each family: add_cflags add_cxflags add_cxxflags add_mflags add_mxflags add_mxxflags add_scflags add_asflags add_gcflags add_dcflags add_rcflags add_fcflags add_zcflags add_cuflags add_culdflags add_cugencodes add_ascnpuarchs add_ldflags add_arflags add_shflags.
- config-file generation
  - add_configfiles( @files )
```
...->add_configfiles( 'config.h.in', { filename => 'config.h' } )
```
    Generates a config file from a .in template.
  - set_configvar( $name, $value )
```
...->set_configvar( 'HAVE_X', '1' )
```
    Sets a config variable substituted into generated config files.
  - set_configdir( $dir )
```
...->set_configdir( '$(projectdir)/config' )
```
    Sets the directory into which generated config files are written.
- compile-time feature detection
  
  The full @builtin/check helper family is wired in. The first call emits includes("@builtin/check") at the project root exactly once. Each helper renders def, arg and passes list-style arguments (links, headers, types) as a single Lua list rather than flattening them; a trailing hashref becomes the options table. Both the plain check_* (defines the macro) and configvar_check_* (writes set_configvar into the generated config) forms are provided across links syslinks ctypes cxxtypes cfuncs cxxfuncs cincludes cxxincludes csnippets cxxsnippets features macros sizeof alignof bigendian cflags cxxflags:
```
  ...->add_configfiles( 'config.h.in', { filename => 'config.h' } )
  ...->configvar_check_links( 'HAS_PTHREAD', [ 'pthread', 'm', 'dl' ] )
  ...->configvar_check_ctypes( 'HAS_WCHAR', 'wchar_t' )

with C<config.h.in>:

  ${define HAS_PTHREAD}
  ${define HAS_WCHAR}
```
- scoped conditions (when)
  
  when( $condition, $body ) wraps a group of statements in a Lua if/then/end block so they only apply when a compile-time predicate holds (is_plat is_os is_arch is_host is_mode is_kind is_config has_config has_package, or any Lua expression, including negations like not is_plat("windows")). $body is a code ref whose ->...>> chained calls back into the same builder, an arrayref of raw Lua lines, or a single raw Lua line string. Inner statements are indented one level and end closes the block:
```
  ...->when( 'is_plat("windows", "linux")', sub {
      ...->add_links( 'pthread', 'm', 'dl' );
  } )
  ...->when( 'is_arch("arm.*")', 'add_defines("ARM")' )

emits:

  if is_plat("windows", "linux") then
      add_links("pthread", "m", "dl")
  end
  if is_arch("arm.*") then
      add_defines("ARM")
  end
```
  when is also available at the project (root/global) scope to guard add_rules/add_requires/includes and any root statement.
- raw hooks and escape hatch
  
  Hooks take raw Lua function bodies: on_load on_config on_build on_build_file before_build after_build on_link on_clean on_install on_uninstall on_run. Strings that begin with function are emitted unquoted; other strings are quoted and joined as arguments:
```
...->on_build( 'function (target) print(target:name()) end' )
...->on_install( 'windows', 'function (target) end' )
```
  lua( @lines ) pushes raw Lua lines straight into the target body (escape hatch).

Option builder

An option(...) block describes a configurable build option. Every method is chainable. A trailing hashref becomes an options table; true/false emit bare Lua booleans. Note that an option created with the inline table form (option('name', { ... })) cannot be extended with these setters.

set_default( $value )
```
...->set_default( true )
```
Sets the option's default value.
set_values( @vals )
```
...->set_values( 'debug', 'release' )
```
Sets the list of allowed values for the option.
set_showmenu( $bool )
```
...->set_showmenu( true )
```
Sets whether to show the option in the xmake f --help menu.
set_category( $category )
```
...->set_category( 'Features' )
```
Groups the option under a category in the menu.
set_description( $text )
```
...->set_description( 'Enable the foo feature' )
```
Sets a human-readable description shown in the menu.
add_deps( @opts )
```
...->add_deps( 'with_toolchain' )
```
Requires the named other options to be resolved first.
add_links( @libs )
```
...->add_links( 'm', 'dl' )
```
Adds libraries the option links when enabled.
add_linkdirs( @dirs )
```
...->add_linkdirs( 'lib' )
```
Adds library search directories for the option.
add_rpathdirs( @dirs )
```
...->add_rpathdirs( '$ORIGIN' )
```
Adds runtime library search directories for the option.
add_cincludes( @headers )
```
...->add_cincludes( 'math.h' )
```
Probes for the presence of the given C headers.
add_cxxincludes( @headers )
```
...->add_cxxincludes( 'vector' )
```
Probes for the presence of the given C++ headers.
add_ctypes( @types )
```
...->add_ctypes( 'wchar_t' )
```
Probes for the presence of the given C types.
add_cxxtypes( @types )
```
...->add_cxxtypes( 'std::string' )
```
Probes for the presence of the given C++ types.
add_csnippets( @code )
```
...->add_csnippets( 'int main() { return 0; }' )
```
Probes C code snippets for successful compilation.
add_cxxsnippets( @code )
```
...->add_cxxsnippets( 'int main() { return 0; }' )
```
Probes C++ code snippets for successful compilation.
add_cfuncs( @funcs )
```
...->add_cfuncs( 'pow' )
```
Probes for the presence of the given C functions.
add_cxxfuncs( @funcs )
```
...->add_cxxfuncs( 'std::swap' )
```
Probes for the presence of the given C++ functions.
add_defines( @defines )
```
...->add_defines( 'HAVE_FOO' )
```
Adds macros defined when the option is enabled.
add_cxflags( @flags )
```
...->add_cxflags( '-DFOO' )
```
Adds C/C++ flags applied when the option is enabled.
before_check( $body ) on_check( $body ) after_check( $body )
```
...->on_check( 'function (option) return false end' )
```
Injects raw-Lua hooks around the option's compile-time check.

Rule builder

A rule(...) block describes a custom build rule. Every method is chainable.

set_extensions( @exts )
```
...->set_extensions( '.c', '.cpp' )
```
Sets the file extensions this rule handles.
add_deps( @rules )
```
...->add_deps( 'lex' )
```
Makes this rule depend on other rules.
add_imports( @mods )
```
...->add_imports( 'core.base.task' )
```
Imports xmake modules for use in the rule's Lua hooks.
on_load( $body ) on_config( $body ) on_link( $body ) on_build( $body ) on_build_file( $body ) on_build_files( $body ) on_clean( $body ) on_package( $body ) on_install( $body ) on_uninstall( $body )
```
...->on_build( 'function (target) print(target:name()) end' )
```
Injects raw-Lua hooks (each takes raw Lua function bodies). lua( @lines ) pushes raw Lua lines straight into the rule body.

Toolchain builder

A toolchain(...) block describes a custom toolchain. Every method is chainable.

set_kind( $kind )
```
...->set_kind( 'standalone' )
```
Sets the toolchain kind, e.g. standalone.
set_sdkdir( $dir )
```
...->set_sdkdir( '/opt/toolchain' )
```
Sets the SDK root directory for the toolchain.
set_bindir( $dir )
```
...->set_bindir( '/opt/toolchain/bin' )
```
Sets the directory containing the toolchain's executables.
set_toolset( %pairs )
```
...->set_toolset( cc => 'gcc', cxx => 'g++' )
```
Sets this toolchain's tool programs as a table of name => program pairs.
add_defines( @defines )
```
...->add_defines( 'FOO' )
```
Adds preprocessor defines for the toolchain.
on_load( $body ) on_check( $body )
```
...->on_load( 'function (toolchain) end' )
```
Injects raw-Lua hooks (each takes raw Lua function bodies).

Package builder

A package(...) block describes how a dependency package is fetched and installed. Every method is chainable; a trailing hashref becomes an options table; true/false emit bare Lua booleans.

set_homepage( $url )
```
...->set_homepage( 'https://example.com' )
```
Sets the package homepage URL.
set_description( $text )
```
...->set_description( 'A useful library' )
```
Sets a short description of the package.
set_license( $license )
```
...->set_license( 'MIT' )
```
Sets the package license identifier.
set_kind( $kind )
```
...->set_kind( 'library' )
```
Sets the package kind: library (default), binary, or headeronly.
set_urls( @urls )
```
...->set_urls( 'https://example.com/libfoo/v$(version).tar.gz' )
```
Sets the official download URL(s) for the package.
add_urls( @urls )
```
...->add_urls( 'https://mirror.example.com/libfoo.tar.gz' )
```
Adds mirror download URL(s), tried in order until one works.
add_versions( @vers )
```
...->add_versions( '1.0.0', { hash => 'sha256:<hexdigest>' } )
```
Registers known versions of the package, each with an integrity hash.
add_versionfiles( @files )
```
...->add_versionfiles( '1.0.0' => 'patch.tar.gz' )
```
Adds version-specific file mappings.
set_sourcedir( $dir )
```
...->set_sourcedir( 'src' )
```
Uses a local source directory instead of downloading.
add_patches( @patches )
```
...->add_patches( '1.0.0', 'patch.diff' )
```
Adds patches to apply after unpacking.
add_links( @libs )
```
...->add_links( 'foo' )
```
Adds libraries this package provides.
add_syslinks( @libs )
```
...->add_syslinks( 'pthread' )
```
Adds system libraries this package links.
add_includedirs( @dirs )
```
...->add_includedirs( 'include' )
```
Adds include directories this package adds.
add_bindirs( @dirs )
```
...->add_bindirs( 'bin' )
```
Adds binary directories this package adds.
add_defines( @defines )
```
...->add_defines( 'HAVE_FOO' )
```
Adds defines this package adds to its consumers.
add_frameworks( @frameworks )
```
...->add_frameworks( 'Foundation' )
```
Adds system frameworks this package links (macOS/iOS).
add_linkdirs( @dirs )
```
...->add_linkdirs( 'lib' )
```
Adds library search directories this package adds.
add_linkorders( @orders )
```
...->add_linkorders( 'liba.a' )
```
Adds link ordering across whole libs for this package.
add_linkgroups( @groups )
```
...->add_linkgroups( 'pthread', 'm' )
```
Adds linker group flags for this package's links.
add_configs( @configs )
```
...->add_configs( 'shared', true )
...->add_configs( 'shared', false, 'icu', true )
```
Sets default package configurations as alternating name, value pairs.
add_extsources( @sources )
```
...->add_extsources( 'ext/*.c' )
```
Adds extra source files/objects to add when built from source.
add_deps( @pkgs )
```
...->add_deps( 'zlib' )
```
Declares dependencies on other packages.
add_components( @comps )
```
...->add_components( 'core', 'io' )
```
Declares components of this package.
set_base( $rule )
```
...->set_base( 'github' )
```
Bases this package on an existing package or rule.
add_schemes( %schemes )
```
...->add_schemes( configs => { shared => true } )
```
Sets scheme overrides that push configs onto consumers of this package.
on_load( $body ) on_fetch( $body ) on_check( $body ) on_install( $body ) on_download( $body ) on_test( $body ) on_component( $body )
```
...->on_install( 'function (package) end' )
```
Injects raw-Lua hooks (each takes raw Lua function bodies). lua( @lines ) pushes raw Lua lines straight into the package body.

Xpack builder

An xpack(...) block describes a distributable installer package. The first xpack call also emits includes("@builtin/xpack") to enable the plugin. Every method is chainable; a trailing hashref becomes an options table; true/false emit bare Lua booleans.

set_version( $version )
```
...->set_version( '1.0.0' )
```
Sets the package version string.
set_homepage( $url )
```
...->set_homepage( 'https://example.com' )
```
Sets the package homepage URL.
set_title( $title )
```
...->set_title( 'MyApp' )
```
Sets the display title of the installer.
set_author( $author )
```
...->set_author( 'Jane Doe' )
```
Sets the author name.
set_maintainer( $maintainer )
```
...->set_maintainer( 'Jane Doe' )
```
Sets the maintainer name.
set_description( $text )
```
...->set_description( 'Cross-platform app' )
```
Sets a short description shown in the installer.
set_copyright( $notice )
```
...->set_copyright( '2026 Jane Doe' )
```
Sets the copyright notice for the installer.
set_company( $company )
```
...->set_company( 'Acme Inc.' )
```
Sets the company/organization name.
set_inputkind( $kind )
```
...->set_inputkind( 'binary' )
```
Identifies the packaged input source type: binary or source. Optional - built-in formats usually determine this from the format name, but it is needed for custom formats (e.g. to distinguish a binary deb from a source deb).
set_formats( @formats )
```
...->set_formats( 'nsis', 'zip', 'targz' )
```
Configures the packaging format(s) to generate; xmake pack produces all of them at once. Supported formats: nsis (Windows NSIS installer), wix, zip, targz, srczip, srctargz, runself, rpm, srpm, deb, dmg, appimage, plus custom formats.
set_basename( $name )
```
...->set_basename( 'myapp-setup' )
```
Sets the base file name of the generated installer.
set_extension( $ext )
```
...->set_extension( '.exe' )
```
Sets the file extension of the generated installer.
set_bindir( $dir )
```
...->set_bindir( 'bin' )
```
Sets the directory whose contents become the payload's bin.
set_libdir( $dir )
```
...->set_libdir( 'lib' )
```
Sets the directory whose contents become the payload's lib.
set_includedir( $dir )
```
...->set_includedir( 'include' )
```
Sets the directory whose contents become the payload's include.
set_prefixdir( $dir )
```
...->set_prefixdir( 'usr/local' )
```
Sets the install prefix inside the payload.
set_specfile( $spec )
```
...->set_specfile( 'packaging/foo.spec' )
```
Sets the path to a packaging spec file.
set_specvar( $name, $value )
```
...->set_specvar( 'VERSION', '$(version)' )
```
Sets a variable substituted into the spec file.
set_iconfile( $file )
```
...->set_iconfile( 'assets/icon.ico' )
```
Sets the icon file for the installer.
set_license( $license )
```
...->set_license( 'MIT' )
```
Sets the license text or identifier.
set_licensefile( $file )
```
...->set_licensefile( 'LICENSE' )
```
Sets the path to a license file bundled with the installer.
set_nsis_displayicon( $bool )
```
...->set_nsis_displayicon( true )
```
Sets whether to show the icon in the NSIS installer.
add_sourcefiles( @files )
```
...->add_sourcefiles( 'src/*.c' )
```
Adds source files to package.
add_installfiles( @files )
```
...->add_installfiles( 'README.md' )
```
Adds extra install files to package.
add_targets( @targets )
```
...->add_targets( 'myapp' )
```
Includes the named build targets' outputs in the package.
add_components( @comps )
```
...->add_components( 'core' )
```
Includes prebuilt components in the package.
add_buildrequires( @pkgs )
```
...->add_buildrequires( 'nsis' )
```
Adds packages required to build the installer.
on_load( $body ) on_package( $body )
```
...->on_package( 'function (xpack) end' )
```
Injects raw-Lua hooks (each takes raw Lua function bodies).
component( $name, @body )
```
...->component( 'core', sub { ...->set_default( true ) } )
```
Begins an xpack_component(...) block; returns a "XpackComponent builder".

XpackComponent builder

An xpack_component(...) block describes one sub-component of an xpack. Every method is chainable.

set_title( $title )
```
...->set_title( 'Core runtime' )
```
Sets the display title of the component.
set_description( $text )
```
...->set_description( 'The core runtime library' )
```
Sets the description of the component.
set_default( $bool )
```
...->set_default( true )
```
Sets whether the component is selected by default. Pass a real false to deselect.
add_sourcefiles( @files )
```
...->add_sourcefiles( 'src/*.c' )
```
Adds source files to this component.
add_installfiles( @files )
```
...->add_installfiles( 'LICENSE' )
```
Adds extra install files to this component.
on_load( $body )
```
...->on_load( 'function (component) end' )
```
Injects a raw-Lua hook (takes a raw Lua function body).
before_installcmd( $body ) on_installcmd( $body ) after_installcmd( $body ) before_uninstallcmd( $body ) on_uninstallcmd( $body ) after_uninstallcmd( $body )
```
...->on_installcmd( 'function (cmd) end' )
```
Injects raw-Lua hooks around the component's install/uninstall commands (each takes raw Lua function bodies). lua( @lines ) pushes raw Lua lines straight into the component body.

OPTION TABLES AND BOOLEANS

Any method that in xmake takes a trailing table accepts a Perl hashref as its last argument. It is rendered with bracket keys so any string key is valid Lua:

$t->add_files('src/*.cpp', { unity_group => 'core' });   # add_files("src/*.cpp", {["unity_group"]="core"})

Use the v5.36+ true/false keywords for booleans so xmake receives a real boolean, not the string "1":

$p->add_requires('zlib', { shared => true });

Key order in tables is deterministic (sorted).

EXAMPLES

A dependency-driven executable and a shared library with a test, built from Perl:

use v5.40;
use Alien::Xmake::Project;

my $p = Alien::Xmake::Project->new(file => 'xmake.lua');
$p->set_project('app')->set_version('0.1.0');
$p->add_rules('mode.debug', 'mode.release');
$p->add_requires('zlib', { configs => { shared => true } });

$p->target('core')
    ->set_kind('shared')
    ->add_files('src/core/*.cpp')
    ->add_packages('zlib');

$p->target('app')
    ->set_kind('binary')
    ->add_files('src/main.cpp')
    ->add_deps('core')
    ->add_packages('zlib')
    ->set_languages('c++20')
    ->add_values('wasm.preloadfiles', 'src/assets/app.js')
    ->on_install('windows', 'function (target) end');

$p->save;

$p->xmake->configure(mode => 'release');
$p->xmake->build;
$p->xmake->test;
$p->xmake->project(kind => 'vsxmake');   # feed any IDE generator

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson https://github.com/sanko

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)