Alien-Xmake-Project

 view release on metacpan or  search on metacpan

lib/Alien/Xmake/Project.pod  view on Meta::CPAN

generation, queries) directly from Perl.

=head1 CONSTRUCTOR

=head2 C<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
    );

=over

=item B<file>

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

=item B<yes>

Boolean. Forwarded to L<Alien::Xmake/new> so captured installs (e.g. C<add_requires>) never hang on a prompt.

=back

=head1 METHODS

=head2 Project level

=head3 Identity

=over

=item C<set_project( $name )>

    ...->set_project( 'libobseum' )

Sets the project name at the top of the build file.

=item C<set_version( $version )>

    ...->set_version( '0.1.0' )

Sets the project version string.

=item C<set_xmakever( $version )>

    ...->set_xmakever( '2.9.1' )

Sets the minimum xmake version required to build the project.

=back

=head3 Global options and defaults

=over

=item C<set_config( $name, $value )>

    ...->set_config( 'plat', 'windows' )

Sets a global configuration item that applies to the whole project.

=item C<set_defaultplat( @plats )>

    ...->set_defaultplat( 'windows' )

Sets the default platform used when none is given on the command line.

=item C<set_defaultarchs( @archs )>

    ...->set_defaultarchs( 'x86_64' )

Sets the default architectures used when none are given.

=item C<set_defaultmode( @modes )>

    ...->set_defaultmode( 'release' )

Sets the default build mode(s) used when none are given.

=item C<set_allowedplats( @plats )>

    ...->set_allowedplats( 'windows', 'linux', 'macosx' )

Whitelists the platforms the project may be built for.

=item C<set_allowedarchs( @archs )>

    ...->set_allowedarchs( 'x86', 'x86_64' )

Whitelists the architectures the project may be built for.

=item C<set_allowedmodes( @modes )>

    ...->set_allowedmodes( 'debug', 'release' )

Whitelists the build modes the project supports.

=item C<set_runtimes( @runtimes )>

    ...->set_runtimes( 'MT', 'MD' )

Sets the runtime flavour(s), e.g. C<MT>/C<MD> on MSVC.

=back

=head3 Global scope (applies to every target)

=over

=item C<set_toolchains( @names )>

    ...->set_toolchains( 'clang' )

Declares the toolchain(s) to use project-wide.

=item C<set_toolset( %pairs )>

    ...->set_toolset( cc => 'gcc', cxx => 'g++' )

Sets the tool programs used by the toolchain, as a table of C<name =E<gt> program> pairs.

lib/Alien/Xmake/Project.pod  view on Meta::CPAN

Sets the C precompiled header.

=item C<set_pcxxheader( $header )>

    ...->set_pcxxheader( 'common.hpp' )

Sets the C++ precompiled header.

=item C<set_pmheader( $header )>

    ...->set_pmheader( 'common.h' )

Sets the Objective-C precompiled header.

=item C<set_pmxxheader( $header )>

    ...->set_pmxxheader( 'common.hh' )

Sets the Objective-C++ precompiled header.

=item C<set_runtimes( @runtimes )>

    ...->set_runtimes( 'MD' )

Sets the runtime library flavour(s). On MSVC this selects the C runtime: C<MT>, C<MTd>, C<MD>, C<MDd>; on Android/iOS
it selects the C++ STL implementation: C<c++_static>, C<c++_shared>.

=item C<set_languages( @langs )>

    ...->set_languages( 'c99', 'cxx11' )

Sets the language standard(s). Standard C values: C<ansi>, C<c89>, C<gnu89>, C<c90>, C<gnu90>, C<c99>, C<gnu99>,
C<c11>, C<gnu11>, C<c17>, C<gnu17>, ..., C<clatest>. C++ values use the C<cxxN> form (C<cxx98>, C<cxx11>, C<cxx14>,
C<cxx17>, C<cxx20>, C<cxx23>, ..., C<cxxlatest>) or the C<C++N> spelling. A C and a C++ standard may be set together.

=item C<add_forceincludes( @files )>

    ...->add_forceincludes( 'config.h' )

Force-includes the given header files in every translation unit.

=item C<add_vectorexts( @exts )>

    ...->add_vectorexts( 'sse2', 'avx' )

Enables the given vector extensions.

=back

=item B<content and deps>

