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

perl v5.40.0                                       2025-02-04                                PDL::Core::Dev(3pm)