PDL::Core::Dev(3pm)

NAME
PDL::Core::Dev - PDL development module

SYNOPSIS
   use PDL::Core::Dev;

DESCRIPTION
This module encapsulates most of the stuff useful for PDL development and is often used from within Makefile.PL's.

BUILD MODES

  Old Skool
The original scheme, which still works, was one PDL module per ExtUtils::MakeMaker (EUMM) "module", i.e. directory. There has been work with Module::Build, but as that is now deprecated, it will not be further discussed. That module would generate a ".xs" and ".pm" file in its directory, according to its Makefile.PL, such as linking extra objects, or other libraries.

To have several distinct PDL modules in a CPAN distribution, you made several directories, each with a Makefile.PL. Parallel building was not normally possible between modules, though see PDL's top-level Makefile.PL as of about 2015, which gained a "coretest" target that did build in parallel despite subdirectories and "recursive make". Any change to any C code caused a rebuild of the whole ".xs" file (for Slices this was upwards of 40,000 lines), and being one compilation unit, it could not be parallelised.

  Multi-C files
As of 2.058, a new "multi-C" mode was added. For all internal PDL modules, and external ones that opted in (by adding a 5th, true, element to the array-ref describing the package). This creates one C file per operation, so parallel building is possible. This makes for quicker builds, both for those installing the package, and those developing it.

It can also avoid unnecessary rebuilds if only one operation got changed - it only recompiles that C file. This is possible due to some trickiness by PDL::PP, which detects if each C file that it would output is the same as the one already on disk, first removing any "#line" directives so that line renumbering will not force a rebuild, and not writing anything unless a real change happened.

It is opt-in because if the module adds C functions with "pp_addhdr" without scoping them appropriately, they get incorporated in each generated C file, which causes linking problems. Moving those to separate C files solves that.

But parallel building (without the "cleverness" of the "coretest" work) is only possible within each module.

  Deep mode
EUMM pure-Perl distributions in the modern era have a lib directory, whose structure matches the hierarchy of modules. PDL now uses this in its "Basic" subdirectory, so there is e.g. lib/PDL/Core.pm under that. As of EUMM 7.12 (shipped with Perl 5.26), it's also possible to put ".xs" files next to their respective ".pm" files, by giving a true value for "XSMULTI".

As of 2.096, another new mode was added, which automatically engages "multi-C" mode. This allows you to place your ".pd" file under a lib directory, whose location tells the build system its package name, which means the previous schemes' need to communicate that in each Makefile.PL is no more. Now, the configuration is communicated by each ".pd" file by setting values in a hash, e.g.:

  { no warnings 'once'; # pass info back to Makefile.PL
  $PDL::Core::Dev::EXTRAS{$::PDLMOD}{OBJECT} .= join '', map " $::PDLBASE/$_\$(OBJ_EXT)", qw(fftn);
  $PDL::Core::Dev::EXTRAS{$::PDLMOD}{DEFINE} .= qq{ -DFFT_FLOAT -DFFT_DOUBLE -DFFT_LDOUBLE};
  $PDL::Core::Dev::EXTRAS{$::PDLMOD}{INC} .= qq{ "-I$::PDLBASE"};
  }

This works because PDL needs to make an entry in the Makefile for each operation defined, which it does by loading the ".pd" file, and making its version of "pp_def" just record the operation name. As a side effect, the setting of the "EXTRAS" value can be seen by the build process.

To have the only Makefile.PL work in this new scheme, converting it from the previous one(s), you need to add this key to the "WriteMakefile" call:

  VERSION_FROM => 'lib/PDL/GSL/CDF.pd',

Note that the ones supplied by "pdlpp_stdargs" are added for you. You do need to provide overrides for "postamble" as before, and also "init_PM":

  {
  my @pd_srcs;
  package MY; # so that "SUPER" works right
  sub init_PM {
    my ($self) = @_;
    $self->SUPER::init_PM;
    @pd_srcs = ::pdlpp_eumm_update_deep($self);
  }
  sub postamble { ::pdlpp_postamble(@pd_srcs) }
  }

FUNCTIONS

  isbigendian
Is the machine big or little endian?

  print "Your machins is big endian.\n" if isbigendian();

returns 1 if the machine is big endian, 0 if little endian, or dies if neither. It uses the "byteorder" element of perl's %Config array.

   my $retval = isbigendian();

  trylink
a perl configure clone

  if (trylink 'libGL', '', 'char glBegin(); glBegin();', '-lGL') {
    $libs = '-lGLU -lGL';
    $have_GL = 1;
  } else {
    $have_GL = 0;
  }
  $maybe =
    trylink 'libwhatever', '', $body, $libs, $cflags,
        {MakeMaker=>1, Hide=>0, Clean=>1};

Try to link some C-code making up the body of a function with a given set of library specifiers

return 1 if successful, 0 otherwise

   trylink $infomsg, $include, $progbody, $libs [,$cflags,{OPTIONS}];

Takes 4 + 2 optional arguments.

•   an informational message to print (can be empty)

•   any commands to be included at the top of the generated C program (typically something like "#include "mylib.h"")

•   the body of the program (in function main)

•   library flags to use for linking. Preprocessing by MakeMaker should be performed as needed (see options and example).

•   compilation flags. For example, something like "-I/usr/local/lib". Optional argument. Empty if omitted.

•   OPTIONS

    MakeMaker
        Preprocess library strings in the way MakeMaker does things. This is advisable to ensure that your code will actually work after the link specs have been processed by MakeMaker.

    Hide
        Controls if linking output etc is hidden from the user or not. On by default but overridable with environment variable "HIDE_TRYLINK" if set.

    Clean
        Remove temporary files. Enabled by default. You might want to switch it off during debugging.

  generate_core_flags
prints on "STDOUT" XS text with core flags, for Core.xs.

  got_complex_version
  PDL::Core::Dev::got_complex_version($func_name, $num_params)

For a given function appearing in C99's "complex.h", will return a boolean of whether the system being compiled on has the complex version of that. E.g. for "sin", will test whether "csinl" exists (before 2.069, would only check for "csin", causing build failures on non-C99 compliant "libc" which mandates long-double versions).