1Padre::Manual::Hacking(U3s)er Contributed Perl DocumentatPiaodnre::Manual::Hacking(3)
2
6 Padre::Manual::Hacking - Guide to hacking on Padre
7
9 This is the Padre Developers Guide.
10 It is intended for people interested in hacking on Padre, and
12 specifically hacking the core distribution.
13 Getting Started
15 This document assumes that you are working from a copy of Padre checked
16 out from the official repository.
17 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 The specific path you want to check out is...
24 http://svn.perlide.org/padre/trunk
26 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 In addition, there are some additional scripts that are for development
32 purposes and are not part of the releases themselves.
33 Padre/dev.pl
35 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 tools/release.pl
42 Used to release Padre.
44 tools/update_version_number.pl
46 Similar to the ppi_version tool from CPAN, this updates the version
48 number.
49 Bug Tracking
51 Padre uses Trac for bug tracking.
52 The main web site of Padre is actually its Trac
54 <http://padre.perlide.org/>
55 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 Please send patches either to the padre-dev mailing list or add them to
62 trac to the appropriate ticket.
63 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 So please don't intentionally break the trunk!
71 If you think your change is relatively large and you feel more
73 comfortable working on a branch, do it.
74 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 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 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 Tickets/Issues/Bugs
91 We are using Trac as the issue and bug tracker.
92 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 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 You are also encouraged to do so!
102
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 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 In general, the code style preferences for Padre are guided by ease of
114 understanding code, and thus ease of maintenance.
115 Tabs instead of Spaces
117 Use one tab character for each indentation level at the beginning of a
118 line.
119 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 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 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 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 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 Example: (Where you put the opening brace isn't
144 important for this example!)
145 sub baz {
147 if (foo()
148 and bar())
149 {
150 # ...
151 }
152 }
153 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 Methods in all capitals are reserved for Perl-specific methods such as
160 "DESTROY"
161 Methods in StudlyCaps are reserved for the Wx bindings.
163 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 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 my $object = Class->new(
172 value => 'something',
173 );
174 sub value {
176 $_[0]->{value};
177 }
178 Accessors which can change post-constructor should be named "get_foo"
180 and "set_foo". Do not use mutators.
181 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
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 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 Here's a rough how-to for Linux and similar OSs:
200 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.10.0 is the latest stable release.
204 · Extract the sources and run
206 ./Configure -Dprefix='/path/for/your/perl' -DDEBUGGING -Dusethreads -Duse64bitall -Dusedevel -DDEBUG_LEAKING_SCALARS -DPERL_USE_SAFE_PUTENV
208 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 -DDEBUG_LEAKING_SCALARS -DPERL_USE_SAFE_PUTENV
215 Afterwards, keep hitting return until the configuration is done.
217 · Compile "perl" by typing "make" or for multiple CPUs, type "make -jX"
219 where X is the number of CPUs+1.
220 · If all went well, type "make install" to install your own private
222 debugging perl.
223 · 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 perl -e 'for(@ARGV){$n=$_;s/5\.\d+\.\d+//; system("ln -s $n $_")}' *5.*
229 Check that there's now also a perl symlink to perl5.10.0 (or whatever
231 version of perl you built).
232 · Setup the environment of your shell to use the new perl. For bash-
234 like shells, do this:
235 export PATH=/path/to/your/perl/bin:$PATH
237 csh like shells probably use something like "setenv" or so.
239 · Try running "perl -V" to see whether your new perl is being run.
241 (See also: "which perl")
242 Make sure "perl -V" shows these particular "compile-time options":
244 DEBUGGING DEBUG_LEAKING_SCALARS PERL_USE_SAFE_PUTENV
246 PERL_USE_DEVEL
247 There'll certainly be others, too.
249 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 · Run cpan. (NOT as root!)
255 · 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 · From cpan, type "look Alien::wxWidgets". You should get a new shell
261 in an extracted "Alien::wxWidgets" distribution.
262 · Build wxWidgets by running:
264 perl Build.PL --debug --unicode
266 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 "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 ./Build
275 ./Build test
276 ./Build install
277 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 cpan> look Wx
283 ...
284 $ perl Makefile.PL
285 ... blah blah missing this or that ...
286 Take note of the missing dependencies, exit to the CPAN shell,
288 install the missing modules, then "look Wx" again.
289 · If you have all Wx.pm dependencies in place, build "Wx" like this:
291 perl Makefile.PL --wx-debug --wx-unicode
293 make
294 make test
295 make install
296 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 · Run "cpan ." to automatically install all dependencies of Padre!
302 · Run the following to set up Padre:
304 perl Makefile.PL
306 make
307 · Run dev.pl to start Padre from your checkout.
309 perl dev.pl
311 or with all plugins loaded:
313 perl dev.pl -h
315 or with the Perl debugger:
317 perl dev.pl -d
319 · 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
327 For support with Padre itself, see the support section in the top level
328 Padre class.
329 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.
335perl v5.12.1 2010-03-31 Padre::Manual::Hacking(3)