1 |
root |
1.1 |
=head1 NAME |
2 |
|
|
|
3 |
|
|
staticperl - perl, libc, 50 modules all in one 500kb file |
4 |
|
|
|
5 |
|
|
=head1 SYNOPSIS |
6 |
|
|
|
7 |
|
|
staticperl help # print the embedded documentation |
8 |
|
|
staticperl fetch # fetch and unpack perl sources |
9 |
|
|
staticperl configure # fetch and then configure perl |
10 |
|
|
staticperl build # configure and then build perl |
11 |
|
|
staticperl install # build and then install perl |
12 |
|
|
staticperl clean # clean most intermediate files (restart at configure) |
13 |
|
|
staticperl distclean # delete everything installed by this script |
14 |
|
|
staticperl cpan # invoke CPAN shell |
15 |
|
|
staticperl instmod path... # install unpacked modules |
16 |
|
|
staticperl instcpan modulename... # install modules from CPAN |
17 |
|
|
staticperl mkbundle <bundle-args...> # see documentation |
18 |
|
|
staticperl mkperl <bundle-args...> # see documentation |
19 |
|
|
|
20 |
|
|
Typical Examples: |
21 |
|
|
|
22 |
|
|
staticperl install # fetch, configure, build and install perl |
23 |
|
|
staticperl cpan # run interactive cpan shell |
24 |
|
|
staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V |
25 |
|
|
staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http |
26 |
|
|
# build a perl with the above modules linked in |
27 |
|
|
|
28 |
|
|
=head1 DESCRIPTION |
29 |
|
|
|
30 |
|
|
This script helps you creating single-file perl interpreters, or embedding |
31 |
|
|
a pelr interpreter in your apps. Single-file means that it is fully |
32 |
|
|
self-contained - no separate shared objects, no autoload fragments, no .pm |
33 |
|
|
or .pl files are needed. And when linking statically, you can create (or |
34 |
|
|
embed) a single file that contains perl interpreter, libc, all the modules |
35 |
|
|
you need and all the libraries you need. |
36 |
|
|
|
37 |
|
|
With uclibc and upx on x86, you can create a single 500kb binary that |
38 |
|
|
contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so |
39 |
|
|
on. Or any other choice of modules. |
40 |
|
|
|
41 |
|
|
The created files do not need write access to the filesystem (like PAR |
42 |
|
|
does). In fact, since this script is in many ways similar to PAR::Packer, |
43 |
|
|
here are the differences: |
44 |
|
|
|
45 |
|
|
=over 4 |
46 |
|
|
|
47 |
|
|
=item * The generated executables are much smaller than PAR created ones. |
48 |
|
|
|
49 |
|
|
Shared objects and the perl binary contain a lot of extra info, while |
50 |
|
|
the static nature of F<staticperl> allows the linker to remove all |
51 |
|
|
functionality and meta-info not required by the final executable. Even |
52 |
|
|
extensions statically compiled into perl at build time will only be |
53 |
|
|
present in the final executable when needed. |
54 |
|
|
|
55 |
|
|
In addition, F<staticperl> can strip perl sources much more effectively |
56 |
|
|
than PAR. |
57 |
|
|
|
58 |
|
|
=item * The generated executables start much faster. |
59 |
|
|
|
60 |
|
|
There is no need to unpack files, or even to parse Zip archives (which is |
61 |
|
|
slow and memory-consuming business). |
62 |
|
|
|
63 |
|
|
=item * The generated executables don't need a writable filesystem. |
64 |
|
|
|
65 |
|
|
F<staticperl> loads all required files directly from memory. There is no |
66 |
|
|
need to unpack files into a temporary directory. |
67 |
|
|
|
68 |
|
|
=item * More control over included files. |
69 |
|
|
|
70 |
|
|
PAR tries to be maintainance and hassle-free - it tries to include more files |
71 |
|
|
than necessary to make sure everything works out of the box. The extra files |
72 |
|
|
(such as the unicode database) can take substantial amounts of memory and filesize. |
73 |
|
|
|
74 |
|
|
With F<staticperl>, the burden is mostly with the developer - only direct |
75 |
|
|
compile-time dependencies and L<AutoLoader> are handled automatically. |
76 |
|
|
This means the modules to include often need to be tweaked manually. |
77 |
|
|
|
78 |
|
|
=item * PAR works out of the box, F<staticperl> does not. |
79 |
|
|
|
80 |
|
|
Maintaining your own custom perl build can be a pain in the ass, and while |
81 |
|
|
F<staticperl> tries to make this easy, it still requires a custom perl |
82 |
|
|
build and possibly fiddling with some modules. PAR is likely to produce |
83 |
|
|
results faster. |
84 |
|
|
|
85 |
|
|
=back |
86 |
|
|
|
87 |
|
|
=head1 HOW DOES IT WORK? |
88 |
|
|
|
89 |
|
|
Simple: F<staticperl> downloads, compile and installs a perl version of |
90 |
|
|
your choice in F<~/.staticperl>. You can add extra modules either by |
91 |
|
|
letting F<staticperl> install them for you automatically, or by using CPAN |
92 |
|
|
and doing it interactively. This usually takes 5-10 minutes, depending on |
93 |
|
|
the speed of your computer and your internet conenction. |
94 |
|
|
|
95 |
|
|
It is possible to do program development at this stage, too. |
96 |
|
|
|
97 |
|
|
Afterwards, you create a list of files and modules you want to include, |
98 |
|
|
and then either build a new perl binary (that acts just like a normla perl |
99 |
|
|
except everything is compiled in), or you create bundle files (basically C |
100 |
|
|
sources you can use to embed all files into your project). |
101 |
|
|
|
102 |
|
|
This step is very fast (a few seconds if PPI is not used for stripping, |
103 |
|
|
more seconds otherwise, as PPI is very slow), and can be tweaked and |
104 |
|
|
repeated as often as necessary. |
105 |
|
|
|
106 |
|
|
=head1 THE F<STATICPERL> SCRIPT |
107 |
|
|
|
108 |
|
|
This module installs a script called F<staticperl> into your perl |
109 |
|
|
binary directory. The script is fully self-contained, and can be used |
110 |
|
|
without perl (for example, in an uClibc chroot environment). In fact, |
111 |
|
|
it can be extracted from the C<App::Staticperl> distribution tarball as |
112 |
|
|
F<bin/staticperl>, without any installation. |
113 |
|
|
|
114 |
|
|
F<staticperl> interprets the first argument as a command to execute, |
115 |
|
|
optionally followed by any parameters. |
116 |
|
|
|
117 |
|
|
There are two command categories: the "phase 1" commands which deal with |
118 |
|
|
installing perl and perl modules, and the "phase 2" commands, which deal |
119 |
|
|
with creating binaries and bundle files. |
120 |
|
|
|
121 |
|
|
=head2 PHASE 1 COMMANDS: INSTALLING PERL |
122 |
|
|
|
123 |
|
|
The most important command is F<install>, which does basically |
124 |
|
|
everything. The default is to download and install perl 5.12.2 and a few |
125 |
|
|
modules required by F<staticperl> itself, but all this can (and should) be |
126 |
|
|
changed - see L<CONFIGURATION>, below. |
127 |
|
|
|
128 |
|
|
The command |
129 |
|
|
|
130 |
|
|
staticperl install |
131 |
|
|
|
132 |
|
|
Is normally all you need: It installs the perl interpreter in |
133 |
|
|
F<~/.staticperl/perl>. It downloads, configures, builds and installs the |
134 |
|
|
perl interpreter if required. |
135 |
|
|
|
136 |
|
|
Most of the following commands simply run one or more steps of this |
137 |
|
|
sequence. |
138 |
|
|
|
139 |
|
|
To force recompilation or reinstalaltion, you need to run F<staticperl |
140 |
|
|
distclean> first. |
141 |
|
|
|
142 |
|
|
=over 4 |
143 |
|
|
|
144 |
|
|
=item F<staticperl fetch> |
145 |
|
|
|
146 |
|
|
Runs only the download and unpack phase, unless this has already happened. |
147 |
|
|
|
148 |
|
|
=item F<staticperl configure> |
149 |
|
|
|
150 |
|
|
Configures the unpacked perl sources, potentially after downloading them first. |
151 |
|
|
|
152 |
|
|
=item F<staticperl build> |
153 |
|
|
|
154 |
|
|
Builds the configured perl sources, potentially after automatically |
155 |
|
|
configuring them. |
156 |
|
|
|
157 |
|
|
=item F<staticperl install> |
158 |
|
|
|
159 |
|
|
Wipes the perl installation directory (usually F<~/.staticperl/perl>) and installs |
160 |
|
|
the perl distribution, potentially aftering building it first. |
161 |
|
|
|
162 |
|
|
=item F<staticperl cpan> [args...] |
163 |
|
|
|
164 |
|
|
Starts an interactive CPAN shell that you cna use to install further |
165 |
|
|
modules. Installs the perl first if neccessary, but apart from that, |
166 |
|
|
no magic is involved: you could just as well run it manually via |
167 |
|
|
F<~/.staticperl/perl/bin/cpan>. |
168 |
|
|
|
169 |
|
|
Any additional arguments are simply passed to the F<cpan> command. |
170 |
|
|
|
171 |
|
|
=item F<staticperl instcpan> module... |
172 |
|
|
|
173 |
|
|
Tries to install all the modules given and their dependencies, using CPAN. |
174 |
|
|
|
175 |
|
|
Example: |
176 |
|
|
|
177 |
|
|
staticperl instcpan EV AnyEvent::HTTPD Coro |
178 |
|
|
|
179 |
|
|
=item F<staticperl instsrc> directory... |
180 |
|
|
|
181 |
|
|
In the unlikely case that you have unpacked perl modules around and want |
182 |
|
|
to install from these instead of from CPAN, you cna do this using this |
183 |
|
|
command by specifying all the directories with modules in them that you |
184 |
|
|
want to have built. |
185 |
|
|
|
186 |
|
|
=item F<staticperl clean> |
187 |
|
|
|
188 |
|
|
Runs F<make distclean> in the perl source directory (and potentially |
189 |
|
|
cleans up other intermediate files). This can be used to clean up |
190 |
|
|
intermediate files without removing the installed perl interpreter. |
191 |
|
|
|
192 |
|
|
=item F<staticperl distclean> |
193 |
|
|
|
194 |
|
|
This wipes your complete F<~/.staticperl> directory. Be careful with this, |
195 |
|
|
it nukes your perl download, perl sources, perl distribution and any |
196 |
|
|
installed modules. It is useful if you wish to start over "from scratch" |
197 |
|
|
or when you want to uninstall F<staticperl>. |
198 |
|
|
|
199 |
|
|
=back |
200 |
|
|
|
201 |
|
|
=head2 PHASE 2 COMMANDS: BUILDING PERL BUNDLES |
202 |
|
|
|
203 |
|
|
Building (linking) a new F<perl> binary is handled by a separate |
204 |
|
|
script. To make it easy to use F<staticperl> from a F<chroot>, the script |
205 |
|
|
is embedded into F<staticperl>, which will write it out and call for you |
206 |
|
|
with any arguments you pass: |
207 |
|
|
|
208 |
|
|
staticperl mkbundle mkbundle-args... |
209 |
|
|
|
210 |
|
|
In the oh so unlikely case of something not working here, you |
211 |
|
|
cna run the script manually as well (by default it is written to |
212 |
|
|
F<~/.staticperl/mkbundle>). |
213 |
|
|
|
214 |
|
|
F<mkbundle> is a more conventional command and expect the argument |
215 |
|
|
syntax commonly used on unix clones. For example, this command builds |
216 |
|
|
a new F<perl> binary and includes F<Config.pm> (for F<perl -V>), |
217 |
|
|
F<AnyEvent::HTTPD>, F<URI> and a custom F<httpd> script (from F<eg/httpd> |
218 |
|
|
in this distribution): |
219 |
|
|
|
220 |
|
|
# first make sure we have perl and the required modules |
221 |
|
|
staticperl instcpan AnyEvent::HTTPD |
222 |
|
|
|
223 |
|
|
# now build the perl |
224 |
|
|
staticperl mkperl -M'"Config_heavy.pl"' -MAnyEvent::Impl::Perl \ |
225 |
|
|
-MAnyEvent::HTTPD -MURI::http \ |
226 |
|
|
--add 'eg/httpd httpd.pm' |
227 |
|
|
|
228 |
|
|
# finally, invoke it |
229 |
|
|
./perl -Mhttpd |
230 |
|
|
|
231 |
|
|
As you can see, things are not quite as trivial: the L<Config> module has |
232 |
|
|
a hidden dependency which is not even a perl module (F<Config_heavy.pl>), |
233 |
|
|
L<AnyEvent> needs at least one event loop backend that we have to |
234 |
|
|
specifymanually (here L<AnyEvent::Impl::Perl>), and the F<URI> module |
235 |
|
|
(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra |
236 |
|
|
modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need |
237 |
|
|
to include that module. |
238 |
|
|
|
239 |
|
|
=head3 OPTION PROCESSING |
240 |
|
|
|
241 |
|
|
All options can be given as arguments on the commandline (typically using |
242 |
|
|
long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since |
243 |
|
|
specifying a lot of modules can make the commandlien very cumbersome, |
244 |
|
|
you can put all long options into a "bundle specification file" (with or |
245 |
|
|
without C<--> prefix) and specify this bundle file instead. |
246 |
|
|
|
247 |
|
|
For example, the command given earlier could also look like this: |
248 |
|
|
|
249 |
|
|
staticperl mkperl httpd.bundle |
250 |
|
|
|
251 |
|
|
And all options could be in F<httpd.bundle>: |
252 |
|
|
|
253 |
|
|
use "Config_heavy.pl" |
254 |
|
|
use AnyEvent::Impl::Perl |
255 |
|
|
use AnyEvent::HTTPD |
256 |
|
|
use URI::http |
257 |
|
|
add eg/httpd httpd.pm |
258 |
|
|
|
259 |
|
|
=head3 MKBUNDLE OPTIONS |
260 |
|
|
|
261 |
|
|
=over 4 |
262 |
|
|
|
263 |
|
|
"strip=s" => \$STRIP, |
264 |
|
|
"verbose|v" => sub { ++$VERBOSE }, |
265 |
|
|
"quiet|q" => sub { --$VERBOSE }, |
266 |
|
|
"perl" => \$PERL, |
267 |
|
|
"eval=s" => sub { trace_eval $_[1] }, |
268 |
|
|
"use|M=s" => sub { trace_module $_[1] }, |
269 |
|
|
"boot=s" => sub { cmd_boot $_[1] }, |
270 |
|
|
"add=s" => sub { cmd_add $_[1] }, |
271 |
|
|
"static" => sub { $STATIC = 1 }, |
272 |
|
|
"<>" => sub { cmd_file $_[1] }, |
273 |
|
|
|
274 |
|
|
=back |
275 |
|
|
|
276 |
|
|
=head2 F<STATCPERL> CONFIGURATION AND HOOKS |
277 |
|
|
|
278 |
|
|
#TODO |
279 |
|
|
|
280 |
|
|
=head1 AUTHOR |
281 |
|
|
|
282 |
|
|
Marc Lehmann <schmorp@schmorp.de> |
283 |
|
|
http://software.schmorp.de/pkg/staticperl.html |
284 |
|
|
|
285 |
|
|
|
286 |
|
|
|