The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
# ABSTRACT: A narrative introduction to Pinto

package Pinto::Manual::Tutorial;

#------------------------------------------------------------------------------

# VERSION

#------------------------------------------------------------------------------
1;

__END__

=pod

=encoding UTF-8

=for :stopwords Jeffrey Ryan Thalhammer BenRifkah Fowler Jakob Voss Karen Etheridge Michael
G. Bergsten-Buret Schwern Oleg Gashev Steffen Schwigon Tommy Stanton
Wolfgang Kinkeldei Yanick Boris Champoux hesco popl Däppen Cory G Watson
David Steinbrunner Glenn

=head1 NAME

Pinto::Manual::Tutorial - A narrative introduction to Pinto

=head1 VERSION

version 0.094

=head1 INTRODUCTION

This tutorial walks you through some of the typical use cases for a
L<Pinto> repository.  Along the way, it demonstrates most of the
L<pinto> commands.  You are encouraged to try the commands as you read
along.  If you would prefer to get a more condensed summary of
features and commands, please read the L<Pinto::Manual::QuickStart>.
For detailed instructions on installing the software read
L<Pinto::Manual::Installing>.

=head1 BASIC OPERATIONS

=head2 Creating a repository

The first step in using Pinto is to create a repository, using the
L<init|App::Pinto::Command::init> command like this:

  $> pinto -r ~/repo init

This will create a new repository in the F<~/repo> directory.  If
that directory does not exist, it will be created for you.  If it
already does exist, then it must be empty.

The C<-r> (or C<--root>) option specifies where the repository is.
This argument is required for every L<pinto> command.  But if you get
tired of typing it, you can set the C<PINTO_REPOSITORY_ROOT>
environment variable to point to your repository instead.

The repository is created with a stack called "master" which is also 
marked as the default stack.  We'll talk more about stacks and default 
stack later.

=head2 Inspecting the repository

Now that you have a repository, let's look inside it.  To see the
contents of a repository, use the L<list|App::Pinto::Command::list>
command:

  $> pinto -r ~/repo list

You will use the L<list|App::Pinto::Command::list> command quite
often.  But at this point, the listing will be empty because there is
nothing in the repository.  So let's go ahead and add something...

=head2 Adding dependencies

Suppose we are working on an application called My-App that contains a
package called C<My::App>.  The application also depends on the L<URI>
package.  Using the L<pull|App::Pinto::Command::pull> command, you can
bring the URI package into your repository:

  $> pinto -r ~/repo pull URI

You will be prompted to enter a log message that describes why this
change is happening.  The message template will include a semi-informative
generated message.  Feel free to edit this message as you see fit.
Save the file and close your editor when you are done.

Now, you should have URI in your local repository.  So lets look
and see what we really got.  Once again, you use the
L<list|App::Pinto::Command::list> command to see inside the
repository:

  $> pinto -r ~/repo list

This time, the listing will look something like this:

  rf  URI                            1.60  GAAS/URI-1.60.tar.gz
  rf  URI::Escape                    3.31  GAAS/URI-1.60.tar.gz
  rf  URI::Heuristic                 4.20  GAAS/URI-1.60.tar.gz
  ...

You can see that the URI package has been added to the repository, as
well as all the prerequisites for URI, and all of their prerequisites,
and so on.

=head2 Adding your own distributions

Now suppose that you've finished work on My-App and your ready to
release the first version.  Using your preferred build tool
(L<ExtUtils::MakeMaker>, L<Module::Build>, L<Module::Install> etc.)
you package a release as F<My-App-1.0.tar.gz>.  Now put the
distribution into the repository with the
L<add|App::Pinto::Command::add> command:

  $> pinto -r ~/repo add path/to/My-App-1.0.tar.gz

When you list the repository contents now, it will include the
C<My::App> package and show you as the author of the distribution:

  rl  My::App                         1.0  JEFF/My-App-1.0.tar.gz
  rf  URI                            1.60  GAAS/URI-1.60.tar.gz
  rf  URI::Escape                    3.31  GAAS/URI-1.60.tar.gz
  rf  URI::Heuristic                 4.20  GAAS/URI-1.60.tar.gz
  ...

