=head1 NAME
Shipwright::Manual::Tutorial - Tutorial to Shipwright
=head1 SYNOPSIS
In this tutorial, we'll create a vessel to represent basic stuff of Shipwright.
=head1 DESCRIPTION
Currently, Shipwright supports 4 kinds of backends: I<SVK>, I<SVN>, I<Git> and I<plain
file system>. e.g.
svk:/test/foo
fs:/tmp/foo
Note: since we need C<svk>/C<svn>/C<svnadmin>/C<git> cmds in in backends, sources or
other places, we can tell shipwright the location of C<svk>/C<svn>/C<git> cmds by
setting ENV C<SHIPWRIGHT_SVK>/C<SHIPWRIGHT_SVN>/C<SHIPWRIGHT_GIT>.
C<svnadmin> is assumed in the same directory of svn.
=head2 create
We need to create the svn repo first:
$ svnadmin create /tmp/svnrepo
Then we can initialize the repository of our Shipwright project:
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
=item FTP
=item SVK
svk:/test/foo
=item SVN
=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.
( use --no-follow is because run Makefile.PL will hung if we don't have
apache installed )
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 buildmechanism 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: (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:
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
set the source url first before update.
=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=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.
=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.