NAME

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

VERSION

       version 0.020

SYNOPSIS

        # planner/xs.pl

        load_extension('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.

perl v5.40.1                                       2025-05-11                               Dist::Build::XS(3pm)