=head2 Installing packages

Now the repository contains both your application and all of its
prerequisites, so you can install it into your environment using 
the L<install|App::Pinto::Command::install> command:

  $> pinto -r ~/repo install My::App

When C<My::App> is installed, it will only use the prerequisites that
are in your repository.  Even if a newer version of URI is released
to the CPAN in the future, C<My::App> will always be built with the
same versions of the same prerequisites that you developed and tested
against.  This ensures your application builds will be stable and
predictable.

On the surface, a Pinto repository looks like an ordinary CPAN, so you 
can also install packages from it using L<cpanm> directly.  All you have 
to do is point them at the URL of your repository (under the hood, this
is all the L<install|App::Pinto::Command::install> command is really
doing anyway).  For example:

  $> cpanm --mirror file:///home/jeff/repo --mirror-only My::App

The C<--mirror-only> flag is important because it tells L<cpanm> to B<not>
look in other repositories for missing prerequisites.  Usually, you only
want to install things from B<your> repository.

You can do the same thing with L<cpan> and L<cpanp> as well.  See their
documentation for information on how to set the URL of the repository.  

=head2 Upgrading a dependency

Suppose that several weeks have passed since you first released My-App
and now URI version 1.62 is available on the CPAN.  It has some bug
critical fixes that you'd like to get.  Again, we can bring that into
the repository using the L<pull|App::Pinto::Command::pull> command.
But since your repository already contains a version of URI, you must
indicate that you want a *newer* one by specifying the minimum version
that you want:

  $> pinto -r ~/repo pull URI~1.62

If you look at the listing again, this time you'll see the newer
version of URI (and possibly other packages as well):

  rl  My::App                         1.0  JEFF/My-App-1.0.tar.gz
  rf  URI                            1.62  GAAS/URI-1.62.tar.gz
  rf  URI::Escape                    3.38  GAAS/URI-1.62.tar.gz
  rf  URI::Heuristic                 4.20  GAAS/URI-1.62.tar.gz
  ...

If the new version of URI requires any new prerequisites, those will
be in the repository too.  Now when you install C<My::App>, you'll get
version 1.62 of URI.

=head1 WORKING WITH STACKS

So far in this tutorial, we've treated the repository as a singular
resource.  For example, when we upgraded URI in the last section,
it impacted every person and every application that might have been
using the repository.  But this kind of broad impact is undesirable.
You would prefer to make those kinds of changes in isolation and test
them before forcing everyone else to upgrade.  This is what stacks
are designed for.

=head2 What is a stack

All CPAN-like repositories have an index which maps the latest version
of each package to the archive that contains it.  Usually, there is
only one such index per repository.  But with Pinto, there can be many
indexes.  Each of these indexes is called a "stack".  This allows you
to create different stacks of dependencies within a single repository.
So you could have a C<development> stack and a C<production> stack.
Whenever you add a distribution or upgrade a prerequisite, it only
affects one stack.

=head2 The default stack

Before getting into the gory details, you first need to know about the
default stack.  For most operations, the name of the stack is an
optional parameter.  So if you do not specify a stack explicitly, then
the operation is applied to whichever stack is marked as the default.

In any repository, there is never more than one default stack.  When we
created this repository, the C<master> stack was marked as the default.  
You can also change the default stack or change the name of a stack, but 
we won't go into that here.  See the L<default|App::Pinto::Command::default>
command to learn more about that.

Just remember that C<master> is the name of the stack that was created
when the repository was first initialized.

=head2 Creating a stack

Suppose your repository contains version 1.60 of URI, but version 1.62
has been released to the CPAN, just like in the earlier section.  You
want to try upgrading, but this time you're going to do it on a
separate stack.

Thus far, everything you've added or pulled into the repository has
gone onto the C<master> stack.  You could create an entirely new stack,
but the C<master> stack already has the prerequisites for My-App, so
we're just going to make a clone using the L<copy|App::Pinto::Command::copy> 
command:

  $> pinto -r ~/repo copy master uri_upgrade

