Alien-Xmake-Project
view release on metacpan or search on metacpan
generation, queries) directly from Perl.
# CONSTRUCTOR
## `new( ... )`
```perl
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](https://metacpan.org/pod/Alien%3A%3AXmake)
handle returned by `xmake`, so every action reads this file via `-F`.
- **yes**
Boolean. Forwarded to ["new" in Alien::Xmake](https://metacpan.org/pod/Alien%3A%3AXmake#new) 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_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 )`
```
- `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`:
```perl
...->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:
```perl
...->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:
```js
...->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.
( run in 0.601 second using v1.01-cache-2.11-cpan-1236ad508bc )