1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
=head1 NAME
PDL::DeveloperGuide - How to develop for PDL
=head1 Public Git Repository
The PDL source distribution is hosted with L</Git> at the GitHub
site L<https://github.com/PDLPorters/pdl>, alongside with other PDL
related software.
This is the preferred place to submit bug reports or, even better,
pull requests.
=head1 PDL Developer Guidelines
The following guidelines are for any developer that has
access to the PDL Git repository.
=over
=item 1) Add new files to the inventory
Before committing a change with new files to the repository
you should update:
- MANIFEST (if files were added, using 'make manifest')
- MANIFEST.SKIP (if applicable)
=item 2) Add tests
Make sure you add a test case in the 't' directory for any
significant additional capability you add to PDL. Please
use L<Test::More> or one the of the Test modules available via
perl modules rather than doing-it-yourself!
=item 3) Add documentation
Please include POD documentation for any functions you add to
the distribution.
=item 4) Run the tests
Don't commit before you successfully built and passed
C<make test>.
=item 5) Watch for bug reports
Bugs should be reported to the GitHub issue tracker at
L<https://github.com/PDLPorters/pdl/issues>. See L<PDL::Bugs> for a
detailed description.
=item 6) PDL Developer Recommended Workflow
This is detailed in section 4.11 of L<PDL::FAQ>.
=back
=head1 PDL Developer Notes
=head2 Getting (some) Debug Information
PDL has some global variables which control diagnostic output:
=over
=item C<$::PP_VERBOSE>
If set to a true value, L<PDL::PP> will print details while building
the module processing C<pp_def> declarations.
=item C<$PDL::Graphics::TriD::verbose>
If set to a true value, the routines in L<PDL::Graphics::TriD> will
report their progress.
=item C<$PDL::verbose>
Several modules produce diagnostic output to STDOUT if
C<$PDL::verbose> has a true value.
=item C<$PDL::debug>
Several modules produce diagnostic output if C<$PDL::verbose> has a
true value.
=back
=head2 Generating a Stack Trace
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 Rerun perl Makefile.PL
This will update the timestamps on Makefiles, prompting a full rebuild.
=item Edit your generated top-level Makefile
Add C<-g> to the C<OPTIMIZE => line to generate debug symbols (this gets
propagated to subdirectories)
=item Run: C<make>
This builds PDL into the C<blib> directory.
=item Run: C<gdb perl -ex 'run -Mblib t/tracking.t'>
In gdb, run: C<bt>
=item Copy-paste the backtrace output
This should show where the segfault originated.
=back
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.
=head2 Random Musings
A (small) collection of random musings to note if you feel
the need to improve or add to PDL (please do):
=over
=item Organizing Commits
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
=head2 Finding the Source
As of 2.096, the directory layout in the repository is largely the
same as in a PDL installation, especially in L<PDL::Basic>.
Where the .pm files are generated via PDL::PP, changes would need
to go into their .pd sources. Use C<git grep Package::Name> to find
them.
=head1 References
=over
=item Official Website
For the audience of PDL users there is a dedicated website in the
perl.org domain: L<https://pdl.perl.org/>.
=item The current PDL version on MetaCPAN
L<https://metacpan.org/dist/PDL>
=item A guide to PDL's module references for PDL users
L<PDL::Modules>
=item The comprehensive modules index (autogenerated)
L<PDL::Index>
=item Git
The main Git home page is at L<http://www.git-scm.org/>.
Two good online Git references are:
=over
=item the Git User's Manual at
L<http://www.kernel.org/pub/software/scm/git/docs/user-manual.html>
=item and Git Magic at
L<http://www-cs-students.stanford.edu/~blynn/gitmagic/>
=back
=back
|