This creates a new stack called C<uri_upgrade>.  If you want to see the
contents of that stack, just use the L<list|App::Pinto::Command::list>
command with the C<--stack> option:

  $> pinto -r ~/repo list --stack uri_upgrade

The listing should be identical to the C<master> stack:

  rl  My::App                         1.0  JEFF/My-App-1.0.tar.gz
  rf  URI                            1.60  GAAS/URI-1.60.tar.gz
  ...

=head2 Upgrading a stack

Now that you've got a separate stack, you can try upgrading URI.  Just
as before, you'll use the L<pull|App::Pinto::Command::pull> command.
But this time, you'll tell Pinto that you want the packages to be
pulled onto the C<uri_upgrade> stack:

  $> pinto -r ~/repo pull --stack uri_upgrade URI~1.62

Now lets compare the C<master> and C<uri_upgrade> stacks using the
L<diff|App::Pinto::Command::diff> command:

  $> pinto -r ~/repo diff master uri_upgrade

  +rf URI                                              1.62 GAAS/URI-1.62.tar.gz
  +rf URI::Escape                                      3.31 GAAS/URI-1.62.tar.gz
  +rf URI::Heuristic                                   4.20 GAAS/URI-1.62.tar.gz
  ...
  -rf URI                                              1.60 GAAS/URI-1.60.tar.gz
  -rf URI::Escape                                      3.31 GAAS/URI-1.60.tar.gz
  -rf URI::Heuristic                                   4.20 GAAS/URI-1.60.tar.gz

The output is similar to the diff(1) command. Records starting with a 
"+" were added and those starting with a "-" have been removed.

=head2 Installing from a stack

With URI upgraded on the C<uri_upgrade> stack, you can now try
building and testing our application.  All you have to do is run the
L<install|App::Pinto::Command::install> command and point to the
right stack:

  $> pinto -r ~/repo install --stack uri_upgrade My::App

This will build My::App using only the prerequisites that are on the
C<uri_upgrade> stack.  If the tests pass, then you can confidently
upgrade URI on the C<dev> stack as well.

As mentioned earlier, you can also use L<cpanm> to install modules from
your repository.  But when installing from a stack other than the default, 
you must append "stacks/stack_name" to the URL.  For example:

  $> cpanm --mirror file:///home/jeff/repo/stacks/uri_upgrade --mirror-only My::App

=head1 USING PINS

In the last section, we used a stack to experiment with upgrading a
dependency.  Fortunately, all the tests passed.  But what if the tests
didn't pass?  If the problem lies within My-App and you can quickly
correct it, you might just modify your code, release version 2.0 of
My-App, and then proceed to upgrade URI on the C<master> stack.

But if the issue is a bug in URI or it will take a long time to fix
My-App, then you have a real problem.  You don't want someone else to
upgrade URI, nor do you want it to be upgraded inadvertently to
satisfy some other prerequisite that My-App may have.  Until the bug
is fixed (in either URI or My-App) you need to prevent URI from being
upgraded.  This is what pins are for.

=head2 Pinning a package

When you pin a package, that version of the package is forced to stay
in a stack.  Any attempt to upgrade it (either directly or via another
prerequisite) will fail.  To pin a package, use the
L<pin|App::Pinto::Command::pin> command like this:

  $> pinto -r ~/repo pin URI

If you look at the listing for the C<master> stack again, you'll see
something like this:

  ...
  rl  My::App                         1.0  JEFF/My-App-1.0.tar.gz
  rf! URI                            1.60  GAAS/URI-1.60.tar.gz
  rf! URI::Escape                    3.31  GAAS/URI-1.60.tar.gz
  ...

The "!" near the beginning of the line indicates the package has been
pinned.  Notice every package in the F<URI-1.60.tar.gz> distribution
has been pinned, so it is impossible to partially upgrade a
distribution (this situation could happen when a package moves into a
different distribution).

=head2 Unpinning a packages

After a while, suppose you fix the problem in My-App or a new version
of URI is released that fixes the bug.  When that happens, you can
unpin URI from the stack using the L<unpin|App::Pinto::Command::unpin>
command:

  $> pinto -r ~/repo unpin URI

