NAME

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

DESCRIPTION

       This is the Padre Developers Guide.

       It is intended for people interested in hacking on Padre, and specifically hacking the core distribution.

   Getting Started
       This document assumes that you are working from a copy of Padre checked out from the official repository.

       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.

       The specific path you want to check out is...

         http://svn.perlide.org/padre/trunk

   Extra Files
       The trunk contains primarily a set of directories, one for each CPAN distribution created for Padre by
       the development team.

       In addition, there are some additional scripts that are for development purposes and are not part of the
       releases themselves.

       Padre/dev

       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
       @INC path to prevent needing to run make constantly.

       tools/release.pl

       Used to release Padre.

       tools/update_version_number.pl

       Similar to the ppi_version tool from CPAN, this updates the version number.

   Bug Tracking
       Padre uses Trac for bug tracking.

       The main web site of Padre is actually its Trac <http://padre.perlide.org/>

   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.

       Please send patches either to the padre-dev mailing list or add them to trac to the appropriate ticket.

   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.

       So please don't intentionally break the trunk!

       If you think your change is relatively large and you feel more comfortable working on a branch, do it.

   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.

       Commit messages are important. If a commit relates to a ticket please try to remember adding the ticket
       number with a # sign ( #23 ). The GUI of Trac will turn it into a link to the relevant ticket making it
       easier to find related information.

       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.

   Tickets/Issues/Bugs
       We are using Trac as the issue and bug tracker.

       When adding a note that relates to one of the commit in SVN please use the r780 format. That allows Trac
       to create links to the diff of that revision.

   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.

       You are also encouraged to do so!

STYLE

       We're not overly strict about code style in Padre (yet), but please don't feel offended if somebody
       corrects your coding style.

       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.

       In general, the code style preferences for Padre are guided by ease of understanding code, and thus ease
       of maintenance.

   Tabs instead of Spaces
       Use one tab character for each indentation level at the beginning of a line.

       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.

       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.

       If your editor doesn't support tabs properly, well that's clearly a temporary probably because you will
       eventually be switching to Padre, which DOES support tabs properly.

       Additionally, there current plan for project support does include correctly supporting project specific
       tab-versus-space settings, so you can use spaces for your code, and Padre will just switch and Do The
       Right Thing when you work on the Padre project.

       After the initial indentation, do not use tabs for indentation any more.  Instead, use the appropriate
       amount of spaces to make  things line up.

       Example: (Where you put the opening brace isn't
                 important for this example!)

         sub baz {
                 if (foo()
                     and bar())
                 {
                         # ...
                 }
         }

   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).

       Methods in all capitals are reserved for Perl-specific methods such as "DESTROY"

       Methods in StudlyCaps are reserved for the Wx bindings.

       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.

   Accessors
       If a value is set once during the constructor and then not changed afterward, use a accessor name which
       matches the original parameter.

         my $object = Class->new(
             value => 'something',
         );

         sub value {
             $_[0]->{value};
         }

       Accessors which can change post-constructor should be named "get_foo" and "set_foo". Do not use mutators.

       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.

HEAVY-DUTY DEBUGGING

       Don't bother reading this sectionif you don't know any C or if you just want to get started hacking
       Padre!

       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.

       Here's a rough how-to for Linux and similar OSs:

   Building your own debugging perl
       • 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.

       • Extract the sources and run

           ./Configure -Dprefix='/path/for/your/perl' -DDEBUGGING -Dusethreads -Duse64bitall -Dusedevel -DDEBUG_LEAKING_SCALARS -DPERL_USE_SAFE_PUTENV

         Remove the "-Duse64bitall" if you have a 32bit OS (or  machine).  Keep  answering  the  questions  with
         default  (hit  Enter) except for the question about additional cc flags. Here, put the default settings
         that are suggested in the [...] brackets and add two options:

           -DDEBUG_LEAKING_SCALARS -DPERL_USE_SAFE_PUTENV

         Afterwards, keep hitting return until the configuration is done.

       • Compile "perl" by typing "make" or for multiple CPUs, type "make -jX" where X is the number of CPUs+1.

       • If all went well, type "make install" to install your own private debugging perl.

       • Check whether the executables in /path/to/your/perl/bin all contain the version numbers  of  perl.  You
         may want to create symlinks of the basename.  If so, cd to the directory and run:

           perl -e 'for(@ARGV){$n=$_;s/5\.\d+\.\d+//; system("ln -s $n $_")}' *5.*

         Check that there's now also a perl symlink to perl5.12.1 (or whatever version of perl you built).

       • Setup the environment of your shell to use the new perl. For bash-like shells, do this:

           export PATH=/path/to/your/perl/bin:$PATH

         csh like shells probably use something like "setenv" or so.

       • Try running "perl -V" to see whether your new perl is being run.  (See also: "which perl")

         Make sure "perl -V" shows these particular "compile-time options":

           DEBUGGING DEBUG_LEAKING_SCALARS PERL_USE_SAFE_PUTENV
           PERL_USE_DEVEL

         There'll certainly be others, too.

   Building your own debugging wxWidgets
       • Make  sure  your  ~/.cpan  is  owned  by  you  and  not  being  used  by  another  perl. Maybe clean up
         ~/.cpan/build/* so there's no collisions.

       • Run cpan. (NOT as root!)

       • If you like, install "Bundle::CPAN" for convenience. Potentially restart cpan afterwards. Check whether
         the modules were installed into your fresh perl at /path/to/your/perl/lib.....

       • From cpan, type "look Alien::wxWidgets". You should get a new shell in an extracted  "Alien::wxWidgets"
         distribution.

       • Build wxWidgets by running:

           perl Build.PL --debug --unicode

         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.

         "Build.PL" will ask you whether you want to build from sources. Yes, you do.  Have it fetch the sources
         as .tar.gz.

           ./Build
           ./Build test
           ./Build install

   Installing a debugging Wx.pm
       • Now, you want to set up your own Wx.pm with debugging enabled.  First, install  the  prerequisites  for
         Wx. I did it like this:

           cpan> look Wx
           ...
           $ perl Makefile.PL
           ... blah blah missing this or that ...

         Take  note of the missing dependencies, exit to the CPAN shell, install the missing modules, then "look
         Wx" again.

       • If you have all Wx.pm dependencies in place, build "Wx" like this:

           perl Makefile.PL --wx-debug --wx-unicode
           make
           make test
           make install

   Installing Padre from SVN
       • Once Wx.pm is installed, check out Padre from the Subversion repository and cd to its  directory  under
         trunk/Padre.

       • Run "cpan ." to automatically install all dependencies of Padre!

       • Run the following to set up Padre:

           perl Makefile.PL
           make

       • Run dev to start Padre from your checkout.

           perl dev

         or with all plugins loaded:

           perl dev -h

         or with the Perl debugger:

           perl dev -d

       • 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.

SUPPORT

       For support with Padre itself, see the support section in the top level Padre class.

       For support on hacking Padre, the best place to go is the #padre channel on <irc://irc.perl.org/>.

COPYRIGHT

       Copyright 2008-2010 The Padre Team.

perl v5.18.1                                       2011-08-13                        Padre::Manual::Hacking(3pm)