NAME

Dist::Build::XS - An XS implementation for Dist::Build

VERSION

version 0.018

SYNOPSIS

# planner/xs.pl

load_module('Dist::Build::XS');
add_xs(
  module        => 'Foo::Bar',
  extra_sources => [ glob 'src/*.c' ],
  libraries     => [ 'foo' ],
);

DESCRIPTION

This module implements support for XS for Dist::Build.

METHODS

add_xs

This method takes the following named arguments, all optional:

• module

  The name of the module to be compiled. This defaults to $main_module unless file is given, in which case the name is derived from the path.

• version

  The version of the module, defaulting to the dist version.

• file

  The name of the XS file. By default it's derived from the $module_name, e.g. lib/Foo/Bar.xs for Foo::Bar.

• defines

  This hash contains defines for the C files. E.g. { DEBUG => 1 }.

• include_dirs

  A list of directories to add to the include path. For the xs file the directory it is in is automatically added to this list.

• extra_sources

  A list of C files to compile with this module. Instead of just a name, entries can also be a hash with the following entries:

  • source

    The name of the input file. Mandatory.

  • object

    The name of the object that will be compiled. Will be derive from the source name by default.

  • include_dirs

    An array containing additional include directories for this objects

  • defines

    A hash containing additional defines for this object.

  • flags

    An array containing additional flags for this compilation.

• extra_objects

  A list of object files to link with the module.

• extra_compiler_flags

  Additional flags to feed to the compiler. This can either be an array or a (shell-quoted) string.

• extra_sources

  Extra C files to compile with this module.

• library_dirs

  Extra libraries to find libraries in.

• libraries

  Libraries to link to.

• extra_linker_flags

  Additional flags to feed to the compiler. This can either be an array or a (shell-quoted) string.

auto_xs

This method is like add_xs, except that instead of taking module or file named arguments, it takes a dir argument (defaulting to 'lib'). It will search that directory for all XS files, and build them with the other arguments passed to this function.

EXTENSIONS

Various extensions exist that modify the behavior of add_xs. Among these are:

• Dist::Build::XS::Import

  This adds an import argument to imports include directories and compilation flags exported by other modules using Dist::Build::XS::Export.

• Dist::Build::XS::WriteConstants

  This adds a write_constants argument, integrating ExtUtils::Constant.

• Dist::Build::XS::Alien

  This adds an alien argument to link to libraries using Alien::Base.

• Dist::Build::XS::PkgConfig

  This adds a pkg_config argument to link to libraries using pkg-config files.

AUTHOR

Leon Timmermans <fawaka@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2024 by Leon Timmermans.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.