view release on metacpan or  search on metacpan

lib/Affix/Build.pod  view on Meta::CPAN

=pod

=encoding utf-8

=head1 NAME

Affix::Build - Robust, Polyglot Build System for FFI Extensions

=head1 SYNOPSIS

    use v5.40;
    use Affix::Build;
    use Affix;

    # Example 1: Single Language (Rust)
    my $rust = Affix::Build->new( name => 'my_rust_lib' );

    $rust->add( \<<~'RUST', lang => 'rust' );
        #[no_mangle]
        pub extern "C" fn add(a: i32, b: i32) -> i32 { a + b }
    RUST

    my $rust_dll = $rust->link();

    # Example 2: Polyglot (C and Go)
    my $mix = Affix::Build->new(
        name      => 'hybrid_lib',
        flags     => { cflags => '-O3', ldflags => '-L/opt/lib' },
        debug     => 1
    );

    # Add file with per-file compiler overrides
    $mix->add('src/wrapper.c', flags => '-DDEBUG');
    $mix->add('src/core.go');

    my $poly_dll = $mix->link();

=head1 DESCRIPTION

C<Affix::Build> is a cross-platform compilation utility designed to generate shared libraries (C<.dll>, C<.so>,
C<.dylib>) from source code in over 20 different programming languages.

While originally developed to compile test fixtures for the Affix suite, it has evolved into a robust tool for creating
polyglot extensions. It abstracts away the complexity of invoking various compilers, normalizing object file
extensions, handling platform-specific linker flags (such as MinGW vs. MSVC on Windows), and ensuring that language
runtimes (like the Go GC or .NET Runtime) are correctly initialized.

It serves as a powerful, polyglot alternative to C<Inline::*> modules—allowing you to write native code in your
language of choice and instantly bind to it from Perl using L<Affix>.

=head2 Build Strategies

The builder automatically selects the optimal strategy based on the input sources:

=over

=item 1. B<Native Toolchain Strategy> (Single Language)

If you provide source files for only B<one> language, C<Affix::Build> delegates the entire build process to that
language's native toolchain (e.g., C<go build -buildmode=c-shared>, C<rustc --crate-type cdylib>, C<dotnet publish>).
This ensures that the language's standard library and runtime environment are configured exactly as intended by its
maintainers.