package Dancer::Manual::Developers;

# PODNAME: Dancer::Manual::Developers
# ABSTRACT: Steps to follow to hack on Dancer

__END__

=pod

=head1 NAME

Dancer::Manual::Developers - Steps to follow to hack on Dancer

=head1 VERSION

version 1.9999_02

This document is for developers. If you want to try out Dancer, hack it
a bit, fix bugs, improve documentations, provide patches, etc. , you need to be
able to build it and understand some basic stuff. This document tries to help in this regard.

=head1 Get Git

Go to L<http://git-scm.com>, and get a git client for your platform

=head1 Get Dancer sources from GitHub

Go to L<https://github.com/PerlDancer/Dancer2>. Then you can either grab a tarball, or clone read-only, or fork the project.

I recommend you to fork the project into your github account, so that you can
go write modifications, and provide patches (Pull Requests) to upstream easily.

So go on and click on the I<Fork> button. Then git clone your Dancer forked
repo.

=head1 Prepare your environment (Perlbrew version)

You need Perl, and Dist::Zilla, and a few additional modules. This section
describes how to get to a point where all the test passes and Dancer is
usable, starting from nothing, using Perlbrew.

=head2 Get Perlbrew

Perlbrew allows you to have multiple version of Perl on your system, alongside
your system built-in Perl. It's very handy, and doesn't require administration
permissions.

Go to L<http://perlbrew.pl/> and follow the instructions to install the
C<perlbrew> program.

=head2 Install Perl

Now you need to pick up a version of Perl you'll install. Depending on what the
current stable version is, the following line will have to be adapted. At the
time of writing.

To see which version of perl is available, use:

  # perlbrew available
  perl-5.17.1
  perl-5.16.0
  perl-5.14.2
  perl-5.12.4
  perl-5.10.1
  perl-5.8.9
  perl-5.6.2
  perl5.005_04
  perl5.004_05
  perl5.003_07

Then go on and install a version inside Perlbrew. I recommend you give a name
to the installation (C<--as> option), as well as compiling without the tests
(C<--n> option) to speed it up.

  perlbrew install -n perl-5.14.2 --as dancer_development -j 3

Wait a while, and it should be done. Switch to your new Perl with:

  perlbrew switch dancer_development

Now you are using the fresh Perl, you can check it with:

  which perl

=head2 Install cpanm

To be able to easily and quickly install Perl modules, I recommend using C<cpanm>

  perlbrew install-cpanm

=head2 Install Dist::Zilla

Dancer uses Dist::Zilla ( L<http://dzil.org/> ). Dist::Zilla is a program to
make it easier to write, package, manage, and release free software.

However, it's not built in Perl, so let's install it:

  cpanm -n Dist::Zilla

That will take some time, but should install properly.

After that is done, you should be able to launch C<dzil>:

  # dzil
  Available commands:

      commands: list the application's commands
          help: display a command's help screen

    authordeps: list your distribution's author dependencies
         build: build your dist
         clean: clean up after build, test, or install
       install: install your dist
      listdeps: print your distribution's prerequisites
           new: mint a new dist
           nop: do nothing: initialize dzil, then exit
       release: release your dist
           run: run stuff in a dir where your dist is built
         setup: set up a basic global config file
         smoke: smoke your dist
          test: test your dist

If that's the case, all's good.

=head2 Install dist.ini dependencies

The Dancer sources come with a C<dist.ini>. That's the configuration files for
C<Dist::Zilla>, so that it knows how to build Dancer. However, in this
configuration files, we use several C<Dist::Zilla> plugins, that are not yet
installed. Let's do that with:

  dzil authordeps | cpanm -n

That should install a bunch of stuff

=head2 Install Dancer dependencies

Now that C<Dist::Zilla> is up and running, you should install the dependencies
required by Dancer:

  dzil listdeps | cpanm -n

When that is done, you're good to go !

=head1 Test Dancer

Launching the Dancer test suite is easy:

  dzil test

=head1 AUTHOR

Dancer Core Developers

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Alexis Sukrieh.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut
