Shipwright::Manual::Tutorial - introduction to Shipwright
In this tutorial, we'll create a simple vessel: the Acme::Hello module from CPAN.
We will use svk://__shipwright/hello as our repository.
There are three main steps to creating a shipwright vessel.
$ shipwright create -r svk://__shipwright/hello
$ shipwright import -r svk://__shipwright/hello cpan:Acme::Hello
Then shipwright will try to download and import Acme::Hello and all its dependencies from CPAN. (You can import from other types of sources as well; see shipwright help import to find out about them.) In Shipwright terms, these imported sources are called distributions, and are stored under dists/ in the repository.
If you want to skip some dependencies, e.g. Locale::Maketext and Locale::Maketext::Lexicon, just say --skip Locale::Maketext,Locale::Maketext::Lexicon.
Run 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 scripts/DISTNAME/build to tell Shipwright how to build that source. For more information on build scripts, see Shipwright::Manual::CustomizeBuild.
$ shipwright build -r svk://__shipwright/hello
If tests are time-consuming or for some reason unnecessary for your build, you can add --skip-test to skip them.
Run shipwright help build to see more options.
And that's it! Your build should end with a bunch of lines beginning with Installing. These specify where you can find your built vessel. This will generally be in a subdirectory of /tmp, but you can specify a different location with --install-base.
To ship your vessel, create an archive of the built files using an archive program such as tar, e.g. by running 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 /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 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 docs/tutorial.log.
There are two commands you can use to update a distribution: update and import.
If you would like to just update the distribution source (files in dists/), use update. It will delete the directory in dists/ and add it again.
The other way is to import the distribution again. This will delete the corresponding directories in dists/ and scripts/ and then add new ones. If you want to update the dependency lists too, just add the --overwrite option.
Shipwright::Manual::UsingFlags, Shipwright::Manual::CustomizeBuild, Shipwright::Manual::Glossary
