NAME
Dist::Zilla::Plugin::Alien - Use Alien::Base with Dist::Zilla
VERSION
version 0.024
SYNOPSIS
In your dist.ini:
name = Alien-myapp
[Alien]
repo = http://myapp.org/releases
bins = myapp myapp_helper
# the following parameters are based on the dist name automatically
name = myapp
pattern_prefix = myapp-
pattern_version = ([\d\.]+)
pattern_suffix = \.tar\.gz
pattern = myapp-([\d\.]+)\.tar\.gz
# commands used to build (optional)
build_command = %c --prefix=%s
# ...
# commands uses to install (optional)
install_command = make installDESCRIPTION
NOTE: This module uses the older, and still supported, but not actively developed Alien::Base::ModuleBuild interface for installing aliens. You should use Dist::Zilla::Plugin::AlienBuild for new Aliens, and consider migration for older code as well.
This is a simple wrapper around Alien::Base, to make it very simple to generate a distribution that uses it. You only need to make a module like in this case Alien::myapp which extends Alien::Base and additionally a url that points to the path where the downloadable .tar.gz of the application or library can be found. For more informations about the parameter, please checkout also the Alien::Base documentation. The repo paramter is automatically taken apart to supply the procotol, host and other parameters for Alien::Base.
Warning: Please be aware that Alien::Base uses Module::Build, which means you shouldn't have Dist::Zilla::Plugin::MakeMaker loaded. For our case, this means, you can't just easily use it together with the common Dist::Zilla::PluginBundle::Basic, because this includes it. As alternative you can use Dist::Zilla::PluginBundle::Alien which is also included in this distribution.
You should also consider using Dist::Zilla::Plugin::AlienBuild for new development, as it uses the more modern flexible installer alienfile + Alien::Build.
ATTRIBUTES
repo
The only required parameter, defines the path for the packages of the product you want to alienfy. This must not include the filename.
To indicate a local repository use the file: scheme:
# located in the base directory
repo = file:.
# located in the inc/ directory relative to the base
repo = file:incpattern
The pattern is used to define the filename to be expected from the repo of the alienfied product. It is set together out of pattern_prefix, pattern_version and pattern_suffix. pattern_prefix is by default "name" together with a dash.
exact_filename
Instead of providing a pattern you may use this to set the exact filename.
bins
A space or tab seperated list of all binaries that should be wrapped to be executable from the perl environment (if you use perlbrew or local::lib this also guarantees that its available via the PATH).
NOTE: If you set this, the build will use a custom subclass of Alien::Base::ModuleBuild in order to only install the wrapper scripts for a share install.
name
The name of the Alien package, this is used for the pattern matching filename. If none is given, then the name of the distribution is used, but the Alien- is cut off.
build_command
The ordered sequence of commands used to build the distribution (passed to the alien_build_commands option). This is optional.
# configure then make
build_command = %c --prefix=%s
build_command = makeinstall_command
The ordered sequence of commands used to install the distribution (passed to the alien_install_commands option). This is optional.
install_command = make installtest_command
The ordered sequence of commands used to test the distribution (passed to the alien_test_commands option). This is optional, and not often used.
test_command = make checkisolate_dynamic
If set to true, then dynamic libraries will be isolated from the static libraries when install_type=share is used. This is recommended for XS modules where static libraries are more reliable. Dynamic libraries (.dll, .so, etc) are still available and can easily be used by FFI modules.
isolate_dynamic = 1Usage of this attribute will bump the requirement of Alien::Base up to 0.005 for your distribution.
autoconf_with_pic
If set to true (the default), then --with-pic will be passed to autoconf style configure scripts. This usually enables position independent code which is desirable if you are using static libraries to build XS modules. Usually, if the autoconf does not recognize --with-pic it will ignore it, but some configure scripts which are not managed by autoconf may complain and die with this option.
; only if you know configure will die with --with-pic
autoconf_with_pic = 0Usage of this attribute will bump the requirement of Alien::Base up to 0.005 for your distribution.
inline_auto_include
List of header files to automatically include (see Inline::C#auto_include) when the Alien module is used with Inline::C or Inline::CPP.
msys
Force the use of Alien::MSYS when building on Windows. Normally this is only done if Alien::Base::ModuleBuild can detect that you are attempting to use an autotools style configure script.
bin_requires
Require the use of a binary tool Alien distribution. You can optionally specify a version using the equal = sign.
[Alien]
bin_requires = Alien::patch
bin_requires = Alien::gmake = 0.03stage_install
If set to true, Alien packages are installed directly into the blib directory by the `./Build' command rather than to the final location during the `./Build install` step.
helper
Defines helpers. You can specify the content of the helper (which will be evaluated in Alien::Base::ModuleBuild during the build/install step) using the equal = sign.
[Alien]
helper = mytool = '"mytool --foo --bar"'provides_cflags
Sets the alien_provides_cflags property for Alien::Base::ModuleBuild.
provides_libs
Sets the alien_provides_libs property for Alien::Base::ModuleBuild.
version_check
Sets the alien_version_check property for Alien::Base::ModuleBuild.
env
Sets the alien_env property for Alien::Base::ModuleBuild. You can specify the content of the environment using the equal = sign. Note that values are interpolated, and allow variables and helpers.
[Alien]
helper = path = 'require Config;$Config{path_sep}$ENV{PATH}'
; sets PATH to /extra/path:$PATH on UNIX, /extra/path;$PATH on Windows
env = PATH = /extra/path%{path}
; sets FOO to 1
env = FOO = 1There is no default value, so this is illegal:
[Alien]
; won't build!
env = FOONote that setting an environment variable to the empty string ('') is not portable. In particular it will work on Unix as you might expect, but in Windows it will actually unset the environment variable, which may not be what you intend.
[Alien]
; works but not consistent
; over all platforms
env = FOO =InstallRelease
The method Alien::Base is using would compile the complete Alien 2 times, if you use it in combination with Dist::Zilla::Plugin::InstallRelease. One time at the test, and then again after release. With a small trick, you can avoid this. You can use Dist::Zilla::Plugin::Run to add an additional test which installs out of the unpacked distribution for the testing:
[Run::Test]
run_if_release = ./Build installThis will do the trick :). Be aware, that you need to add this plugin after [ModuleBuild]. You can use Dist::Zilla::PluginBundle::Author::GETTY, which directly use this trick in the right combination.
SEE ALSO
- Alien::Base
-
Base class for aliens
- Alien::Base::ModuleBuild
-
Installer this plugin uses for building Aliens.
- alienfile + Alien::Build
-
Modern pluggable installer alternative to Alien::Base::ModuleBuild.
- Dist::Zilla::Plugin::AlienBuild
-
Alternative Dist::Zilla plugin that uses alienfile + Alien::Build.
BUGS
Please report any bugs or feature requests on the bugtracker website https://github.com/PerlAlien/Dist-Zilla-Plugin-Alien/issues
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
AUTHOR
Torsten Raudssus <torsten@raudss.us>
COPYRIGHT AND LICENSE
This software is copyright (c) 2013 by Torsten Raudssus.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.