1Padre::Manual::Hacking(U3s)er Contributed Perl DocumentatPiaodnre::Manual::Hacking(3)
2
3
4

NAME

6       Padre::Manual::Hacking - Guide to hacking on Padre
7

DESCRIPTION

9       This is the Padre Developers Guide.
10
11       It is intended for people interested in hacking on Padre, and
12       specifically hacking the core distribution.
13
14   Getting Started
15       This document assumes that you are working from a copy of Padre checked
16       out from the official repository.
17
18       Rather than just checking out the Padre distribution alone, we
19       recommend that you checkout the entire repository trunk, which will
20       provide you with Padre itself, miscellaneous tool scripts, and most of
21       the plugin distributions as well.
22
23       The specific path you want to check out is...
24
25         http://svn.perlide.org/padre/trunk
26
27   Extra Files
28       The trunk contains primarily a set of directories, one for each CPAN
29       distribution created for Padre by the development team.
30
31       In addition, there are some additional scripts that are for development
32       purposes and are not part of the releases themselves.
33
34       Padre/dev
35
36       This is a launch script used to start Padre in developer mode. This
37       mainly automates a couple of conveniences, such as using a local .padre
38       directory instead of your system one, and including lib in the @INC
39       path to prevent needing to run make constantly.
40
41       tools/release.pl
42
43       Used to release Padre.
44
45       tools/update_version_number.pl
46
47       Similar to the ppi_version tool from CPAN, this updates the version
48       number.
49
50   Bug Tracking
51       Padre uses Trac for bug tracking.
52
53       The main web site of Padre is actually its Trac
54       <http://padre.perlide.org/>
55
56   Patching
57       Check out the trunk (<http://svn.perlide.org/padre/trunk/>) and use svn
58       diff to create your patch while your current working directory is the
59       trunk directory.
60
61       Please send patches either to the padre-dev mailing list or add them to
62       trac to the appropriate ticket.
63
64   Branching
65       Usually we use the trunk for all the development work so we can see
66       issues and fix them quickly. At least some of us already use Padre for
67       the development work running it from the workspace so if someone breaks
68       trunk that will immediately affect some of the developers.
69
70       So please don't intentionally break the trunk!
71
72       If you think your change is relatively large and you feel more
73       comfortable working on a branch, do it.
74
75   Change Management
76       We try to work with small changes. There are no exact rules what is
77       small and what is already too big but we try not to mix unrelated
78       issues in one change. If you need a styling change or white space
79       change, do it it in a separate commit.
80
81       Commit messages are important. If a commit relates to a ticket please
82       try to remember adding the ticket number with a # sign ( #23 ). The GUI
83       of Trac will turn it into a link to the relevant ticket making it
84       easier to find related information.
85
86       Most of the current major committers monitor the commit messages to see
87       what everyone else is doing, so please write them as if they are going
88       to actually be read within a few hours of you making the commit.
89
90   Tickets/Issues/Bugs
91       We are using Trac as the issue and bug tracker.
92
93       When adding a note that relates to one of the commit in SVN please use
94       the r780 format. That allows Trac to create links to the diff of that
95       revision.
96
97   Code review
98       We don't have formal code-review but in response to the commit messages
99       we sometimes reply with comments to the padre-dev mailing list.
100
101       You are also encouraged to do so!
102

STYLE

104       We're not overly strict about code style in Padre (yet), but please
105       don't feel offended if somebody corrects your coding style.
106
107       There are a number of relatively simple preferences that are more or
108       less enforced, but none of this is automated. We prefer humans over
109       automation for this because PerlTidy has something of a history of
110       doing things overly strictly, which can sometimes destroy clarity for
111       the sake of correctness.
112
113       In general, the code style preferences for Padre are guided by ease of
114       understanding code, and thus ease of maintenance.
115
116   Tabs instead of Spaces
117       Use one tab character for each indentation level at the beginning of a
118       line.
119
120       There are a lot of people working on Padre, with indent preferences
121       ranging from two to eight spaces. Using tabs allows all of the
122       development team to work with code at the indent level that is most
123       comfortable for their eyes.
124
125       In particular, allowing the use of large (eight or higher) tabs enables
126       developers with visual processing or eye-sight issues (astygmatisms,
127       mild short-sightedness, figure-ground problems) to effectively
128       contribute to Padre.
129
130       If your editor doesn't support tabs properly, well that's clearly a
131       temporary probably because you will eventually be switching to Padre,
132       which DOES support tabs properly.
133
134       Additionally, there current plan for project support does include
135       correctly supporting project specific tab-versus-space settings, so you
136       can use spaces for your code, and Padre will just switch and Do The
137       Right Thing when you work on the Padre project.
138
139       After the initial indentation, do not use tabs for indentation any
140       more.  Instead, use the appropriate amount of spaces to make  things
141       line up.
142
143       Example: (Where you put the opening brace isn't
144                 important for this example!)
145
146         sub baz {
147                 if (foo()
148                     and bar())
149                 {
150                         # ...
151                 }
152         }
153
154   Method and Subroutine Naming
155       Methods in Padre itself must be lowercase, and should generally consist
156       of complete words separated by underscores.  (e.g. Use ->check_message
157       instead of ->chkMsg).
158
159       Methods in all capitals are reserved for Perl-specific methods such as
160       "DESTROY"
161
162       Methods in StudlyCaps are reserved for the Wx bindings.
163
164       Separating This allows us to be clear which methods (or overrided
165       methods) are part of the Wx layer, and which are part of Padre itself.
166
167   Accessors
168       If a value is set once during the constructor and then not changed
169       afterward, use a accessor name which matches the original parameter.
170
171         my $object = Class->new(
172             value => 'something',
173         );
174
175         sub value {
176             $_[0]->{value};
177         }
178
179       Accessors which can change post-constructor should be named "get_foo"
180       and "set_foo". Do not use mutators.
181
182       For simple accessors, we encourage the use of Class::XSAccessor for
183       accessor generation. This not only makes them significantly faster, but
184       also makes debugging easier, because the debugger won't descend into
185       every single accessor sub.
186

HEAVY-DUTY DEBUGGING

188       Don't bother reading this sectionif you don't know any C or if you just
189       want to get started hacking Padre!
190
191       If you're planning to do a serious debugging session, you may want to
192       set up Padre with a debugging perl and debugging version of Wx.
193       Particularly the core developers are encouraged to have a go at this
194       because the debugging version of wxWidgets will show various warnings
195       of failed assertions which may otherwise go undetected. This is a bit
196       of work to set up and not very useful for a casual hacker as this will
197       involve compiling your own perl, wxWidgets, and Wx.
198
199       Here's a rough how-to for Linux and similar OSs:
200
201   Building your own debugging perl
202       · Get the perl sources from http://cpan.org/src/README.html or via git.
203         As of this writing, perl 5.12.1 is the latest stable release.
204
205       · Extract the sources and run
206
207           ./Configure -Dprefix='/path/for/your/perl' -DDEBUGGING -Dusethreads -Duse64bitall -Dusedevel -DDEBUG_LEAKING_SCALARS -DPERL_USE_SAFE_PUTENV
208
209         Remove the "-Duse64bitall" if you have a 32bit OS (or machine). Keep
210         answering the questions with default (hit Enter) except for the
211         question about additional cc flags. Here, put the default settings
212         that are suggested in the [...] brackets and add two options:
213
214           -DDEBUG_LEAKING_SCALARS -DPERL_USE_SAFE_PUTENV
215
216         Afterwards, keep hitting return until the configuration is done.
217
218       · Compile "perl" by typing "make" or for multiple CPUs, type "make -jX"
219         where X is the number of CPUs+1.
220
221       · If all went well, type "make install" to install your own private
222         debugging perl.
223
224       · Check whether the executables in /path/to/your/perl/bin all contain
225         the version numbers of perl. You may want to create symlinks of the
226         basename.  If so, cd to the directory and run:
227
228           perl -e 'for(@ARGV){$n=$_;s/5\.\d+\.\d+//; system("ln -s $n $_")}' *5.*
229
230         Check that there's now also a perl symlink to perl5.12.1 (or whatever
231         version of perl you built).
232
233       · Setup the environment of your shell to use the new perl. For bash-
234         like shells, do this:
235
236           export PATH=/path/to/your/perl/bin:$PATH
237
238         csh like shells probably use something like "setenv" or so.
239
240       · Try running "perl -V" to see whether your new perl is being run.
241         (See also: "which perl")
242
243         Make sure "perl -V" shows these particular "compile-time options":
244
245           DEBUGGING DEBUG_LEAKING_SCALARS PERL_USE_SAFE_PUTENV
246           PERL_USE_DEVEL
247
248         There'll certainly be others, too.
249
250   Building your own debugging wxWidgets
251       · Make sure your ~/.cpan is owned by you and not being used by another
252         perl. Maybe clean up ~/.cpan/build/* so there's no collisions.
253
254       · Run cpan. (NOT as root!)
255
256       · If you like, install "Bundle::CPAN" for convenience. Potentially
257         restart cpan afterwards. Check whether the modules were installed
258         into your fresh perl at /path/to/your/perl/lib.....
259
260       · From cpan, type "look Alien::wxWidgets". You should get a new shell
261         in an extracted "Alien::wxWidgets" distribution.
262
263       · Build wxWidgets by running:
264
265           perl Build.PL --debug --unicode
266
267         Hopefully, it won't say you're missing any dependencies. If you're
268         missing any, quit the shell and install them from the cpan shell
269         before continuing.
270
271         "Build.PL" will ask you whether you want to build from sources. Yes,
272         you do.  Have it fetch the sources as .tar.gz.
273
274           ./Build
275           ./Build test
276           ./Build install
277
278   Installing a debugging Wx.pm
279       · Now, you want to set up your own Wx.pm with debugging enabled.
280         First, install the prerequisites for Wx. I did it like this:
281
282           cpan> look Wx
283           ...
284           $ perl Makefile.PL
285           ... blah blah missing this or that ...
286
287         Take note of the missing dependencies, exit to the CPAN shell,
288         install the missing modules, then "look Wx" again.
289
290       · If you have all Wx.pm dependencies in place, build "Wx" like this:
291
292           perl Makefile.PL --wx-debug --wx-unicode
293           make
294           make test
295           make install
296
297   Installing Padre from SVN
298       · Once Wx.pm is installed, check out Padre from the Subversion
299         repository and cd to its directory under trunk/Padre.
300
301       · Run "cpan ." to automatically install all dependencies of Padre!
302
303       · Run the following to set up Padre:
304
305           perl Makefile.PL
306           make
307
308       · Run dev to start Padre from your checkout.
309
310           perl dev
311
312         or with all plugins loaded:
313
314           perl dev -h
315
316         or with the Perl debugger:
317
318           perl dev -d
319
320       · Don't be annoyed by the Wx popups complaining about assertion-
321         failures. They indicate potential bugs that probably need attention.
322         If you get these, that means it was worth the effort to build a
323         debugging perl and Wx! Note that the stack backtraces given are at
324         the C level, not Perl backtraces.
325

SUPPORT

327       For support with Padre itself, see the support section in the top level
328       Padre class.
329
330       For support on hacking Padre, the best place to go is the #padre
331       channel on <irc://irc.perl.org/>.
332
334       Copyright 2008-2010 The Padre Team.
335
336
337
338perl v5.30.1                      2020-01-30         Padre::Manual::Hacking(3)
Impressum