Ubuntu Manpage: PDL::Core::Dev - PDL development module

name
synopsis
description
build modes
functions

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).