.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test::Alien::Build 3"
.TH Test::Alien::Build 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Test::Alien::Build \- Tools for testing Alien::Build + alienfile
.SH VERSION
.IX Header "VERSION"
version 2.80
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& use Test2::V0;
\& use Test::Alien::Build;
\& 
\& # returns an instance of Alien::Build.
\& my $build = alienfile_ok q{
\&   use alienfile;
\& 
\&   plugin \*(AqMy::Plugin\*(Aq => (
\&     foo => 1,
\&     bar => \*(Aqstring\*(Aq,
\&     ...
\&   );
\& };
\& 
\& alien_build_ok \*(Aqbuilds okay.\*(Aq;
\& 
\& done_testing;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides some tools for testing Alien::Build and alienfile.  Outside of Alien::Build
core development, It is probably most useful for Alien::Build::Plugin developers.
.PP
This module also unsets a number of Alien::Build specific environment variables, in order to make tests
reproducible even when overrides are set in different environments.  So if you want to test those variables in
various states you should explicitly set them in your test script.  These variables are unset if they defined:
\&\f(CW\*(C`ALIEN_BUILD_PRELOAD\*(C'\fR \f(CW\*(C`ALIEN_BUILD_POSTLOAD\*(C'\fR \f(CW\*(C`ALIEN_INSTALL_TYPE\*(C'\fR.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS alienfile
.IX Subsection "alienfile"
.Vb 3
\& my $build = alienfile;
\& my $build = alienfile q{ use alienfile ... };
\& my $build = alienfile filename => \*(Aqalienfile\*(Aq;
.Ve
.PP
Create a Alien::Build instance from the given alienfile.  The first two forms are abbreviations.
.PP
.Vb 3
\& my $build = alienfile;
\& # is the same as
\& my $build = alienfile filename => \*(Aqalienfile\*(Aq;
.Ve
.PP
and
.PP
.Vb 3
\& my $build = alienfile q{ use alienfile ... };
\& # is the same as
\& my $build = alienfile source => q{ use alienfile ... };
.Ve
.PP
Except for the second abbreviated form sets the line number before feeding the source into Alien::Build
so that you will get diagnostics with the correct line numbers.
.IP source 4
.IX Item "source"
The source for the alienfile as a string.  You must specify one of \f(CW\*(C`source\*(C'\fR or \f(CW\*(C`filename\*(C'\fR.
.IP filename 4
.IX Item "filename"
The filename for the alienfile.  You must specify one of \f(CW\*(C`source\*(C'\fR or \f(CW\*(C`filename\*(C'\fR.
.IP root 4
.IX Item "root"
The build root.
.IP stage 4
.IX Item "stage"
The staging area for the build.
.IP prefix 4
.IX Item "prefix"
The install prefix for the build.
.SS alienfile_ok
.IX Subsection "alienfile_ok"
.Vb 4
\& my $build = alienfile_ok;
\& my $build = alienfile_ok q{ use alienfile ... };
\& my $build = alienfile_ok filename => \*(Aqalienfile\*(Aq;
\& my $build = alienfile_ok $build;
.Ve
.PP
Same as \f(CW\*(C`alienfile\*(C'\fR above, except that it runs as a test, and will not throw an exception
on failure (it will return undef instead).
.PP
[version 1.49]
.PP
As of version 1.49 you can also pass in an already formed instance of Alien::Build.  This
allows you to do something like this:
.PP
.Vb 5
\& subtest \*(Aqa subtest\*(Aq => sub {
\&   my $build = alienfile q{ use alienfile; ... };
\&   alienfile_skip_if_missing_prereqs; # skip if alienfile prereqs are missing
\&   alienfile_ok $build;  # delayed pass/fail for the compile of alienfile
\& };
.Ve
.SS alienfile_skip_if_missing_prereqs
.IX Subsection "alienfile_skip_if_missing_prereqs"
.Vb 2
\& alienfile_skip_if_missing_prereqs;
\& alienfile_skip_if_missing_prereqs $phase;
.Ve
.PP
Skips the test or subtest if the prereqs for the alienfile are missing.
If \f(CW$phase\fR is not given, then either \f(CW\*(C`share\*(C'\fR or \f(CW\*(C`system\*(C'\fR will be
detected.
.SS alien_install_type_is
.IX Subsection "alien_install_type_is"
.Vb 2
\& alien_install_type_is $type;
\& alien_install_type_is $type, $name;
.Ve
.PP
Simple test to see if the install type is what you expect.
\&\f(CW$type\fR should be one of \f(CW\*(C`system\*(C'\fR or \f(CW\*(C`share\*(C'\fR.
.SS alien_download_ok
.IX Subsection "alien_download_ok"
.Vb 2
\& my $file = alien_download_ok;
\& my $file = alien_download_ok $name;
.Ve
.PP
Makes a download attempt and test that a file or directory results.  Returns
the file or directory if successful.  Returns \f(CW\*(C`undef\*(C'\fR otherwise.
.SS alien_extract_ok
.IX Subsection "alien_extract_ok"
.Vb 4
\& my $dir = alien_extract_ok;
\& my $dir = alien_extract_ok $archive;
\& my $dir = alien_extract_ok $archive, $name;
\& my $dir = alien_extract_ok undef, $name;
.Ve
.PP
Makes an extraction attempt and test that a directory results.  Returns
the directory if successful.  Returns \f(CW\*(C`undef\*(C'\fR otherwise.
.SS alien_build_ok
.IX Subsection "alien_build_ok"
.Vb 4
\& my $alien = alien_build_ok;
\& my $alien = alien_build_ok $name;
\& my $alien = alien_build_ok { class => $class };
\& my $alien = alien_build_ok { class => $class }, $name;
.Ve
.PP
Runs the download and build stages.  Passes if the build succeeds.  Returns an instance
of Alien::Base which can be passed into \f(CW\*(C`alien_ok\*(C'\fR from Test::Alien.  Returns
\&\f(CW\*(C`undef\*(C'\fR if the test fails.
.PP
Options
.IP class 4
.IX Item "class"
The base class to use for your alien.  This is Alien::Base by default.  Should
be a subclass of Alien::Base, or at least adhere to its API.
.SS alien_build_clean
.IX Subsection "alien_build_clean"
.Vb 1
\& alien_build_clean;
.Ve
.PP
Removes all files with the current build, except for the runtime prefix.
This helps test that the final install won't depend on the build files.
.SS alien_clean_install
.IX Subsection "alien_clean_install"
.Vb 1
\& alien_clean_install;
.Ve
.PP
Runs \f(CW\*(C`$build\->clean_install\*(C'\fR, and verifies it did not crash.
.SS alien_checkpoint_ok
.IX Subsection "alien_checkpoint_ok"
.Vb 2
\& alien_checkpoint_ok;
\& alien_checkpoint_ok $test_name;
.Ve
.PP
Test the checkpoint of a build.
.SS alien_resume_ok
.IX Subsection "alien_resume_ok"
.Vb 2
\& alien_resume_ok;
\& alien_resume_ok $test_name;
.Ve
.PP
Test a resume a checkpointed build.
.SS alien_rc
.IX Subsection "alien_rc"
.Vb 1
\& alien_rc $code;
.Ve
.PP
Creates \f(CW\*(C`rc.pl\*(C'\fR file in a temp directory and sets ALIEN_BUILD_RC.  Useful for testing
plugins that should be called from \f(CW\*(C`~/.alienbuild/rc.pl\*(C'\fR.  Note that because of the
nature of how the \f(CW\*(C`~/.alienbuild/rc.pl\*(C'\fR file works, you can only use this once!
.SS alien_subtest
.IX Subsection "alien_subtest"
.Vb 3
\& alien_subtest $test_name => sub {
\&   ...
\& };
.Ve
.PP
Clear the build object and clear the build object before and after the subtest.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP Alien 4
.IX Item "Alien"
.PD 0
.IP alienfile 4
.IX Item "alienfile"
.IP Alien::Build 4
.IX Item "Alien::Build"
.IP Test::Alien 4
.IX Item "Test::Alien"
.PD
.SH AUTHOR
.IX Header "AUTHOR"
Author: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Diab Jerius (DJERIUS)
.PP
Roy Storey (KIWIROY)
.PP
Ilya Pavlov
.PP
David Mertens (run4flat)
.PP
Mark Nunberg (mordy, mnunberg)
.PP
Christian Walde (Mithaldu)
.PP
Brian Wightman (MidLifeXis)
.PP
Zaki Mughal (zmughal)
.PP
mohawk (mohawk2, ETJ)
.PP
Vikas N Kumar (vikasnkumar)
.PP
Flavio Poletti (polettix)
.PP
Salvador Fandiño (salva)
.PP
Gianni Ceccarelli (dakkar)
.PP
Pavel Shaydo (zwon, trinitum)
.PP
Kang-min Liu (劉康民, gugod)
.PP
Nicholas Shipp (nshp)
.PP
Juan Julián Merelo Guervós (JJ)
.PP
Joel Berger (JBERGER)
.PP
Petr Písař (ppisar)
.PP
Lance Wicks (LANCEW)
.PP
Ahmad Fatoum (a3f, ATHREEF)
.PP
José Joaquín Atria (JJATRIA)
.PP
Duke Leto (LETO)
.PP
Shoichi Kaji (SKAJI)
.PP
Shawn Laffan (SLAFFAN)
.PP
Paul Evans (leonerd, PEVANS)
.PP
Håkon Hægland (hakonhagland, HAKONH)
.PP
nick nauwelaerts (INPHOBIA)
.PP
Florian Weimer
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2011\-2022 by Graham Ollis.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.