view release on metacpan or  search on metacpan

lib/Alien/SDL3.pm  view on Meta::CPAN

use v5.40;
#
package Alien::SDL3 v3.4.22 {
    use feature 'class';
    no warnings 'experimental::class';
    use Alien::Xrepo::Runtime;
    use Config ();

    class Alien::SDL3 : isa(Alien::Xrepo::Runtime) {

        # SDL3 is bound as a family: core + the common extension libraries. Each is installed
        # separately (as a SHARED library; xrepo builds SDL3 static by default, and Affix/FFI::Platypus
        # need a real .dll/.so/.dylib) and exposed via the Alien::Build-style `alt()` accessor or a
        # package-name argument.
        #
        # recipes/ is a small local xmake-repo tree (local overrides of libsdl3, libsdl3_image,
        # libsdl3_ttf and libsdl3_mixer); registering it here means the runtime description also
        # carries everything the engine needs to reproduce the build.
        method recipe {

            # install_opts() is only the runtime's dynamic-resolution ambient; the build engine reads the
            # recipe's `defaults`. Folding install_opts() in here is what actually hands -a (and the Windows
            # toolchain below) to `perl Build`, keeping the built profile and dynamic resolution in step.
            my %defaults = ( system => 1, $self->install_opts );

            # ALIEN_SDL3_XMAKE_DEBUG=1 forwards -v/-D to `xrepo install` (Alien::Xrepo's
            # verbose/diagnosis, which needs v1.0.9+) so a package that fails to build prints
            # its whole install.txt instead of only the tail. That is what turns an opaque
            # `=> install libsdl3 .. failed` into the real error. Off by default: the
            # diagnostic detail is large and is only wanted while debugging a build.
            if ( $ENV{ALIEN_SDL3_XMAKE_DEBUG} ) {
                $defaults{verbose}   = 1;
                $defaults{diagnosis} = 1;
            }
            return {
                name     => 'Alien-SDL3',
                packages => [
                    { name => 'libsdl3',       kind => 'shared' },
                    { name => 'libsdl3_image', kind => 'shared', required => 0 },
                    { name => 'libsdl3_ttf',   kind => 'shared', required => 0 },
                    { name => 'libsdl3_mixer', kind => 'shared', required => 0 }
                ],

                # Ask for system packages explicitly: package-manager copies of SDL3 and friends (apt, brew,
                # vcpkg, ...) are preferred over building the pinned sources, and anything the system does not
                # provide still falls back to a source build. Note this is deliberately not a hard requirement
                # -- recipes/packages/l/libsdl3/xmake.lua gates the system path on SDL3 >= 3.4.18, so an older
                # copy (eg Ubuntu's 3.4.2 or vcpkg's 3.4.16) is skipped rather than mixed with the 3.4.18
                # headers the extension libraries build against, and on Windows the extension recipes re-check
                # that same verdict so the family never splits across sources.
                defaults    => \%defaults,
                local_repos => ['recipes']
            };
        }

        # An Alien hands the running Perl a library it must `dlopen`, so the xmake target
        # architecture has to follow $Config{archname} and not the host machine. The gap is
        # real on windows-11-arm, where an x64 Strawberry Perl runs under emulation: left to
        # itself xmake picks the ARM64 host arch, and x64 perl.exe cannot load an arm64 DLL.
        # Setting -a here keeps target arch, the prebuilt DLL flavour, and the Perl in step.
        # Returns () when archname is unrecognised, so xmake keeps its usual host default.
        #
        # Windows also needs its toolchain pinned. xmake's `windows` platform lists
        # msvc/clang/... in set_toolchains() but never gcc, so on a Strawberry Perl host --
        # gcc, nothing named `cl` on PATH -- xmake aborts the throwaway project with
        # "toolchain not found!" before a single package is even fetched (CPAN smoker
        # reports on MSWin32-x64-multi-thread). Pinning the toolchain to the compiler Perl
        # itself was built with keeps the prebuilt DLL flavour, the import library on_test
        # links against, and the library FFI dlopens all in agreement. An MSVC-built Perl
        # (cc=cl) is left untouched: the platform default already finds msvc.
        #
        # The platform itself needs pinning too, for the same reason the arch does: -p is
        # what the recipes branch on, and without it xmake invents one from the shell.