.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Padre::Manual::Hacking 3pm"
.TH Padre::Manual::Hacking 3pm "2014-09-11" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Padre::Manual::Hacking \- Guide to hacking on Padre
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the Padre Developers Guide.
.PP
It is intended for people interested in hacking on Padre, and specifically 
hacking the core distribution.
.SS "Getting Started"
.IX Subsection "Getting Started"
This document assumes that you are working from a copy of Padre checked
out from the official repository.
.PP
Rather than just checking out the Padre distribution alone, we recommend
that you checkout the entire repository trunk, which will provide you
with Padre itself, miscellaneous tool scripts, and most of the plugin
distributions as well.
.PP
The specific path you want to check out is...
.PP
.Vb 1
\&  http://svn.perlide.org/padre/trunk
.Ve
.SS "Extra Files"
.IX Subsection "Extra Files"
The trunk contains primarily a set of directories, one for each \s-1CPAN\s0
distribution created for Padre by the development team.
.PP
In addition, there are some additional scripts that are for development
purposes and are not part of the releases themselves.
.PP
\&\fIPadre/dev\fR
.PP
This is a launch script used to start Padre in developer mode. This mainly
automates a couple of conveniences, such as using a local .padre directory
instead of your system one, and including lib in the \f(CW@INC\fR path to prevent
needing to run make constantly.
.PP
\&\fItools/release.pl\fR
.PP
Used to release Padre.
.PP
\&\fItools/update_version_number.pl\fR
.PP
Similar to the \fBppi_version\fR tool from \s-1CPAN,\s0 this updates the version number.
.SS "Bug Tracking"
.IX Subsection "Bug Tracking"
Padre uses Trac for bug tracking.
.PP
The main web site of Padre is actually its Trac <http://padre.perlide.org/>
.SS "Patching"
.IX Subsection "Patching"
Check out the trunk (<http://svn.perlide.org/padre/trunk/>) and use svn
diff to create your patch while your current working directory is the
trunk directory.
.PP
Please send patches either to the padre-dev mailing list or add them to
trac to the appropriate ticket.
.SS "Branching"
.IX Subsection "Branching"
Usually we use the trunk for all the development work so we can see issues
and fix them quickly. At least some of us already use Padre for the
development work running it from the workspace so if someone breaks trunk
that will immediately affect some of the developers.
.PP
So please don't \fBintentionally\fR break the trunk!
.PP
If you think your change is relatively large and you feel more comfortable
working on a branch, do it.
.SS "Change Management"
.IX Subsection "Change Management"
We try to work with small changes. There are no exact rules what is small
and what is already too big but we try not to mix unrelated issues in one
change. If you need a styling change or white space change, do it it in a
separate commit.
.PP
Commit messages are important. If a commit relates to a ticket please try
to remember adding the ticket number with a # sign ( #23 ). The \s-1GUI\s0 of
Trac will turn it into a link to the relevant ticket making it easier to
find related information.
.PP
Most of the current major committers monitor the commit messages to see
what everyone else is doing, so please write them as if they are going to
actually be read within a few hours of you making the commit.
.SS "Tickets/Issues/Bugs"
.IX Subsection "Tickets/Issues/Bugs"
We are using Trac as the issue and bug tracker.
.PP
When adding a note that relates to one of the commit in \s-1SVN\s0 please use the
r780 format. That allows Trac to create links to the diff of that revision.
.SS "Code review"
.IX Subsection "Code review"
We don't have formal code-review but in response to the commit messages
we sometimes reply with comments to the padre-dev mailing list.
.PP
You are also encouraged to do so!
.SH "STYLE"
.IX Header "STYLE"
We're not overly strict about code style in Padre (yet), but please don't
feel offended if somebody corrects your coding style.
.PP
There are a number of relatively simple preferences that are more or less
enforced, but none of this is automated. We prefer humans over automation
for this because PerlTidy has something of a history of doing things overly
strictly, which can sometimes destroy clarity for the sake of
correctness.
.PP
In general, the code style preferences for Padre are guided by ease of
understanding code, and thus ease of maintenance.
.SS "\fBTabs instead of Spaces\fP"
.IX Subsection "Tabs instead of Spaces"
Use one tab character for each indentation level at the beginning of a line.
.PP
There are a lot of people working on Padre, with indent preferences
ranging from two to eight spaces. Using tabs allows all of the development
team to work with code at the indent level that is most comfortable for
their eyes.
.PP
In particular, allowing the use of large (eight or higher) tabs enables
developers with visual processing or eye-sight issues (astygmatisms, mild
short-sightedness, figure-ground problems) to effectively contribute to
Padre.
.PP
If your editor doesn't support tabs properly, well that's clearly a
temporary probably because you will eventually be switching to Padre,
which \s-1DOES\s0 support tabs properly.
.PP
Additionally, there current plan for project support does include correctly
supporting project specific tab-versus-space settings, so you can use
spaces for \fByour\fR code, and Padre will just switch and Do The Right Thing
when you work on the Padre project.
.PP
After the initial indentation, do not use tabs for indentation any more.
Instead, use the appropriate amount of spaces to make  things line up.
.PP
Example: (Where you put the opening brace isn't
          important for this example!)
.PP
.Vb 7
\&  sub baz {
\&          if (foo()
\&              and bar())
\&          {
\&                  # ...
\&          }
\&  }
.Ve
.SS "Method and Subroutine Naming"
.IX Subsection "Method and Subroutine Naming"
Methods in Padre itself must be lowercase, and should generally consist of
complete words separated by underscores.
(e.g. Use \->check_message instead of \->chkMsg).
.PP
Methods in all capitals are reserved for Perl-specific methods such as
\&\f(CW\*(C`DESTROY\*(C'\fR
.PP
Methods in StudlyCaps are reserved for the Wx bindings.
.PP
Separating This allows us to
be clear which methods (or overrided methods) are part of the Wx layer,
and which are part of Padre itself.
.SS "Accessors"
.IX Subsection "Accessors"
If a value is set once during the constructor and then not changed
afterward, use a accessor name which matches the original parameter.
.PP
.Vb 3
\&  my $object = Class\->new(
\&      value => \*(Aqsomething\*(Aq,
\&  );
\&  
\&  sub value {
\&      $_[0]\->{value};
\&  }
.Ve
.PP
Accessors which can change post-constructor should be named \*(L"get_foo\*(R"
and \*(L"set_foo\*(R". Do not use mutators.
.PP
For simple accessors, we encourage the use of Class::XSAccessor for
accessor generation. This not only makes them significantly faster,
but also makes debugging easier, because the debugger won't descend into
every single accessor sub.
.SH "HEAVY-DUTY DEBUGGING"
.IX Header "HEAVY-DUTY DEBUGGING"
\&\fIDon't bother reading this sectionif you don't know any C or if you
just want to get started hacking Padre!\fR
.PP
If you're planning to do a serious debugging session, you may want to set
up Padre with a debugging perl and debugging version of Wx.
Particularly the core developers are encouraged to have a go at this
because the debugging version of wxWidgets will show various warnings
of failed assertions which may otherwise go undetected. This is a bit of
work to set up and not very useful for a casual hacker as this will
involve compiling your own perl, wxWidgets, and Wx.
.PP
Here's a rough how-to for Linux and similar OSs:
.SS "Building your own debugging perl"
.IX Subsection "Building your own debugging perl"
.IP "\(bu" 2
Get the perl sources from http://cpan.org/src/README.html or via git.
As of this writing, perl 5.12.1 is the latest stable release.
.IP "\(bu" 2
Extract the sources and run
.Sp
.Vb 1
\&  ./Configure \-Dprefix=\*(Aq/path/for/your/perl\*(Aq \-DDEBUGGING \-Dusethreads \-Duse64bitall \-Dusedevel \-DDEBUG_LEAKING_SCALARS \-DPERL_USE_SAFE_PUTENV
.Ve
.Sp
Remove the \f(CW\*(C`\-Duse64bitall\*(C'\fR if you have a 32bit \s-1OS \s0(or machine). Keep
answering the questions with default (hit Enter) except for the question
about \fBadditional cc flags\fR. Here, put the default settings that are suggested
in the \fI[...]\fR brackets and add two options:
.Sp
.Vb 1
\&  \-DDEBUG_LEAKING_SCALARS \-DPERL_USE_SAFE_PUTENV
.Ve
.Sp
Afterwards, keep hitting return until the configuration is done.
.IP "\(bu" 2
Compile \f(CW\*(C`perl\*(C'\fR by typing \f(CW\*(C`make\*(C'\fR or for multiple CPUs, type \f(CW\*(C`make \-jX\*(C'\fR
where X is the number of CPUs+1.
.IP "\(bu" 2
If all went well, type \f(CW\*(C`make install\*(C'\fR to install your own private debugging perl.
.IP "\(bu" 2
Check whether the executables in \fI/path/to/your/perl/bin\fR all contain
the version numbers of perl. You may want to create symlinks of the basename.
If so, cd to the directory and run:
.Sp
.Vb 1
\&  perl \-e \*(Aqfor(@ARGV){$n=$_;s/5\e.\ed+\e.\ed+//; system("ln \-s $n $_")}\*(Aq *5.*
.Ve
.Sp
Check that there's now also a \fIperl\fR symlink to \fIperl5.12.1\fR (or whatever
version of perl you built).
.IP "\(bu" 2
Setup the environment of your shell to use the new perl. For bash-like
shells, do this:
.Sp
.Vb 1
\&  export PATH=/path/to/your/perl/bin:$PATH
.Ve
.Sp
csh like shells probably use something like \f(CW\*(C`setenv\*(C'\fR or so.
.IP "\(bu" 2
Try running \f(CW\*(C`perl \-V\*(C'\fR to see whether your new perl is being run.
(See also: \f(CW\*(C`which perl\*(C'\fR)
.Sp
Make sure \f(CW\*(C`perl \-V\*(C'\fR shows these particular \*(L"compile-time options\*(R":
.Sp
.Vb 2
\&  DEBUGGING DEBUG_LEAKING_SCALARS PERL_USE_SAFE_PUTENV
\&  PERL_USE_DEVEL
.Ve
.Sp
There'll certainly be others, too.
.SS "Building your own debugging wxWidgets"
.IX Subsection "Building your own debugging wxWidgets"
.IP "\(bu" 2
Make sure your \fI~/.cpan\fR is owned by you and not being used by another
perl. Maybe clean up \fI~/.cpan/build/*\fR so there's no collisions.
.IP "\(bu" 2
Run \fIcpan\fR. (\fB\s-1NOT\s0\fR as root!)
.IP "\(bu" 2
If you like, install \f(CW\*(C`Bundle::CPAN\*(C'\fR for convenience. Potentially
restart \fIcpan\fR afterwards. Check whether the modules were installed
into your fresh perl at \fI/path/to/your/perl/lib....\fR.
.IP "\(bu" 2
From \fIcpan\fR, type \f(CW\*(C`look Alien::wxWidgets\*(C'\fR. You should get a new shell
in an extracted \f(CW\*(C`Alien::wxWidgets\*(C'\fR distribution.
.IP "\(bu" 2
Build wxWidgets by running:
.Sp
.Vb 1
\&  perl Build.PL \-\-debug \-\-unicode
.Ve
.Sp
Hopefully, it won't say you're missing any dependencies. If you're
missing any, quit the shell and install them from the cpan shell
before continuing.
.Sp
\&\f(CW\*(C`Build.PL\*(C'\fR will ask you whether you want to build from sources. Yes, you do.
Have it fetch the sources as \fI.tar.gz\fR.
.Sp
.Vb 3
\&  ./Build
\&  ./Build test
\&  ./Build install
.Ve
.SS "Installing a debugging Wx.pm"
.IX Subsection "Installing a debugging Wx.pm"
.IP "\(bu" 2
Now, you want to set up your own \fIWx.pm\fR with debugging enabled.
First, install the prerequisites for Wx. I did it like this:
.Sp
.Vb 4
\&  cpan> look Wx
\&  ...
\&  $ perl Makefile.PL
\&  ... blah blah missing this or that ...
.Ve
.Sp
Take note of the missing dependencies, exit to the \s-1CPAN\s0 shell, install
the missing modules, then \f(CW\*(C`look Wx\*(C'\fR again.
.IP "\(bu" 2
If you have all \fIWx.pm\fR dependencies in place, build \f(CW\*(C`Wx\*(C'\fR like this:
.Sp
.Vb 4
\&  perl Makefile.PL \-\-wx\-debug \-\-wx\-unicode
\&  make
\&  make test
\&  make install
.Ve
.SS "Installing Padre from \s-1SVN\s0"
.IX Subsection "Installing Padre from SVN"
.IP "\(bu" 2
Once \fIWx.pm\fR is installed, check out Padre from the Subversion
repository and cd to its directory under \fItrunk/Padre\fR.
.IP "\(bu" 2
Run \f(CW\*(C`cpan .\*(C'\fR to automatically install all dependencies of Padre!
.IP "\(bu" 2
Run the following to set up Padre:
.Sp
.Vb 2
\&  perl Makefile.PL
\&  make
.Ve
.IP "\(bu" 2
Run \fIdev\fR to start Padre from your checkout.
.Sp
.Vb 1
\&  perl dev
.Ve
.Sp
or with all plugins loaded:
.Sp
.Vb 1
\&  perl dev \-h
.Ve
.Sp
or with the Perl debugger:
.Sp
.Vb 1
\&  perl dev \-d
.Ve
.IP "\(bu" 2
Don't be annoyed by the Wx popups complaining about
assertion-failures. They indicate potential bugs that probably need
attention. If you get these, that means it was worth the effort to
build a debugging perl and Wx! Note that the stack backtraces given are
at the C level, not Perl backtraces.
.SH "SUPPORT"
.IX Header "SUPPORT"
For support with Padre itself, see the support section in the top
level Padre class.
.PP
For support on hacking Padre, the best place to go is the #padre
channel on <irc://irc.perl.org/>.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2010 The Padre Team.