NAME

Shipwright::Manual::Tutorial - introduction to Shipwright

SYNOPSIS

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

DESCRIPTION

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

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

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

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

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

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:

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

compressed file

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

plain directory

    dir:/tmp/foo
    directory:/home/ross/dinosaur-0.01

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

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

SVK

    svn:file:///tmp/svnrepo/foo>
    svk:/test/foo

SVN

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

CPAN

    cpan:Jifty
    cpan:Module::Install

It's ok, Shipwright will find the download link automatically for us, with CPAN's help.

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.

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 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 autoconf, ExtUtils::MakeMaker, Module::Install, and Module::Build), we would now need to edit 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 Shipwright::Manual::CustomizeBuild.

update

For dists with CPAN, SVK, SVN and Shipwright types, we can simply use the 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 relocate cmd.

e.g. apache 2.2.10 is released one day, with download link 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

tweak manually

You may find that cpan-XML-LibXML needs libxml as a dependence, but in /scripts/cpan-XML-LibXML/require.yml there's no such entry, because require.yml is created automatically, filled with perl module dists, no extra dependence will be set.

So we have to do it manually, edit /scripts/cpan-XML-LibXML/require.yml ourselves, at least by now.

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

build

We need to check out the repository to some place first, then chdir there, and run:

$ ./bin/shipwright-builder

Run ./bin/shipwright-builder --help to see more options.

ship our vessel

We call the built stuff the vessel.

To ship our vessel, create an archive of the built files using an archive program such as tar, e.g. by running 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 /home/user/.bashrc on most systems): 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.

SEE ALSO

Shipwright::Manual::UsingFlags, Shipwright::Manual::CustomizeBuild, Shipwright::Manual::Glossary

AUTHORS

sunnavy <sunnavy@bestpractical.com>

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.

cpanm Shipwright

perl -MCPAN -e shell
install Shipwright