# ABSTRACT: Tips for installing Pinto

package Pinto::Manual::Installing;

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

# VERSION

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

__END__

=pod

=for :stopwords Jeffrey Ryan Thalhammer Imaginative Software Systems Perlbrew cpanm

=head1 NAME

Pinto::Manual::Installing - Tips for installing Pinto

=head1 VERSION

version 0.068

=head1 SYNOPSIS

For the impatient...

  curl -L http://getpinto.stratopan.com | bash
  export PINTO_HOME=$HOME/opt/local/pinto
  export PATH=$PINTO_HOME/bin:$PATH

And then possibly...

  echo export PINTO_HOME=\$HOME/opt/local/pinto >> ~/.bashrc
  echo export PATH=$PINTO_HOME/bin:$PATH >> ~/.bashrc

=head1 App::Pinto and Pinto (and Pinto::Remote)

The Pinto suite is divided into several different modules.  L<App::Pinto> is 
the front-end driver that provides the L<pinto> command-line application. 
L<Pinto> is the back-end library that does all the work.  These two modules
are shipped in separate distributions.  But to do anything useful, you will
need to install both of them.

There is also L<Pinto::Remote>, which is the back-end for using a remote 
repository (via L<Pinto::Server>) and can be installed instead of Pinto.  But
as of March 2013, Pinto::Remote and Pinto::Server are broken so I assume you
won't be using them.  I plan to fix those shorty and will update this 
documentation when they are released.

=head1 APPLICATION VERSUS LIBRARY

For most situations, Pinto is more like an I<application> than a I<library>.
It is a tool that you use to develop and deploy your code, but Pinto itself
is not I<part of> your code.  Pinto also has a lot of dependencies, some of 
which may conflict with or complicate your code.

=head1 INSTALLING AS AN APPLICATION

For the reasons above, I recommend installing Pinto as a stand-alone 
application in its own sandbox.  That way, it doesn't pollute your 
environment with its dependencies.  Nor will you pollute Pinto with changes to
your environment, so Pinto will function even when your other environment 
dependencies are broken. And hopefully, you can use Pinto to help fix whatever
broke!

=head2 Step 1: Run the pinto installer script

The installer script at getpinto.stratopan.com is just a wrapper around 
cpanm, which installs pinto in a self-contained directory:

   # If you have curl...
   curl -L http://getpinto.stratopan.com | bash

   # If you use wget...
   wget -O - http://getpinto.stratopan.com | bash

All the dependent modules will come from a curated repository on 
L<stratopan.com|http://stratopan.com>.  These aren't always the latest 
versions of things, but they are versions that I know will work.

=head2 Step 2: Set the PINTO_HOME environment variable

The pinto installer puts pinto I<outside> of the default Perl environment.  
So you need to tell pinto where it lives:

  export PINTO_HOME=$HOME/opt/local/pinto

For convenience, you'll probably also want C<pinto> to be in your C<PATH>.
It lives in the C<bin> directory inside C<PINTO_HOME>:

  export PATH=$PINTO_HOME/bin:$PATH

To make these settings part of your everyday shell environment, just add 
those two C<export> commands to your F<~/.bashrc> or F<~/.cshrc> or 
whatever setup file is appropriate for your shell.

=head2 INSTALLING AS A LIBRARY

If you're going to be hacking on Pinto itself, or want to try building on 
the API directly, then you can install Pinto straight into your development
environment, just like you would do for any other module.

Just beware that Pinto has lots of dependencies.  And if you subsequently
upgrade any of those dependencies to something that breaks Pinto, then
you might find yourself in a pickle.  The whole point of Pinto is to
help you manage your dependencies, so if you break Pinto, it won't be able
to help you.

=head1 OTHER INSTALLATION OPTIONS 

Naturally, installation procedures will vary from one environment to another.
If this procedure doesn't work for you, or if you'd like to suggest a 
procedure for a different environment (e.g. Windows, Perlbrew, Strawberry
Perl, etc.), then please contact me.  Your contributions would be greatly
appreciated.

=head1 AUTHOR

Jeffrey Ryan Thalhammer <jeff@stratopan.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Imaginative Software Systems.

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
