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 and 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 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 Shipwrihgt 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 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 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

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

build cmd

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

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

Run shipwright help build to see more options.

./bin/shipwright-buider

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

SEE ALSO

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

cpanm Shipwright

perl -MCPAN -e shell
install Shipwright