=head1 NAME

Shipwright::Manual::Tutorial - introduction to Shipwright

=head1 SYNOPSIS

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

=head1 DESCRIPTION

Currently, Shipwright supports 3 kinds of backends: I<SVK>, I<SVN> and I<plain
file system>. e.g.

    svn:file:///tmp/svnrepo/foo
    svn:http://svn.example.com/foo
    svk://foo
    svk:/test/foo
    fs:/tmp/foo

Note: since we need C<svk>/C<svn>/C<svnadmin> cmds in in backends, sources or 
other places, we can tell shipwright the location of C<svk>/C<svn> cmds by 
setting ENV C<SHIPWRIGHT_SVK> or C<SHIPWRIGHT_SVN>.
C<svnadmin> is assumed in the same directory of svn. 


we'll use C<svn:file:///tmp/svnrepo/foo> as the repository for the rest tutorial.

=head2 create

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

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

=head2 import

It's worthless if we don't import some dists to Shipwright, let's do it now.

Shipwright supports 8 kinds of sources:

here're some examples:

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

=over 4

=item compressed file

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

=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
    
    svn:file:///tmp/svnrepo/foo>
    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.

=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 -r svn:file:///tmp/svnrepo/foo http://www.apache.org/dist/httpd/httpd-2.2.9.tar.gz --name apache
    $ shipwright import -r svn:file:///tmp/svnrepo/foo http://www.cpan.org/authors/id/R/RG/RGARCIA/perl-5.10.0.tar.gz
    $ shipwright import -r svn:file:///tmp/svnrepo/foo 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 -r svn:file:///tmp/svnrepo/foo ftp://xmlsoft.org/libxml2/libxml2-2.6.32.tar.gz --name libxml
    $ shipwright import -r svn:file:///tmp/svnrepo/foo 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> and I<Shipwright> types,
we can simply use the I<update> cmd to update:

    $ shipwright update -r svn:file:///tmp/svnrepo/foo 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 -r svn:file:///tmp/svnrepo/foo 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 -r svn:file:///tmp/svnrepo/foo apache http://www.apache.org/dist/httpd/httpd-2.2.10.tar.gz 
    $ shipwright update -r svn:file:///tmp/svnrepo/foo 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 have to do it manually, edit F</scripts/cpan-XML-LibXML/require.yml>
ourselves, at least by now.

Hey, you know how to edit that file, right? ;)

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

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