Shipwright::Manual::Tutorial - Tutorial to Shipwright
In this tutorial, we'll create a vessel to represent basic stuff of Shipwright.
Shipwright is shipped with command line tool shipwright which allow you to manage shipwright repositories: create, import dists and "update".
Let's start from a new repository.
Repository - the backend, where all stuff lives, e.g. metadata, sources, etc... Shipwright supports several backends: SVK, SVN, Git and plain file system. We'll use SVN backend for our repository in this tutorial.
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
If svn executable is not under PATH then you can tell shipwright the location of it by setting environment variable "SHIPWRIGHT_SVN". svnadmin is assumed in the same directory as svn.
To avoid typing -r svn:file:///tmp/svnrepo/foo all the time you can use "SHIPWRIGHT_REPOSITORY" environment variable.
export SHIPWRIGHT_REPOSITORY="svn:file:///tmp/svnrepo/foo"
Done. No more -r ... for the session.
Our repository is worthless if we don't import some dists. let's do it now.
Shipwright supports different sources you can import things from. Here're some examples:
file:/tmp/foo.tar.gz
file:/home/ross/dinosaur-0.01.tar.bz2
Caveat: for files, we only support .tar.gz(.tgz) and .tar.bz2 format currently.
dir:/tmp/foo
directory:/home/ross/dinosaur-0.01
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.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:/test/foo
svn:file:///tmp/repo/foo svn:http://svn.example.com/foo
cpan:Jifty
cpan:Module::Install
It's ok, Shipwright will find the download link automatically for us, with CPAN's help. thanks, CPAN!
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 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 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.
For dists with CPAN, SVK, SVN, Git and Shipwright types, we can simply use the 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 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 apache http://www.apache.org/dist/httpd/httpd-2.2.10.tar.gz $ shipwright update apache
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 need to do it manually, e.g. use the following cmd to do so
$ shipwright update apache --add-deps libxml
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 and ./bin/shipwright-builder --advanced-help to see even more options.
For the layout of shipwright's source, see Shipwright.
we can use bin/shipwright-filter to fiddle the vessel, e.g. removing pods. Run ./bin/shipwright-filter --help to see more options
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.
Shipwright::Manual::UsingFlags, Shipwright::Manual::CustomizeBuild, Shipwright::Manual::Glossary
sunnavy <sunnavy@bestpractical.com>
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.
