view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

            ```
            ...->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.

- `add_deps( @opts )`

    ```
    ...->add_deps( 'with_toolchain' )
    ```

    Requires the named other options to be resolved first.

- `add_links( @libs )`

    ```
    ...->add_links( 'm', 'dl' )
    ```