view release on metacpan or  search on metacpan

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

=back

=head1 CONSTRUCTOR

    my $builder = Affix::Build->new( %params );

Creates a new compiler instance.

=over

=item * B<C<name>>: The base name of the resulting library (default: C<'affix_lib'>). The compiler will automatically append the OS-specific extension (C<.dll> on Windows, C<.dylib> on macOS, C<.so> on Linux).

=item * B<C<version>>: Optional version string to append to the library name.

=item * B<C<build_dir>>: The directory where intermediate artifacts and the final library will be written. If not provided, a temporary directory is created via L<Path::Tiny>.

=item * B<C<clean>>: If true, the generated C<build_dir> and all its contents will be deleted when the object is destroyed (default: C<0>).

=item * B<C<debug>>: If true, the exact system commands executed by the compiler will be printed to C<STDERR> (default: C<0>).

=item * B<C<flags>>: A HashRef of global flags applied across all files. Keys can be C<cflags>, C<cxxflags>, and C<ldflags>.

=item * B<C<os>>: Override the detected operating system (defaults to C<$^O>).

=back

=head1 METHODS

=head2 C<add( $input, %args )>

Adds a source file to the build manifest.

    $builder->add( 'path/to/file.c' );
    $builder->add( 'file.c', flags => ['-DDEBUG', '-Wall'] );
    $builder->add( \"int main(){}", lang => 'c' );

=over

=item * B<File Path:> If C<$input> is a string, it is treated as a file path. The compiler auto-detects the language based on the extension.

=item * B<Inline Code:> If C<$input> is a SCALAR reference, you B<must> provide the C<lang> argument (e.g., C<'c'>, C<'rust'>) so the compiler knows how to handle it.

=item * B<C<flags>>: An ArrayRef or space-separated string of compiler flags specific to this source file.

=back

=head2 C<compile_and_link( )>

Performs the build process:

=over

=item 1. Inspects added sources to determine the Build Strategy.

=item 2. Compiles all sources to their appropriate intermediate or final formats.

=item 3. Links the artifacts (if necessary) into a shared library.

=back

Returns a L<Path::Tiny> object pointing to the generated shared library. Dies with a detailed error message (including
STDOUT/STDERR of the failed command) if compilation fails.

=head2 C<link( )>

An alias for C<compile_and_link()>. Safe to call multiple times; it will return the cached library handle if the build
has already completed.

=head1 SUPPORTED LANGUAGES

C<Affix::Build> attempts to locate the necessary binaries in your system C<PATH>.

=head3 C / C++

Automatically handles C<-fPIC> on non-Windows platforms.

=over

=item * B<Extensions:> C<.c>, C<.cpp>, C<.cxx>, C<.cc>

=item * B<Known Compilers:> C<cc>, C<gcc>, C<clang>, C<cl> (MSVC), C<c++>, C<g++>, C<icx>.

=back

=head3 Rust

=over

=item * B<Extensions:> C<.rs>

=item * B<Compiler:> C<rustc>

=back

B<Windows Note:> If running under Strawberry Perl (MinGW), you must have the GNU ABI target installed via C<rustup> so
the objects can link against Perl's GCC:

    rustup target add x86_64-pc-windows-gnu

=head3 C# / F#

Uses B<NativeAOT> to compile .NET code directly to unmanaged machine code. Your C# source must tag exported methods
with C<[UnmanagedCallersOnly]>.

=over

=item * B<Extensions:> C<.cs>, C<.fs>

=item * B<Compiler:> C<dotnet> (SDK 8.0 or newer required)

=back

=head3 Go

=over

=item * B<Extensions:> C<.go>

=item * B<Compiler:> C<go> or C<gccgo>

=back