=head1 NAME

Shipwright::Manual::Tutorial - Shipwright tutorial

=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 allows you to
manage shipyard: L<create|/Create a new shipyard>,
L<import sources|/Import sources>, L</update>, and so on.

Let's start from a new shipyard.

=head2 Create a new shipyard

shipyard - the place where all stuff lives.
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 FS in this tutorial.

Let's create a new shipyard:

    $ shipwright create -r fs:/tmp/foo

To avoid typing I<-r fs:/tmp/foo> all the time you can use "SHIPWRIGHT_SHIPYARD"
environment variable.

    $ export SHIPWRIGHT_SHIPYARD="fs:/tmp/foo"

from now on we don't need the "-r ..." for the session.

=head2 Import sources

Our shipyard is worthless if it doesn't contain any source, let's import some

Shipwright supports various types of sources.
Here're some examples:

=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
    
    svk:/test/foo

=item SVN

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

=item Git

    git:file:///tmp/foo.git

=item CPAN

    cpan:Jifty
    cpan:Module::Install

=item shipyard

    shipyard:fs:/tmp/shipyard/foo
    shipyard:fs:/tmp/shipyard/bar

fs:/tmp/shipyard is another shipyard, 'foo' or 'bar' is the
source 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/SOURCE_NAME/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<shipyard> 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 dependences 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<checkout> the repository to some place first,
then I<chdir> there, and run:
(for FS backend, no need to checkout, just chdir to /tmp/foo ),

$ ./bin/shipwright-builder --install-base /tmp/vessel

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

=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 vessel.tar.gz
/tmp/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.


=head2 ship shipyard

If you want to ship a shipyard instead of the vessel, you can just tar your
shipyard( i.e. "/tmp/foo" ) and ship it, though Shipwright supplies a
convinent way too:

let's chdir to our shipyard first, then run:
$ ./bin/shipwright-utility --generate-tar-file /tmp/shipyard.pl

the shipyard.pl is a shipyard perl script working like "shipwright-builder"
but it's self contained, so you can build vessel with shipyard.pl like this:

$ perl /tmp/shipyard.pl --install-base /tmp/vessel

=head1 SEE ALSO

L<Shipwright>, L<Shipwright::Manual>

=head1 AUTHORS

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

=head1 LICENCE AND COPYRIGHT

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

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