blib_to_par

Builds a PAR distribution from the blib/ subdirectory under "path", or under the current directory if unspecified. If blib/ does not exist, it automatically runs Build, make, Build.PL or Makefile.PL to create it.

Returns the filename of the generated PAR distribution.

Valid parameters are:

path

Sets the path which contains the blib/ subdirectory from which the PAR distribution will be generated.

name, version, suffix

These attributes set the name, version and platform specific suffix of the distribution. Name and version can be automatically determined from the distributions META.yml or Makefile.PL files.

The suffix is generated from your architecture name and your version of perl by default.

dist

The output filename for the PAR distribution.

quiet

Set to true to suppress as much output as possible.

install_par

If only a single parameter is given, it is treated as the value for the "dist" parameter.

Valid named parameters are:

dist

The .par file to install. The heuristics outlined in the FUNCTIONS section above apply.

prefix

This string will be prepended to all installation paths. If it isn't specified, the environment variable "PERL_INSTALL_ROOT" is used as a prefix.

uninstall_shadows

This corresponds to the "uninstall_shadows" option of ExtUtils::Install. Quoting its manual: If "uninstall_shadows" is set to true, any differing versions throughout @INC will be uninstalled. This is "make install UNINST=1".

verbose

This corresponds to the "verbose" option of ExtUtils::Install. According to its manual: If "verbose" is true, will print out each file removed. This is "make install VERBINST=1". "verbose" values going up to 5 show increasingly more diagnostics output.

Default verbosity for PAR::Dist is 1.

If you're just going to install into the running perl like everything else, you can stop reading the rest of this section now.

Additionally, you can use several parameters to change the default installation destinations. You don't usually have to worry about this unless you are installing into a user-local directory. The following section outlines the parameter names and default settings:

  Parameter         From          To
  inst_lib          blib/lib      $Config{installsitelib} (*)
  inst_archlib      blib/arch     $Config{installsitearch}
  inst_script       blib/script   $Config{installscript}
  inst_bin          blib/bin      $Config{installbin}
  inst_man1dir      blib/man1     $Config{installman1dir}
  inst_man3dir      blib/man3     $Config{installman3dir}
  packlist_read                   $Config{sitearchexp}/auto/$name/.packlist
  packlist_write                  $Config{installsitearch}/auto/$name/.packlist

The "packlist_write" parameter is used to control where the .packlist file is written to. (Necessary for uninstallation.) The "packlist_read" parameter specifies a .packlist file to merge in if it exists. By setting any of the above installation targets to "undef", you can remove that target altogether. For example, passing "inst_man1dir => undef, inst_man3dir => undef" means that the contained manual pages won't be installed. This is not available for the packlists.

Again, the defaults will be the normal site paths from %Config.

(*) If the ".par"'s inst_archlib section (normally "blib/arch") isn't empty, the code in inst_lib (normally "blib/lib") is also installed into the inst_archlib path. This makes sense for XS modules. If, however, you override "inst_lib", this automatic conversion is also overridden! You can use the named parameter "auto_inst_lib_conversion => 1" to re-enable the conversion for custom inst_lib's.

Finally, you may specify a "custom_targets" parameter. Its value should be a reference to a hash of custom installation targets such as

  custom_targets => { 'blib/my_data' => '/some/path/my_data' }

You can use this to install the .par archives contents to arbitrary locations.

uninstall_par

Takes almost the same parameters as "install_par", but naturally, the installation target parameters do not apply. The only exception to this is the "packlist_read" parameter which specifies the .packlist file to read the list of installed files from. It defaults to "$Config::Config{installsitearch}/auto/$name/.packlist".

Additionally, the "uninstall_shadows" parameter of "install_par" isn't available.

sign_par

verify_par

Returns a boolean value indicating whether verification passed; $! is set to the return code of "Module::Signature::verify".

merge_par

  YAML:XS YAML YAML::Syck YAML::Tiny

Merges two or more PAR distributions into one. First argument must be the name of the distribution you want to merge all others into. Any following arguments will be interpreted as the file names of further PAR distributions to merge into the first one.

  merge_par('foo.par', 'bar.par', 'baz.par')

This will merge the distributions "foo.par", "bar.par" and "baz.par" into the distribution "foo.par". "foo.par" will be overwritten!

The original META.yml of "foo.par" is retained, but augmented with any "provides", "requires", "recommends", "build_requires", and "configure_requires" sections from the other ".par" files.

remove_man

The PAR archive will be extracted, stripped of all "man\d?" and "html" subdirectories and then repackaged into the original file.

get_meta

Takes one named parameter: dist. If only one parameter is passed, it is treated as the dist parameter. (Have a look at the description in the "FUNCTIONS" section above.)

Returns undef if no PAR archive or no META.yml within the archive were found.

parse_dist_name

Returns the results as a list in the above order. If any or all of the above cannot be determined, returns undef instead of the undetermined elements.

Supported formats are:

Math-Symbolic-0.502-x86_64-linux-gnu-thread-multi-5.8.7

Math-Symbolic-0.502

The ".tar.gz" or ".par" extensions as well as any preceding paths are stripped before parsing. Starting with "PAR::Dist" 0.22, versions containing a preceding "v" are parsed correctly.

This function is not exported by default.

generate_blib_stub

After running "generate_blib_stub" and injecting files into the blib directory, you can create a PAR distribution using "blib_to_par". This function is useful for creating custom PAR distributions from scratch. (I.e. not from an unpacked CPAN distribution) Example:

  use PAR::Dist;
  use File::Copy 'copy';

  generate_blib_stub(
    name => 'MyApp', version => '1.00'
  );
  copy('MyApp.pm', 'blib/lib/MyApp.pm');
  blib_to_par(); # generates the .par file!

"generate_blib_stub" will not overwrite existing files.

contains_binaries

Opens a PAR archive tries to determine whether that archive contains platform-specific binary code.

Takes one named parameter: dist. If only one parameter is passed, it is treated as the dist parameter. (Have a look at the description in the "FUNCTIONS" section above.)

Throws a fatal error if the PAR archive could not be found.

Returns one if the PAR was found to contain binary code and zero otherwise.