Skip to content

Commit

Permalink
More stuff for the DeveloperGuide, as suggested in GitHub#481,
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@HaraldJoerg @mohawk2
HaraldJoerg authored and mohawk2 committed Aug 1, 2024
1 parent 4e4a7d7 commit b1d5e88
Show file tree
Hide file tree
Showing 4 changed files with 95 additions and 116 deletions.
5 changes: 5 additions & 0 deletions Basic/PDL.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<PDL::DeveloperGuide>
A guide for people who want to contribute to PDL. Contributions are
very welcome!
=back
=head1 DATA TYPES
Expand Down
179 changes: 75 additions & 104 deletions Basic/Pod/DeveloperGuide.pod
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,117 +57,88 @@ This is detailed in section 4.11 of L<PDL::FAQ>.

=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<PDL::PP> will print details while building
the module processing C<pp_def> 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<PDL::Graphics::TriD> 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<Makefile.PL:>
To generate a stack-trace to help us debug a problem, please first of
all do C<make realclean>, 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<OPTIMIZE => line to generate debug symbols (this gets
propagated to subdirectories)

=item *
=item Run: C<make>

You must change the call from C<pdlpp_postamble> to a call to
C<pdlpp_postamble_int> (with the same arguments.)
This builds PDL into the C<blib> directory.

=item *
=item Run: C<gdb perl -ex 'run -Mblib t/tracking.t'>

It seems that most modules in the PDL source use
In gdb, run: C<bt>

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<Changes to the existing PDL source tree:>

=over

=item *

Edit the 'Makefile.PL' in the directory above your module source
to add your module directory name to
C<DIR => [ qw/Module1 AnotherModule / ]>.
Then please open an issue on whichever repo is relevant with your
C<perl -V> 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

Expand All @@ -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

Expand Down Expand Up @@ -245,4 +216,4 @@ L<http://www-cs-students.stanford.edu/~blynn/gitmagic/>

=back

=back
=back
6 changes: 4 additions & 2 deletions Basic/Pod/FAQ.pod
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<Question 3.2|"Q: 3.2 Are there other PDL information sources on the Internet?">.
We are always looking for people to write code and/or documentation ;).
instructions in L<Question 3.2|"Q: 3.2 Are there other PDL information
sources on the Internet?">. We are always looking for people to write
code and/or documentation. The L<Developer Guide|PDL::DeveloperGuide>
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?
Expand Down
21 changes: 11 additions & 10 deletions Basic/Pod/QuickStart.pod
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -41,17 +41,18 @@ data to be easily played with and visualised.

=head2 Help

PDL contains extensive documentation, available both within the
I<perldl> or I<pdl2> shells and from the command line, using the C<pdldoc> program.
PDL contains extensive user documentation, available both within the
I<perldl> or I<pdl2> shells and from the command line, using the
C<pdldoc> program. C<pdldoc> is the PDL equivalent of C<perldoc -f>.
You can also point a browser to L<https://metacpan.org/pod/PDL>.

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<Developer Guide|PDL::DeveloperGuide>.

=head2 Perl Datatypes and how PDL extends them

Expand Down

0 comments on commit b1d5e88

Please sign in to comment.