=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

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 Shipwrihgt 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 automitacally,
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

There're two ways to build a Shipwright project, we can use Shipwright's
I<build> command or use the F</bin/shipwright-builder> in the repository. 

=over 4

=item build cmd

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

You can tell Shipwright the dir to install to by C<--install-base> arg.

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

=item F<./bin/shipwright-buider>

F<./bin/shipwright-buider> lives in the Shipwright repository,
so 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.

=back

=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/hello/etc/shipwright-source-bash> (for bash users). A source script
is also provided for the tcsh shell.
                                    
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>

=cut