Alien-Build

 view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    documents:

    Alien::Build::Manual::Alien

      A broad overview of Alien-Build and its ecosystem.

    Alien::Build::Manual::AlienUser

      For users of an Alien::libfoo that is implemented using Alien::Base.
      (The developer of Alien::libfoo should provide the documentation
      necessary, but if not, this is the place to start).

    Alien::Build::Manual::AlienAuthor

      If you are writing your own Alien based on Alien::Build and
      Alien::Base.

    Alien::Build::Manual::FAQ

      If you have a common question that has already been answered, like
      "How do I use alienfile with some build system".

    Alien::Build::Manual::PluginAuthor

      This is for the brave souls who want to write plugins that will work
      with Alien::Build + alienfile.

    Alien::Build::Manual::Security

      If you are concerned that Aliens might be downloading tarballs off
      the internet, then this is the place for you. This will discuss some
      of the risks of downloading (really any) software off the internet
      and will give you some tools to remediate these risks.

    Note that you will not usually create a Alien::Build instance directly,
    but rather be using a thin installer layer, such as Alien::Build::MM
    (for use with ExtUtils::MakeMaker) or Alien::Build::MB (for use with
    Module::Build). One of the goals of this project is to remain installer
    agnostic.

CONSTRUCTORS

 new

     my $build = Alien::Build->new;

    This creates a new empty instance of Alien::Build. Normally you will
    want to use load below to create an instance of Alien::Build from an
    alienfile recipe.

 load

     my $build = Alien::Build->load($alienfile);

    This creates an Alien::Build instance with the given alienfile recipe.

 resume

     my $build = Alien::Build->resume($alienfile, $root);

    Load a checkpointed Alien::Build instance. You will need the original
    alienfile and the build root (usually _alien), and a build that had
    been properly checkpointed using the checkpoint method below.

PROPERTIES

    There are three main properties for Alien::Build. There are a number of
    properties documented here with a specific usage. Note that these
    properties may need to be serialized into something primitive like JSON
    that does not support: regular expressions, code references of blessed
    objects.

    If you are writing a plugin (Alien::Build::Plugin) you should use a
    prefix like "plugin_name" (where name is the name of your plugin) so
    that it does not interfere with other plugin or future versions of
    Alien::Build. For example, if you were writing
    Alien::Build::Plugin::Fetch::NewProtocol, please use the prefix
    plugin_fetch_newprotocol:

     sub init
     {
       my($self, $meta) = @_;
     
       $meta->prop( plugin_fetch_newprotocol_foo => 'some value' );
     
       $meta->register_hook(
         some_hook => sub {
           my($build) = @_;
           $build->install_prop->{plugin_fetch_newprotocol_bar} = 'some other value';
           $build->runtime_prop->{plugin_fetch_newprotocol_baz} = 'and another value';
         }
       );
     }

    If you are writing a alienfile recipe please use the prefix my_:

     use alienfile;
     
     meta_prop->{my_foo} = 'some value';
     
     probe sub {
       my($build) = @_;
       $build->install_prop->{my_bar} = 'some other value';
       $build->install_prop->{my_baz} = 'and another value';
     };

    Any property may be used from a command:

     probe [ 'some command %{.meta.plugin_fetch_newprotocol_foo}' ];
     probe [ 'some command %{.install.plugin_fetch_newprotocol_bar}' ];
     probe [ 'some command %{.runtime.plugin_fetch_newprotocol_baz}' ];
     probe [ 'some command %{.meta.my_foo}' ];
     probe [ 'some command %{.install.my_bar}' ];
     probe [ 'some command %{.runtime.my_baz}' ];

 meta_prop

     my $href = $build->meta_prop;
     my $href = Alien::Build->meta_prop;

    Meta properties have to do with the recipe itself, and not any

README  view on Meta::CPAN

    Returns the Alien::Build::Interpolate instance for the Alien::Build
    class.

 has_hook

     my $bool = $build->meta->has_hook($name);
     my $bool = Alien::Build->has_hook($name);

    Returns if there is a usable hook registered with the given name.

 register_hook

     $build->meta->register_hook($name, $instructions);
     Alien::Build->meta->register_hook($name, $instructions);

    Register a hook with the given name. $instruction should be either a
    code reference, or a command sequence, which is an array reference.

 default_hook

     $build->meta->default_hook($name, $instructions);
     Alien::Build->meta->default_hook($name, $instructions);

    Register a default hook, which will be used if the alienfile does not
    register its own hook with that name.

 around_hook

     $build->meta->around_hook($hook_name, $code);
     Alien::Build->meta->around_hook($hook_name, $code);

    Wrap the given hook with a code reference. This is similar to a Moose
    method modifier, except that it wraps around the given hook instead of
    a method. For example, this will add a probe system requirement:

     $build->meta->around_hook(
       probe => sub {
         my $orig = shift;
         my $build = shift;
         my $type = $orig->($build, @_);
         return $type unless $type eq 'system';
         # also require a configuration file
         if(-f '/etc/foo.conf')
         {
           return 'system';
         }
         else
         {
           return 'share';
         }
       },
     );

 after_hook

     $build->meta->after_hook($hook_name, sub {
       my(@args) = @_;
       ...
     });

    Execute the given code reference after the hook. The original arguments
    are passed into the code reference.

 before_hook

     $build->meta->before_hook($hook_name, sub {
       my(@args) = @_;
       ...
     });

    Execute the given code reference before the hook. The original
    arguments are passed into the code reference.

 apply_plugin

     Alien::Build->meta->apply_plugin($name);
     Alien::Build->meta->apply_plugin($name, @args);

    Apply the given plugin with the given arguments.

