view release on metacpan or  search on metacpan

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

package Alien::YARA;

use strict;
use warnings;
use version;

our $VERSION   = qv('v0.0.6');
our $AUTHORITY = 'cpan:MANWAR';

use parent 'Alien::Base';

=encoding utf-8

=head1 NAME

Alien::YARA - Find or download and install the YARA malware analysis library

=head1 VERSION

Version v0.0.6

=head1 SYNOPSIS

In your C<Makefile.PL> or C<Build.PL>:

 use Alien::Build::MM;
 my $abmm = Alien::Build::MM->new;

 WriteMakefile($abmm->mm_args(
     ...
     PREREQ_PM => {
         'Alien::YARA' => '0.01',
     },
 ));

In your Perl module code:

 use Alien::YARA;
 use FFI::Platypus;

 my $ffi = FFI::Platypus->new( api => 2 );
 $ffi->lib( Alien::YARA->dynamic_libs );

 # Now attach your C functions
 $ffi->attach( 'yr_initialize' => [] => 'int' );

=head1 DESCRIPTION

This module acts as an encapsulation layer for the YARA C library (C<libyara>).
It checks your host system to see if YARA is already installed via native package
management (like C<apt>, C<homebrew>, or C<pkgconf>). If it cannot find a suitable
global version, it automatically downloads the official YARA source code,
compiles it, and isolates the binaries locally within your Perl library tree.

This makes bundling dependencies for FFI-based modules like L<YaraFFI> perfectly
cross-platform across Linux, macOS, and Windows.

=head1 METHODS

This class inherits all methods from L<Alien::Base>. The most critical ones for FFI usage are:

=head2 dist_dir

 my $dir = Alien::YARA->dist_dir;

Returns the local installation directory if a C<share> install was performed.

=head2 dynamic_libs

 my @libs = Alien::YARA->dynamic_libs;
 my $lib  = $libs[0];

Returns a list of paths to the shared objects or dynamic libraries (C<.so>, C<.dylib>, C<.dll>).
Pass this directly into your L<FFI::Platypus> instantiation.

=head2 cflags

 my $cflags = Alien::YARA->cflags;

Returns the compiler flags needed to compile an XS module against C<libyara>.

=head2 libs

 my $libs = Alien::YARA->libs;

Returns the linker flags needed to link an XS module against C<libyara>.

=head1 SEE ALSO

=over 4

=item * L<YaraFFI> - The primary FFI interface built on top of this module.

=item * L<Alien::Base> - The base framework powering this installer wrapper.

=item * L<Alien::Build> - The underlying tools used to configure, download, and build YARA.

=item * L<https://github.com/VirusTotal/yara> - The official YARA open-source repository.

=back

=head1 AUTHOR

Mohammad Sajid Anwar, C<< <mohammad.anwar at yahoo.com> >>