From 3f5788ebbed10b8c9c36b817c682186068dcddf9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harald=20J=C3=B6rg?= Date: Fri, 14 Jun 2024 22:41:27 +0200 Subject: [PATCH] More stuff for the DeveloperGuide, as suggested in GitHub#481, adjusted after review: * Basic/Pod/DeveloperGuide.pod: Delete the sections "Access to PDL's configuration" and "Ingesting an external PDL module". Document $::PP_VERBOSE and $PDL::Graphics::TriD::verbose. Add a section "Generating a Stack Trace" taken from GitHub issue #393. Add some more mappings to the package->source file table. * Basic/PDL.pm: Link to the Developer Guide under LANGUAGE DOCUMENTATION. * Basic/Pod/FAQ.pod: Link to the Developer Guide in Q: 3.5. * Basic/Pod/QuickStart.pod: Link to the Developer Guide. Also remove a phrase "until recently" which was recent ... in 1998, and don't mention HTML copies of the documentation which are no longer generated (and https://perldoc.perl.org exists). Changes according to mohawk2's review: * Mention $PDL::verbose and PDL::debug. * Adapt the section to organize commit to current best practice "one commit per small, meaningfil change" * Delete modules outside the repository from the module->file table * Add a line describing pdldoc --- Basic/PDL.pm | 5 + Basic/Pod/DeveloperGuide.pod | 179 +++++++++++++++-------------------- Basic/Pod/FAQ.pod | 6 +- Basic/Pod/QuickStart.pod | 21 ++-- 4 files changed, 95 insertions(+), 116 deletions(-) diff --git a/Basic/PDL.pm b/Basic/PDL.pm index 6555820a2..9ea76d366 100644 --- a/Basic/PDL.pm +++ b/Basic/PDL.pm @@ -84,6 +84,11 @@ course that takes you from a complete beginner level to expert. List of all available documentation, sorted alphabetically. If you cannot find what you are looking for, try here. +=item L + +A guide for people who want to contribute to PDL. Contributions are +very welcome! + =back =head1 DATA TYPES diff --git a/Basic/Pod/DeveloperGuide.pod b/Basic/Pod/DeveloperGuide.pod index 36f0e96df..1ff6eed8b 100644 --- a/Basic/Pod/DeveloperGuide.pod +++ b/Basic/Pod/DeveloperGuide.pod @@ -57,117 +57,88 @@ This is detailed in section 4.11 of L. =head1 PDL Developer Notes -=head2 Random Musings +=head2 Getting (some) Debug Information -A (small) collection of random musings to note if you feel -the need to improve or add to PDL (please do): +PDL has some global variables which control diagnostic output: =over -=item Organizing Commits +=item C<$::PP_VERBOSE> -git supports file-by-file commits so it is helpful -to commit your changes to git a little at a time where -each commit corresponds to a single change. This makes -it easy in the log to determine what was done and to -locate any desired commit in case of issues that need -to be resolved. +If set to a true value, L will print details while building +the module processing C declarations. -=item Access to PDL's configuration +=item C<$PDL::Graphics::TriD::verbose> -If you need to access the configuration for PDL then use the -C<%PDL::Config> variable. Prior to 2.4.1 this was a mess since -you had to use %PDL_CONFIG within Makefile.PL and PDL::Config -from *.pm/tests. The build process has been changed (I hesitate -to say "cleaned up" ;) to just use %PDL::Config consistently -throughout. +If set to a true value, the routines in L will +report their progress. -=back +=item C<$PDL::verbose> -=head2 Ingesting an external PDL module +Several modules produce diagnostic output to STDOUT if +C<$PDL::verbose> has a true value. -Notes on transferring an external PDL module to the PDL -source tree for distribution with PDL: +=item C<$PDL::debug> -Suppose you have developed a PDL module that resides in a -standalone source tree. You typically will need to have PDL -installed on your system before you can build this module. +Several modules produce diagnostic output if C<$PDL::verbose> has a +true value. -If you wish to migrate the module into the PDL distribution -you will need to make certain changes to the module source -in order to built in the PDL distribution. You will need to -removed dependecies on a pre-existing PDL installation for -configuration and build of your module. This is because as -part of the PDL distribution, it is possible that PDL has -never been installed. Build processes based on PDL will then -fail. +=back -Following is some specific advice that can help you do this. -Changes that must be made to files in your module source tree -if you are building the module from a .pd file : +=head2 Generating a Stack Trace -B +To generate a stack-trace to help us debug a problem, please first of +all do C, ensure you have the latest released PDL. +Then, if it is still happening, please follow this process: =over -=item * +=item Rerun perl Makefile.PL -You must remove the line 'use PDL::Core::Dev;'. +This will update the timestamps on Makefiles, prompting a full rebuild. -=item * +=item Edit your generated top-level Makefile -The line 'PDL::Core::Dev->import();' must be present +Add C<-g> to the C line to generate debug symbols (this gets +propagated to subdirectories) -=item * +=item Run: C -You must change the call from C to a call to -C (with the same arguments.) +This builds PDL into the C directory. -=item * +=item Run: C -It seems that most modules in the PDL source use +In gdb, run: C - VERSION_FROM => '../../Basic/PDL.pm', +=item Copy-paste the backtrace output -but not all of them in order that their version tracks -the PDL release version. It is possible to maintain -separate versioning even within the PDL source tree but -it may make things confusing. +This should show where the segfault originated. =back -Make certain that you make these changes to each 'Makefile.PL' in -your source tree. - - -B - -=over - -=item * - -Edit the 'Makefile.PL' in the directory above your module source -to add your module directory name to -C [ qw/Module1 AnotherModule / ]>. +Then please open an issue on whichever repo is relevant with your +C output and PDL version, together with the stack-trace +created above. When you do paste such output into a GitHub issue, +please surround such blocks with ``` on their own lines. You can check +out how it will render with the "Preview" button above the +issue-editing box. -=item * -Add your test files (.t files) to the PDL/t directory renaming if -required to avoid namespace conflicts. +=head2 Random Musings -=item * +A (small) collection of random musings to note if you feel +the need to improve or add to PDL (please do): -Does your module depend on any libraries or external -programs ? If so, doocument the required programs with version -numbers in PDL/DEPENDENCIES and add the PREREQ_* option to the -main Makefile.PL if required. +=over -=item * +=item Organizing Commits -If your module requires external libraries or header files, -add a section to perldl.conf. The hash values with be available -in your module's 'Makefile.PL' as $PDL::Config{WITH_MYMODULE},... +The preferred way to organize commits is one commit per small, +meaningful change (ideally each with an update to the corresponding +tests). This makes it easy in the log to determine what was done and +to locate any desired commit in case of issues that need to be +resolved. =back @@ -178,34 +149,34 @@ a PDL installation. For some modules the .pm files are generated via PDL::PP, so changes would need to go into their .pd sources. Here's a table mapping PDL package names to their origin: - | Package | Source file | - |------------------------+---------------------------------| - | PDL | Basic/PDL.pm | - | PDL::Bad | Basic/Bad/bad.pd | - | PDL::Basic | Basic/Core/Basic.pm | - | PDL::Core | Basic/Core/Core.pm | - | PDL::Demos | Demos/Demos.pm | - | PDL::Graphics::Gnuplot | *not* in this repository | - | PDL::Graphics::PGPLOT | *not* in this repository | - | PDL::Graphics::PLplot | *not* in this repository | - | PDL::Graphics::Prima | *not* in this repository | - | PDL::Graphics::Simple | *not* in this repository | - | PDL::Graphics::TriD | Graphics/TriD/TriD.pm | - | PDL::Graphics::TriD::* | Graphics/TriD/Objects.pm | - | PDL::IO::FITS | IO/FITS/FITS.pm | - | PDL::IO::Misc | IO/Misc/misc.pd | - | PDL::IO::Pic | IO/Pnm/pnm.pd | - | PDL::IO::Storable | IO/Storable/storable.pd | - | PDL::Lvalue | Basic/Lvalue.pm | - | PDL::Math | Basic/Math/math.pd | - | PDL::MatrixOps | Basic/MatrixOps/matrixops.pd | - | PDL::NiceSlice | Basic/SourceFilter/NiceSlice.pm | - | PDL::Ops | Basic/Ops/ops.pd | - | PDL::Primitive | Basic/Primitive/primitive.pd | - | PDL::Slices | Basic/Slices/slices.pd | - | PDL::Ufunc | Basic/Ufunc/ufunc.pd | - - + | Package | Source file | + |----------------------------------------+---------------------------------| + | PDL | Basic/PDL.pm | + | PDL::Bad | Basic/Bad/bad.pd | + | PDL::Basic | Basic/Core/Basic.pm | + | PDL::Core | Basic/Core/Core.pm | + | PDL::Demos | Demos/Demos.pm | + | PDL::Graphics::TriD | Graphics/TriD/TriD.pm | + | PDL::Graphics::TriD::* | Graphics/TriD/Objects.pm | + | PDL::Graphics::TriD::BoundingBox | Graphics/TriD/TriD.pm | + | PDL::Graphics::TriD::Material | Graphics/TriD/TriD.pm | + | PDL::Graphics::TriD::OneTransformation | Graphics/TriD/TriD.pm | + | PDL::Graphics::TriD::QuaterController | Graphics/TriD/TriD/ArcBall.pm | + | PDL::Graphics::TriD::Scale | Graphics/TriD/TriD.pm | + | PDL::Graphics::TriD::Transformation | Graphics/TriD/TriD.pm | + | PDL::Graphics::TriD::Translation | Graphics/TriD/TriD.pm | + | PDL::IO::FITS | IO/FITS/FITS.pm | + | PDL::IO::Misc | IO/Misc/misc.pd | + | PDL::IO::Pic | IO/Pnm/pnm.pd | + | PDL::IO::Storable | IO/Storable/storable.pd | + | PDL::Lvalue | Basic/Lvalue.pm | + | PDL::Math | Basic/Math/math.pd | + | PDL::MatrixOps | Basic/MatrixOps/matrixops.pd | + | PDL::NiceSlice | Basic/SourceFilter/NiceSlice.pm | + | PDL::Ops | Basic/Ops/ops.pd | + | PDL::Primitive | Basic/Primitive/primitive.pd | + | PDL::Slices | Basic/Slices/slices.pd | + | PDL::Ufunc | Basic/Ufunc/ufunc.pd | =head1 References @@ -245,4 +216,4 @@ L =back -=back \ No newline at end of file +=back diff --git a/Basic/Pod/FAQ.pod b/Basic/Pod/FAQ.pod index a7fd49698..640a6de9e 100644 --- a/Basic/Pod/FAQ.pod +++ b/Basic/Pod/FAQ.pod @@ -437,8 +437,10 @@ If you have a certain project in mind you should check if somebody else is already working on it or if you could benefit from existing modules. Do so by posting your planned project to the PDL developers mailing list at pdl-devel@lists.sourceforge.net . See the subscription -instructions in L. -We are always looking for people to write code and/or documentation ;). +instructions in L. We are always looking for people to write +code and/or documentation. The L +should get you started. =head2 Q: 3.6 I think I have found a bug in the current version of PDL. What shall I do? diff --git a/Basic/Pod/QuickStart.pod b/Basic/Pod/QuickStart.pod index 743be047d..d29f746d2 100644 --- a/Basic/Pod/QuickStart.pod +++ b/Basic/Pod/QuickStart.pod @@ -12,11 +12,11 @@ A brief summary of the main PDL features and how to use them. =head2 Introduction Perl is an extremely good and versatile scripting language, well suited to -beginners and allows rapid prototyping. However until recently it did not -support data structures which allowed it to do fast number crunching. +beginners and allows rapid prototyping. However the Perl core does not +support data structures which allow to do fast number crunching. -However with the development of Perl v5, Perl acquired 'Objects'. To put -it simply users can define their own special data types, and write +With the development of Perl v5, Perl acquired 'Objects'. To put +it simply, users can define their own special data types, and write custom routines to manipulate them either in low level languages (C and Fortran) or in Perl itself. @@ -41,17 +41,18 @@ data to be easily played with and visualised. =head2 Help -PDL contains extensive documentation, available both within the -I or I shells and from the command line, using the C program. +PDL contains extensive user documentation, available both within the +I or I shells and from the command line, using the +C program. C is the PDL equivalent of C. +You can also point a browser to L. + For further information try either of: pdl> help help $ pdldoc -HTML copies of the documentation should also be available. -To find their location, try the following: - - pdl> foreach ( map{"$_/PDL/HtmlDocs"}@INC ) { p "$_\n" if -d $_ } +If you want to delve into the internals of PDL, check out the +L. =head2 Perl Datatypes and how PDL extends them