Otherwise-identical statements grouped by shared semantics; each is chainable.

=over

=item C<add_files( @patterns )>

    ...->add_files( 'src/*.cpp' )

Adds source files or glob patterns to compile.

=item C<remove_files( @patterns )>

    ...->remove_files( 'src/old.cpp' )

Removes source files/patterns previously added.

=item C<remove_headerfiles( @files )>

    ...->remove_headerfiles( 'src/old.h' )

Removes header files from the header set.

=item C<add_defines( @defines )>

    ...->add_defines( 'NDEBUG' )

Adds preprocessor macro definitions.

=item C<add_undefines( @defines )>

    ...->add_undefines( 'DEBUG' )

Undefines macros.

=item C<add_includedirs( @dirs )>

    ...->add_includedirs( 'include' )

Adds C header search directories.

=item C<add_sysincludedirs( @dirs )>

    ...->add_sysincludedirs( '/usr/include' )

Adds system header search directories.

=item C<add_embeddirs( @dirs )>

    ...->add_embeddirs( 'assets' )

Adds directories whose files are embedded into the target.

=item C<add_links( @libs )>

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

Adds libraries to link against.

=item C<add_syslinks( @libs )>

    ...->add_syslinks( 'pthread' )

Adds system libraries to link against.

=item C<add_linkorders( @orders )>

    ...->add_linkorders( 'liba.a', 'libb.a' )

Forces link ordering across whole libs.

lib/Alien/Xmake/Project.pod  view on Meta::CPAN

=item C<add_configfiles( @files )>

    ...->add_configfiles( 'config.h.in', { filename => 'config.h' } )

Generates a config file from a C<.in> template.

=item C<set_configvar( $name, $value )>

    ...->set_configvar( 'HAVE_X', '1' )

Sets a config variable substituted into generated config files.

=item C<set_configdir( $dir )>

    ...->set_configdir( '$(projectdir)/config' )

Sets the directory into which generated config files are written.

=back

=item B<compile-time feature detection>

The full C<@builtin/check> helper family is wired in. The first call emits C<includes("@builtin/check")> at the project
root exactly once. Each helper renders C<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 C<check_*> (defines
the macro) and C<configvar_check_*> (writes C<set_configvar> into the generated config) forms are provided across
C<links> C<syslinks> C<ctypes> C<cxxtypes> C<cfuncs> C<cxxfuncs> C<cincludes> C<cxxincludes> C<csnippets>
C<cxxsnippets> C<features> C<macros> C<sizeof> C<alignof> C<bigendian> C<cflags> C<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}

=item B<scoped conditions (when)>

C<when( $condition, $body )> wraps a group of statements in a Lua C<if/then/end> block so they only apply when a
compile-time predicate holds (C<is_plat> C<is_os> C<is_arch> C<is_host> C<is_mode> C<is_kind> C<is_config>
C<has_config> C<has_package>, or any Lua expression, including negations like C<not is_plat("windows")>). C<$body> is a
code ref whose C<->E<gt>...>> 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 C<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

C<when> is also available at the project (root/global) scope to guard C<add_rules>/C<add_requires>/C<includes> and any
root statement.

=item B<raw hooks and escape hatch>

Hooks take raw Lua function bodies: C<on_load> C<on_config> C<on_build> C<on_build_file> C<before_build> C<after_build>
C<on_link> C<on_clean> C<on_install> C<on_uninstall> C<on_run>. Strings that begin with C<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' )

C<lua( @lines )> pushes raw Lua lines straight into the target body (escape hatch).

=back

=back

=head2 Option builder

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

=over

=item C<set_default( $value )>

    ...->set_default( true )

Sets the option's default value.

=item C<set_values( @vals )>

    ...->set_values( 'debug', 'release' )

Sets the list of allowed values for the option.

=item C<set_showmenu( $bool )>

    ...->set_showmenu( true )

Sets whether to show the option in the C<xmake f --help> menu.

=item C<set_category( $category )>

    ...->set_category( 'Features' )

Groups the option under a category in the menu.

=item C<set_description( $text )>

    ...->set_description( 'Enable the foo feature' )

Sets a human-readable description shown in the menu.

=item C<add_deps( @opts )>

    ...->add_deps( 'with_toolchain' )

Requires the named other options to be resolved first.