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>, we need
127       to set the source URL first before updating.
128
129           $ shipwright relocate apache http://www.apache.org/dist/httpd/httpd-2.2.10.tar.gz
130           $ shipwright update apache
131
132       tweak manually
133
134       You may find that cpan-XML-LibXML needs libxml as a dependency, but in
135       /scripts/cpan-XML-LibXML/require.yml there's no such entry, because
136       require.yml is created automatically, filled with perl module dists, no
137       extra dependences will be set.
138
139       So we need to do it manually, e.g. use the following command to do so:
140
141           $ shipwright update cpan-XML-LibXML --add-deps libxml
142
143       build
144
145       We need to checkout the repository into some directory first, then
146       chdir there, and run: (for FS backend, there's no need to checkout,
147       just chdir to /tmp/foo ),
148
149       $ ./bin/shipwright-builder --install-base /tmp/vessel
150
151       Run ./bin/shipwright-builder --help to see more options and
152       ./bin/shipwright-builder --advanced-help to see even more options.
153
154       fiddle the vessel
155
156       We can use bin/shipwright-filter to fiddle the vessel, e.g. removing
157       pods.  Run ./bin/shipwright-filter --help to see more options
158
159       ship our vessel
160
161       We call the built source the vessel.
162
163       To ship our vessel, create an archive of the built files using an
164       archive program such as tar, e.g. by running tar czvf vessel.tar.gz
165       /tmp/vessel.
166
167       Users can use our vessel by extracting the archive to a directory and
168       then adding the following command to their shell's startup script (e.g.
169       for bash users, edit /home/user/.bashrc on most systems): source
170       /base/path/tools/etc/shipwright-source-bash (for bash users). A source
171       script is also provided for the tcsh shell.
172
173       Here is a sourcing example:
174
175         source /home/user/myapp/tools/shipwright-source-bash /home/user/myapp
176
177       This example assumes the myapp vessel was extracted to
178       /home/user/myapp.
179
180       After sourcing this script, users will be able to run binaries and load
181       perl modules from our vessel as with normal installed programs, though
182       they will need to start a new shell or re-run their startup script.
183
184       ship shipyard
185
186       If you want to ship a shipyard instead of the vessel, you can just tar
187       your shipyard( i.e. "/tmp/foo" ) and ship it, though Shipwright
188       supplies a convenient way too:
189
190       Let's chdir to our shipyard first, then run: $ ./bin/shipwright-utility
191       --generate-tar-file /tmp/shipyard.pl
192
193       The shipyard.pl is a shipyard perl script working like "shipwright-
194       builder" but it's self contained, so you can build a vessel with
195       shipyard.pl like this:
196
197       $ perl /tmp/shipyard.pl --install-base /tmp/vessel
198

SEE ALSO

200       Shipwright, Shipwright::Manual
201

AUTHORS

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

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