=head1 NAME

Shipwright::Manual::Tutorial - Tutorial to Shipwright

=head1 DESCRIPTION

In this tutorial, we'll create a vessel to represent basic stuff of Shipwright.

=head1 TUTORIAL

=head1 Introduction

Shipwright is shipped with command line tool F<shipwright> which allow you to manage
shipwright repositories: L<create|/Create a new repository>,
L<import dists|/Importing dists into the repository> and L</update>.

Let's start from a new repository.

=head2 Create a new repository

Repository - the backend, where all stuff lives, e.g. metadata, sources, etc...
Shipwright supports several backends: L<SVK|Shipwright::Backend::SVK>,
L<SVN|Shipwright::Backend::SVN>, L<Git|Shipwright::Backend::Git> and
L<plain file system|Shipwright::Backend::FS>. We'll use SVN backend for
our repository in this tutorial.

We need to create the svn repo first:

    $ svnadmin create /tmp/svnrepo

Then we can initialize the repository of our Shipwright project:

    $ shipwright create -r svn:file:///tmp/svnrepo/foo

If F<svn> executable is not under PATH then you can tell shipwright
the location of it by setting environment variable "SHIPWRIGHT_SVN".
F<svnadmin> is assumed in the same directory as F<svn>.

=head2 Don't repeat -r argument

To avoid typing I<-r svn:file:///tmp/svnrepo/foo> all the time you
can use "SHIPWRIGHT_REPOSITORY" environment variable.

    export SHIPWRIGHT_REPOSITORY="svn:file:///tmp/svnrepo/foo"

Done. No more -r ... for the session.

=head2 Import dists into the repository

Our repository is worthless if we don't import some dists. let's do
it now.

Shipwright supports different sources you can import things from.
Here're some examples:

=over 4

=item compressed file

    file:/tmp/foo.tar.gz
    file:/home/ross/dinosaur-0.01.tar.bz2

B<Caveat>: for files, we only support I<.tar.gz>(I<.tgz>) and I<.tar.bz2> format currently.

=item plain directory

    dir:/tmp/foo
    directory:/home/ross/dinosaur-0.01


=item HTTP
    
    http://apache.mirror.phpchina.com/httpd/httpd-2.2.9.tar.gz
    http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/authors/id/C/CL/CLKAO/SVK-v2.0.2.tar.gz


=item FTP

    ftp://ftp.gnupg.org/gcrypt/gnupg/gnupg-1.4.9.tar.bz2
    ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/authors/id/C/CL/CLKAO/SVK-v2.0.2.tar.gz

=item SVK
    
    svk:/test/foo

=item SVN

    svn:file:///tmp/repo/foo
    svn:http://svn.example.com/foo

=item CPAN

    cpan:Jifty
    cpan:Module::Install

It's ok, Shipwright will find the download link automatically for us,
with L<CPAN>'s help. thanks, L<CPAN>!

=item Shipwright

    shipwright:svk:/shipwright/repo/foo
    shipwright:svk:/shipwright/repo/bar

svk:/shipwright/repo is another shipwright repository, 'foo' or 'bar' is the
dist name we want to import.

=back

We'll import apache 2.2.9, perl 5.10, mod_perl 2.0, libxml and XML::LibXML
in this tutorial one by one.

    $ shipwright import http://www.apache.org/dist/httpd/httpd-2.2.9.tar.gz --name apache
    $ shipwright import http://www.cpan.org/authors/id/R/RG/RGARCIA/perl-5.10.0.tar.gz
    $ shipwright import http://perl.apache.org/dist/mod_perl-2.0-current.tar.gz --name mod_perl --no-follow
    ( use --no-follow is because run Makefile.PL will hung if we don't have
      apache installed )
    $ shipwright import ftp://xmlsoft.org/libxml2/libxml2-2.6.32.tar.gz --name libxml
    $ shipwright import cpan:XML::LibXML

Run I<shipwright help import> to see more options.

As a side note, if we were importing from a source that doesn't use a build
mechanism that Shipwright can automatically create a set of build instructions
for (currently I<autoconf>, L<ExtUtils::MakeMaker>, L<Module::Install>, and 
L<Module::Build>), we would now need to edit F<scripts/DISTNAME/build> to tell
Shipwright how to build that source.

For our tutorial, e.g. perl 5.10, the build can't be created automatically,
so we need to edit the build file:

  configure: ./Configure -des -Dprefix=%%INSTALL_BASE%%
  test: make test
  install: make install

For more information on build scripts, see L<Shipwright::Manual::CustomizeBuild>.

=head2 update

For dists with I<CPAN>, I<SVK>, I<SVN>, I<Git> and I<Shipwright> types,
we can simply use the I<update> cmd to update:

    $ shipwright update cpan-XML-LibXML
    (yeah, that's right, cpan:XML::LibXML will be named cpan-XML-LibXML)

we can also specify the version we want to update to with --version arg:

    $ shipwright update cpan-XML-LibXML --version 1.60

For other types, Shipwright can't find the latest version, so we have to tell 
Shipwright where it is by I<relocate> cmd.

e.g. apache 2.2.10 is released one day, with download link
L<http://apache.mirror.phpchina.com/httpd/httpd-2.2.10.tar.gz>, we need to 
set the source url first before update.

    $ shipwright relocate apache http://www.apache.org/dist/httpd/httpd-2.2.10.tar.gz 
    $ shipwright update apache

=head2 tweak manually 

You may find that I<cpan-XML-LibXML> needs I<libxml> as a dependence, but
in F</scripts/cpan-XML-LibXML/require.yml> there's no such entry,
because F<require.yml> is created automatically, filled with perl module dists,
no extra dependence will be set.

So we need to do it manually, e.g. use the following cmd to do so

    $ shipwright update apache --add-deps libxml

=head2 build

We need to I<check out> the repository to some place first,
then I<chdir> there, and run:

$ ./bin/shipwright-builder 

Run I<./bin/shipwright-builder --help> to see more options and
I<./bin/shipwright-builder --advanced-help> to see even more options.

For the layout of shipwright's source, see L<Shipwright>.

=head2 fiddle the vessel

we can use bin/shipwright-filter to fiddle the vessel, e.g. removing pods.
Run I<./bin/shipwright-filter --help> to see more options

=head2 ship our vessel

We call the built stuff the I<vessel>.

To ship our vessel, create an archive of the built files using an archive
program such as I<tar>, e.g. by running I<tar czvf our-vessel.tar.gz
/tmp/our-vessel>.

Users can use our vessel by extracting the archive to a directory and then
adding the following command to their shell's startup script
(e.g. for bash users, edit F</home/user/.bashrc> on most systems): I<source
/base/path/tools/etc/shipwright-source-bash> (for bash users). A source script
is also provided for the tcsh shell. 

Here is a sourcing example:

  source /home/user/myapp/tools/shipwright-source-bash /home/user/myapp

This example assumes the myapp vessel was extracted to /home/user/myapp.
                                    
After sourcing this script, users will be able to run binaries and load perl
modules from our vessel as with normal installed programs, though they will 
need to start a new shell or re-run their startup script.

=head1 SEE ALSO

L<Shipwright::Manual::UsingFlags>, L<Shipwright::Manual::CustomizeBuild>,
L<Shipwright::Manual::Glossary>

=head1 AUTHORS

sunnavy  C<< <sunnavy@bestpractical.com> >>

=head1 LICENCE AND COPYRIGHT

Shipwright is Copyright 2007-2009 Best Practical Solutions, LLC.

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