ENVIRONMENT

    Alien::Build responds to these environment variables:

    ALIEN_BUILD_LOG

      The default log class used. See Alien::Build::Log and
      Alien::Build::Log::Default.

    ALIEN_BUILD_PKG_CONFIG

      Override the logic in Alien::Build::Plugin::PkgConfig::Negotiate
      which chooses the best pkg-config plugin.

    ALIEN_BUILD_POSTLOAD

      semicolon separated list of plugins to automatically load after
      parsing your alienfile.

    ALIEN_BUILD_PRELOAD

      semicolon separated list of plugins to automatically load before
      parsing your alienfile.

    ALIEN_BUILD_RC

      Perl source file which can override some global defaults for
      Alien::Build, by, for example, setting preload and postload plugins.

    ALIEN_DOWNLOAD_RULE

      This value determines the rules by which types of downloads are
      allowed. The legal values listed under "download_rule", plus default
      which will be the default for the current version of Alien::Build.
      For this version that default is warn.

    ALIEN_INSTALL_NETWORK

      If set to true (the default), then network fetch will be allowed. If
      set to false, then network fetch will not be allowed.

      What constitutes a local vs. network fetch is determined based on the
      start_url and local_source meta properties. An alienfile or plugin
      could override this detection (possibly inappropriately), so this
      variable is not a substitute for properly auditing of Perl modules
      for environments that require that.

    ALIEN_INSTALL_TYPE

      If set to share or system, it will override the system detection
      logic. If set to default, it will use the default setting for the

README  view on Meta::CPAN

      To keep the interface consistent among Aliens, the consumer of the
      fallback opt-in Alien may fallback on the Alien if the environment
      variable ALIEN_INSTALL_TYPE is set to any value. The rationale is
      that by setting this environment variable the user is aware that
      Alien modules may be installed and have indicated consent. The actual
      implementation of this, by its nature would have to be in the
      consuming CPAN module.

    DESTDIR

      This environment variable will be manipulated during a destdir
      install.

    PKG_CONFIG

      This environment variable can be used to override the program name
      for pkg-config when using the command line plugin:
      Alien::Build::Plugin::PkgConfig::CommandLine.

    ftp_proxy, all_proxy

      If these environment variables are set, it may influence the Download
      negotiation plugin Alien::Build::Plugin::Download::Negotiate. Other
      proxy variables may be used by some Fetch plugins, if they support
      it.

SUPPORT

    The intent of the Alien-Build team is to support the same versions of
    Perl that are supported by the Perl toolchain. As of this writing that
    means 5.16 and better.

    Please feel encouraged to report issues that you encounter to the
    project GitHub Issue tracker:

    https://github.com/PerlAlien/Alien-Build/issues

    Better if you can fix the issue yourself, please feel encouraged to
    open pull-request on the project GitHub:

    https://github.com/PerlAlien/Alien-Build/pulls

    If you are confounded and have questions, join us on the #native
    channel on irc.perl.org. The Alien-Build developers frequent this
    channel and can probably help point you in the right direction. If you
    don't have an IRC client handy, you can use this web interface:

    https://chat.mibbit.com/?channel=%23native&server=irc.perl.org

SEE ALSO

    Alien::Build::Manual::AlienAuthor, Alien::Build::Manual::AlienUser,
    Alien::Build::Manual::Contributing, Alien::Build::Manual::FAQ,
    Alien::Build::Manual::PluginAuthor

    alienfile, Alien::Build::MM, Alien::Build::Plugin, Alien::Base, Alien

THANKS

    Alien::Base was originally written by Joel Berger, the rest of this
    project would not have been possible without him getting the project
    started. Thanks to his support I have been able to augment the original
    Alien::Base system with a reliable set of tools (Alien::Build,
    alienfile, Test::Alien), which make up this toolset.

    The original Alien::Base is still copyright (c) 2012-2020 Joel Berger.
    It has the same license as the rest of the Alien::Build and related
    tools distributed as Alien-Build. Joel Berger thanked a number of
    people who helped in in the development of Alien::Base, in the
    documentation for that module.

    I would also like to acknowledge the other members of the PerlAlien
    github organization, Zakariyya Mughal (sivoais, ZMUGHAL) and mohawk
    (ETJ). Also important in the early development of Alien::Build were the
    early adopters Chase Whitener (genio, CAPOEIRAB, author of
    Alien::libuv), William N. Braswell, Jr (willthechill, WBRASWELL, author
    of Alien::JPCRE2 and Alien::PCRE2) and Ahmad Fatoum (a3f, ATHREEF,
    author of Alien::libudev and Alien::LibUSB).

    The Alien ecosystem owes a debt to Dan Book, who goes by Grinnz on IRC,
    for answering question about how to use Alien::Build and friends.

AUTHOR

    Author: Graham Ollis <plicease@cpan.org>

    Contributors:

    Diab Jerius (DJERIUS)

    Roy Storey (KIWIROY)

    Ilya Pavlov

    David Mertens (run4flat)

    Mark Nunberg (mordy, mnunberg)

    Christian Walde (Mithaldu)

    Brian Wightman (MidLifeXis)

    Zaki Mughal (zmughal)

    mohawk (mohawk2, ETJ)

    Vikas N Kumar (vikasnkumar)

    Flavio Poletti (polettix)

    Salvador Fandiño (salva)

    Gianni Ceccarelli (dakkar)

    Pavel Shaydo (zwon, trinitum)

    Kang-min Liu (劉康民, gugod)

    Nicholas Shipp (nshp)

    Juan Julián Merelo Guervós (JJ)

    Joel Berger (JBERGER)

    Petr Písař (ppisar)