At this point you're free to upgrade URI to the latest version
whenever you're ready.  Just as with pinning, when you unpin a
package, it unpins every other package it that distribution as well.

=head1 USING PINS AND STACKS TOGETHER

Pins and stacks are used together to help manage change during the
development cycle.  For example, you could create a stack called
C<prod> that contains your known-good dependencies.  Likewise, you could
create a stack called C<dev> that contains experimental dependencies
for your next release.  Initially, the C<dev> stack is just a copy of
the C<prod> stack.

As development proceeds, you may upgrade or add several packages on
the C<dev> stack.  If an upgraded package breaks your application, then
you'll place a pin in that package on the C<prod> stack to signal that
it shouldn't be upgraded.

=head2 Pins and Patches

Sometimes you may find that a new version of a CPAN distribution has a
bug but the author is unable or unwilling to fix it (at least not
before your next release is due).  In that situation, you may elect to
make a local patch of the CPAN distribution.

So suppose that you forked the code for L<URI> and made a local
version of the distribution called F<URI-1.60_PATCHED.tar.gz>.  You
can add it to your repository using the
L<add|App::Pinto::Command::add> command:

  $> pinto -r ~/repo add path/to/URI-1.60_PATCHED.tar.gz

In this situation, it is wise to pin the package as well, since you do
not want it to be upgraded until you are sure that the new release
includes your patch or the author has fixed the bug by other means.

  $> pinto -r ~/repo pin URI

When the author of URI releases version 1.62 with your patch,
you'll want to try it before deciding to unpin from your locally
patched version.  Just as before, this can be done by cloning the
stack with the L<copy|App::Pinto::Command::copy> command.  Let's call
it the C<trial> stack this time:

 $> pinto -r ~/repo copy master trial

But before you can upgrade URI on the C<trial> stack, you'll have to
unpin it there:

  $> pinto -r ~/repo unpin --stack trial URI

Now you can proceed to upgrade URI on the stack and try building
C<My::App> like this:

  $> pinto -r ~/repo pull --stack trial URI~1.62
  $> pinto -r ~/repo install --stack trial My::App

If all goes well, remove the pin from the C<master> stack and pull your
latest version of URI back to it.

  $> pinto -r ~/repo unpin URI
  $> pinto -r ~/repo pull URI~1.62

=head2 Reviewing Past Changes

As you've noticed by now, each command that changes the state of a stack
requires a log message to describe it.  You can review those messages
using the L<log|App::Pinto::Command::log> command:

  $> pinto -r ~/repo log

That should display something like this:

  revision 4a62d7ce-245c-45d4-89f8-987080a90112
  Date: Mar 15, 2013 1:58:05 PM
  User: jeff 
  
       Pin GAAS/URI-1.59.tar.gz

       Pinning URI because it is not causes our foo.t script to fail
  
  revision 4a62d7ce-245c-45d4-89f8-987080a90112
  Date: Mar 15, 2013 1:58:05 PM
  User: jeff 
  
       Pull GAAS/URI-1.59.tar.gz

       URI is required for HTTP support in our application

  ...

The header for each message shows who made the change and when it happened.  
It also has a unique identifier similar to Git's SHA-1 digests.  You can 
use these identifiers to see the diffs between different revisions or to 
reset the stack back to a prior revision [NB: this feature is not actually 
implemented yet].

=head1 CONCLUSION

In this tutorial, you've seen the basic L<pinto> commands for pulling
dependencies into the repository, and adding your own distributions to
the repository.  You've also seen how to use stacks and pins to manage
your dependencies in the face of some common development obstacles.

Each command has several options that were not discussed in this
tutorial, and there are some commands that were not mentioned here at
all.  So you are encouraged to explore the manual pages for each
command and learn more.

=head1 SEE ALSO

L<Pinto::Manual::QuickStart>

L<Pinto::Manual::Installing>

L<Pinto> (the library)

L<pinto> (the command)

=head1 AUTHOR

Jeffrey Ryan Thalhammer <jeff@stratopan.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Jeffrey Ryan Thalhammer.

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