1Shipwright::Manual::TutUosreiralC(o3n)tributed Perl DocuSmheinptwartiigohnt::Manual::Tutorial(3)
2
3
4

NAME

6       Shipwright::Manual::Tutorial - Shipwright tutorial
7

DESCRIPTION

9       In this tutorial, we'll create a vessel to demonstrate the basic
10       operation of Shipwright.
11

TUTORIAL

13   Introduction
14       Shipwright ships with command line tool shipwright which allows you to
15       manage shipyard: create, import sources, "update", and so on.
16
17       Let's start from a new shipyard.
18
19       Create a new shipyard
20
21       shipyard - the place where all source code lives.  Shipwright supports
22       several backends: SVK, SVN, Git and plain file system.  We'll use FS in
23       this tutorial.
24
25       Let's create a new shipyard:
26
27           $ shipwright create -r fs:/tmp/foo
28
29       To avoid typing -r fs:/tmp/foo all the time you can use
30       "SHIPWRIGHT_SHIPYARD" environment variable.
31
32           $ export SHIPWRIGHT_SHIPYARD="fs:/tmp/foo"
33
34       From now on we don't need the "-r ..." for the session.
35
36       Import sources
37
38       Our shipyard is worthless if it doesn't contain any source, let's
39       import some.
40
41       Shipwright supports various types of sources.  Here are some examples:
42
43       compressed file
44               file:/tmp/foo.tar.gz
45               file:/home/ross/dinosaur-0.01.tar.bz2
46
47       plain directory
48               dir:/tmp/foo
49               directory:/home/ross/dinosaur-0.01
50
51       HTTP
52               http://apache.mirror.phpchina.com/httpd/httpd-2.2.9.tar.gz
53               http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/authors/id/C/CL/CLKAO/SVK-v2.0.2.tar.gz
54
55       FTP
56               ftp://ftp.gnupg.org/gcrypt/gnupg/gnupg-1.4.9.tar.bz2
57               ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/authors/id/C/CL/CLKAO/SVK-v2.0.2.tar.gz
58
59       SVK
60               svk:/test/foo
61
62       SVN
63               svn:file:///tmp/repo/foo
64               svn:http://svn.example.com/foo
65
66       Git
67               git:file:///tmp/foo.git
68
69       CPAN
70               cpan:Jifty
71               cpan:Module::Install
72
73       shipyard
74               shipyard:fs:/tmp/shipyard/foo
75               shipyard:fs:/tmp/shipyard/bar
76
77           fs:/tmp/shipyard is another shipyard, 'foo' or 'bar' is the source
78           name we want to import.
79
80       We'll import apache 2.2.9, perl 5.10, mod_perl 2.0, libxml and
81       XML::LibXML in this tutorial one by one.
82
83           $ shipwright import http://www.apache.org/dist/httpd/httpd-2.2.9.tar.gz --name apache
84           $ shipwright import http://www.cpan.org/authors/id/R/RG/RGARCIA/perl-5.10.0.tar.gz
85           $ shipwright import http://perl.apache.org/dist/mod_perl-2.0-current.tar.gz --name mod_perl --no-follow
86           ( use --no-follow is because run Makefile.PL will hung if we don't have
87             apache installed )
88           $ shipwright import ftp://xmlsoft.org/libxml2/libxml2-2.6.32.tar.gz --name libxml
89           $ shipwright import cpan:XML::LibXML
90
91       Run shipwright help import to see more options.
92
93       As a side note, if we were importing from a source that doesn't use a
94       build mechanism that Shipwright can automatically create a set of build
95       instructions for (currently autoconf, ExtUtils::MakeMaker,
96       Module::Install, and Module::Build), we would now need to edit
97       scripts/SOURCE_NAME/build to tell Shipwright how to build that source.
98
99       For our tutorial, e.g. perl 5.10, Shipwright doesn't know about the
100       peculiarities of how to build perl, so we need to edit the build file:
101
102         configure: ./Configure -des -Dprefix=%%INSTALL_BASE%%
103         test: %%MAKE%% test
104         install: %%MAKE%% install
105
106       For more information on build scripts, see
107       Shipwright::Manual::CustomizeBuild.
108
109       update
110
111       For dists with CPAN, SVK, SVN, Git and shipyard types, we can simply
112       use the update command to update:
113
114           $ shipwright update cpan-XML-LibXML
115           (yeah, that's right, cpan:XML::LibXML will be named cpan-XML-LibXML)
116
117       We can also specify the version we want to update to with --version
118       argument:
119
120           $ shipwright update cpan-XML-LibXML --version 1.60
121
122       For other types, Shipwright can't guess the latest version, so we have
123       to tell Shipwright where it is using the relocate command.
124
125       e.g. apache 2.2.10 is released one day, with download link
126       http://apache.mirror.phpchina.com/httpd/httpd-2.2.10.tar.gz
127       <http://apache.mirror.phpchina.com/httpd/httpd-2.2.10.tar.gz>, we need
128       to set the source URL first before updating.
129
130           $ shipwright relocate apache http://www.apache.org/dist/httpd/httpd-2.2.10.tar.gz
131           $ shipwright update apache
132
133       tweak manually
134
135       You may find that cpan-XML-LibXML needs libxml as a dependency, but in
136       /scripts/cpan-XML-LibXML/require.yml there's no such entry, because
137       require.yml is created automatically, filled with perl module dists, no
138       extra dependences will be set.
139
140       So we need to do it manually, e.g. use the following command to do so:
141
142           $ shipwright update apache --add-deps libxml
143
144       build
145
146       We need to checkout the repository into some directory first, then
147       chdir there, and run: (for FS backend, there's no need to checkout,
148       just chdir to /tmp/foo ),
149
150       $ ./bin/shipwright-builder --install-base /tmp/vessel
151
152       Run ./bin/shipwright-builder --help to see more options and
153       ./bin/shipwright-builder --advanced-help to see even more options.
154
155       fiddle the vessel
156
157       We can use bin/shipwright-filter to fiddle the vessel, e.g. removing
158       pods.  Run ./bin/shipwright-filter --help to see more options
159
160       ship our vessel
161
162       We call the built source the vessel.
163
164       To ship our vessel, create an archive of the built files using an
165       archive program such as tar, e.g. by running tar czvf vessel.tar.gz
166       /tmp/vessel.
167
168       Users can use our vessel by extracting the archive to a directory and
169       then adding the following command to their shell's startup script (e.g.
170       for bash users, edit /home/user/.bashrc on most systems): source
171       /base/path/tools/etc/shipwright-source-bash (for bash users). A source
172       script is also provided for the tcsh shell.
173
174       Here is a sourcing example:
175
176         source /home/user/myapp/tools/shipwright-source-bash /home/user/myapp
177
178       This example assumes the myapp vessel was extracted to
179       /home/user/myapp.
180
181       After sourcing this script, users will be able to run binaries and load
182       perl modules from our vessel as with normal installed programs, though
183       they will need to start a new shell or re-run their startup script.
184
185       ship shipyard
186
187       If you want to ship a shipyard instead of the vessel, you can just tar
188       your shipyard( i.e. "/tmp/foo" ) and ship it, though Shipwright
189       supplies a convenient way too:
190
191       Let's chdir to our shipyard first, then run: $ ./bin/shipwright-utility
192       --generate-tar-file /tmp/shipyard.pl
193
194       The shipyard.pl is a shipyard perl script working like "shipwright-
195       builder" but it's self contained, so you can build a vessel with
196       shipyard.pl like this:
197
198       $ perl /tmp/shipyard.pl --install-base /tmp/vessel
199

SEE ALSO

201       Shipwright, Shipwright::Manual
202

AUTHORS

204       sunnavy  "<sunnavy@bestpractical.com>"
205

207       Shipwright is Copyright 2007-2010 Best Practical Solutions, LLC.
208
209       This program is free software; you can redistribute it and/or modify it
210       under the same terms as Perl itself.
211
212
213
214perl v5.12.3                      2011-01-21   Shipwright::Manual::Tutorial(3)
Impressum