NAME
Shipwright - Best Practical Builder
SYNOPSIS
use Shipwright;DESCRIPTION
Why use Shipwright?
Shipwright is a tool to help you bundle your software.
Most software packages depend on other bits of software in order to avoid code repetition and repeating work that's already been done. This can result in pain and suffering when attempting to install the software, due to having to untangle the maze of dependencies. First, non-CPAN dependencies must be found and installed. Then, CPAN:: or CPANPLUS:: can be used to install all dependencies available on CPAN with minimal pain.
While this works, it has some drawbacks, especially for large projects which have many dependencies. Installation can take many iterations of trying to install from CPAN and then stopping to install other non-CPAN dependencies that the CPAN packages depend on. For example, SVK requires the non-CPAN packages subversion and swig. In the end, installing large projects with many dependencies is not very friendly for users, especially since dependencies may change their functionality and break builds with untested versions.
Enter Shipwright, a tool to help you bundle your software with all of its dependencies, regardless of whether they are CPAN modules or non-Perl modules from elsewhere. Shipwright makes it easy to build and install a bundle of your software, usually with just a single command:
$ ./bin/shipwright-builder
As a general note when reading this and other Shipwright documentation: we will often call a piece of software that your software depends on and is distributed elsewhere a dist, short for distribution. This and other Shipwright terminology are defined in Shipwright::Manual::Glossary.
Introduction
If this is your first time using Shipwright, Shipwright::Manual::Tutorial is probably a better place to start.
Design
The idea of Shipwright is simple:
raw material shipwright factory
--------------------- ------------------------
| all the separate | import | internal shipwright | build
| dist sources | =====> | repository | ====>
--------------------- ------------------------
vessel (final product)
----------------------------------------------
| all packages installed with smart wrappers |
----------------------------------------------There are two main commands in shipwright: import and build, which can be invoked like this:
$ shipwright import ...
$ check out your repository and cd there $ ./shipwright-builder ...
What's in a Shipwright repository or vessel
repository after initialization
After initializing a project, the files in the repository are:
bin/ # used for building, installing and testing shipwright-builder
# a utility for doing things such as updating the build order
shipwright-utilityetc/ # wrapper for installed bin files, mainly for optimizing the environment shipwright-script-wrapper
# wrapper for installed perl scripts
shipwright-perl-wrapper
# source files you can `source', for tcsh and bash, respectively.
# both will be installed to tools/
shipwright-source-tcsh, shipwright-source-bash
# utility which will be installed to tools/
shipwright-utilitysources/ # all the sources of your dists live here
scripts/ # all the build scripts and dependency hints live here
shipwright/ # the actual build order order.yml # non-cpan dists' name => url map source.yml # cpan dists' module => name map map.yml
t/ # will run this if with --only-test when build test
repository after import
After importing, say cpan:Acme::Hello, both the sources and scripts directories will have a `cpan-Acme-Hello' directory.
Under scripts/cpan-Acme-Hello there are two files: 'build' and 'require.yml'.
build
configure: %%PERL%% Build.PL --install_base=%%INSTALL_BASE%% make: %%PERL%% Build test: %%PERL%% Build test install: %%PERL%% Build install clean: %%PERL%% Build realclean
Each line is of `type: command' format, and the command is executed line by line (which is also true for t/test).
See Shipwright::Manual::CustomizeBuild for more information on customizing the build process for dists.
require.yml
build_requires: {}
conflicts: {}
recommends: cpan-Locale-Maketext-Lexicon: version: 0.15 requires: {}
This file details the hints needed in order for Shipwright to create the right build order.
vessel
After the source repository is built, we have a new directory structure which we call a vessel.
Normally, the vessel contains bin/, bin-wrapper/, etc/, tools/ and lib/ directories. One thing to note is that files below bin/ are for you to run, while the files below bin-wrapper/ are not. The bin/ directory contains links to a wrapper around the files in bin-wrapped/, and these programs will only work correctly if run through the wrapper.
METHODS
new PARAMHASH
This class method instantiates a new Shipwright object, which initializes all Shipwright components (if possible).
Arguments
general part:
repository: specify backend's path, e.g. svk:/t/test
log_level: specify log level, default is FATAL
log_file: specify log file, default is append to screensource part:
source: the source we need to import
name: source's name
follow: follow dependency chain or not, default is true
min_perl_version: minimal required perl version,
default is the same as the perl which is running shipwright
skip: hashref where the keys are the skipped modules when importing,
default is undefined
version: source's version, default is undefinedbuild part:
perl: the path of the perl that runs the commands in scripts/foo/build(.pl),
default is $^X, the one that is running shipwright
skip: hashref where the keys are the skipped dists when install,
default is undefined
skip_test: skip test or not, default is false
install_base: install base path, default is a temp directory
force: force install even if tests fail, default is false
only_test: don't install, just test, (used for previously installed dists),
default is false
flags: flags for building, default is { default => 1 }
branches: branches build should useSEE ALSO
AUTHORS
sunnavy <sunnavy@bestpractical.com>
LICENCE AND COPYRIGHT
Shipwright is Copyright 2007-2010 Best Practical Solutions, LLC.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.