view release on metacpan or  search on metacpan

lib/Alien/Xrepo.pod  view on Meta::CPAN

=pod

=encoding utf-8

=head1 NAME

Alien::Xrepo - Eases the Headache of Finding and Building Shared Libraries for FFI and XS

=head1 SYNOPSIS

    use v5.40;
    use Alien::Xrepo;

    # Initialize
    my $repo = Alien::Xrepo->new( );

    # Add a custom repository (optional)
    # $repo->add_repo( 'my-repo', 'https://github.com/my/repo.git' );
    # Install a shared lib with an automatic configuration
    my $ogg = $repo->install('libvorbis');

    # Install a library with specific configuration
    # equivalent to: xrepo install -p windows -a x86_64 -m debug --configs='shared=true,vs_runtime=MD' libpng
    my $pkg = $repo->install( 'libpng', '1.6.x', plat => 'windows', arch => 'x64', mode => 'debug', configs => { vs_runtime => 'MD' } );
    die 'Install failed' unless $pkg;

    # Automatically wrap zlib as a whole with Affix::Wrap
    use Affix;
    use Affix::Wrap;
    my $zlib = $repo->install('zlib');
    Affix::Wrap->new(
        project_files => [ $zlib->find_header('zlib.h') ],
        include_dirs  => [ $zlib->includedirs ],
        types         => { gzFile_s => Pointer [Void] }
    )->wrap( $zlib->libpath );
    say 'zlib version:   ' . zlibVersion();

    # Wrap a single function from sqlite3 with Affix
    use Affix;
    my $sqlite3 = $repo->install('sqlite3');
    affix $sqlite3->libpath, 'sqlite3_libversion', [], String;
    say 'SQLite version: ' . sqlite3_libversion();

    # Wrap a single function from libpng with FFI::Platypus
    use FFI::Platypus;
    my $lz4 = $repo->install('lz4');
    my $ffi = FFI::Platypus->new;
    $ffi->lib( $lz4->libpath );
    $ffi->attach( 'LZ4_versionString', [] => 'string' );
    say 'LZ4 version:    ' . LZ4_versionString();

=head1 DESCRIPTION

This module acts as an intelligent bridge between Perl and the C<xrepo> package manager.

While L<Affix> or L<FFI::Platypus> or L<Inline::C> can handle the binding or linking to native functions, Alien::Xrepo
handles the B<acquisition> of the libraries containing those functions. It automates the entire dependency lifecycle:

=over

=item 1. Provisioning:

Downloads and installs libraries (C<libpng>, C<openssl>, etc.) via C<xrepo>, handling version constraints and custom
repository lookups.

=item 2. Configuration:

Ensures libraries are compiled with FFI compatible flags (forcing C<shared> libraries instead of static archives) and
supports cross-compilation parameters (platform, architecture, toolchains).

=item 3. Introspection:

Parses the build metadata to locate the exact absolute paths to the runtime binaries (C<.dll>, C<.so>, C<.dylib>) and
header files, abstracting away operating system filesystem differences.

=back

This eliminates the need for manual compilation steps or hard coding paths in your Perl scripts, making your FFI
bindings or XS wrappers portable and reproducible.

=head1 CONSTRUCTOR

=head2 C<new>

    my $repo = Alien::Xrepo->new( verbose => 1 );

Creates a new instance.

=over

=item B<verbose>

Boolean. If true, prints command output and status messages to C<STDOUT>. Defaults to C<0>.

=back

=head1 METHODS

=head2 C<install( ... )>

    my $pkg_info = $repo->install( $package_name, $version_constraint, %options );

Installs (if missing) and fetches the metadata for a package.

=over

=item B<$package_name>

The name of the package (e.g., C<zlib>, C<opencv>).