=head1 NAME

Shipwright::Manual::Tutorial - introduction to Shipwright

=head1 SYNOPSIS

In this tutorial, we'll create a simple vessel: the L<Acme::Hello> module
from CPAN.

We will use C<svk://__shipwright/hello> as our repository.

=head1 DESCRIPTION

There are three main steps to creating a shipwright vessel.

=head2 1. initialize

    $ shipwright create -r svk://__shipwright/hello

=head2 2. import

    $ shipwright import -r svk://__shipwright/hello cpan:Acme::Hello

Then shipwright will try to download and import L<Acme::Hello> and all its
dependencies from CPAN. (You can import from other types of sources as well;
see C<shipwright help import> to find out about them.) In Shipwright terms,
these imported sources are called I<distributions>, and are stored under
F<dists/> in the repository.

If you want to skip some dependencies, e.g. L<Locale::Maketext> and
L<Locale::Maketext::Lexicon>, just say C<--skip
Locale::Maketext,Locale::Maketext::Lexicon>.

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

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

=head2 3. build

    $ shipwright build -r svk://__shipwright/hello

If tests are time-consuming or for some reason unnecessary for your build, you
can add C<--skip-test> to skip them.

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

And that's it! Your build should end with a bunch of lines beginning with
C<Installing>. These specify where you can find your built vessel. This will
generally be in a subdirectory of F</tmp>, but you can specify a different
location with C<--install-base>.

To ship your vessel, create an archive of the built files using an archive
program such as C<tar>, e.g. by running C<tar czvf your-vessel.tar.gz
/tmp/your-vessel>. Users can use your 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): C<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 your vessel as with normal
installed programs, though they will need to start a new shell or re-run their
startup script.

A log of the above commands can be found in F<docs/tutorial.log>.

=head1 NOTES

=head2 Updating distributions

There are two commands you can use to update a distribution: C<update> and
C<import>.

If you would like to just update the distribution source (files in F<dists/>),
use C<update>. It will delete the directory in F<dists/> and add it again.

The other way is to C<import> the distribution again. This will delete the
corresponding directories in F<dists/> and F<scripts/> and then add new ones. If
you want to update the dependency lists too, just add the C<--overwrite>
option.

=head1 SEE ALSO

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

=cut