ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/App-Staticperl/README
(Generate patch)

Comparing App-Staticperl/README (file contents):
Revision 1.1 by root, Mon Dec 6 19:33:57 2010 UTC vs.
Revision 1.2 by root, Mon Dec 6 21:12:21 2010 UTC

… …
22 staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V 22 staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V
23 staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http 23 staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http
24 # build a perl with the above modules linked in 24 # build a perl with the above modules linked in
25 25
26DESCRIPTION 26DESCRIPTION
27 This script helps you creating single-file perl interpreters, or
28 embedding a perl interpreter in your applications. Single-file means
29 that it is fully self-contained - no separate shared objects, no
30 autoload fragments, no .pm or .pl files are needed. And when linking
31 statically, you can create (or embed) a single file that contains perl
32 interpreter, libc, all the modules you need and all the libraries you
33 need.
34
35 With uClibc and upx on x86, you can create a single 500kb binary that
36 contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so
37 on. Or any other choice of modules.
38
39 The created files do not need write access to the file system (like PAR
40 does). In fact, since this script is in many ways similar to
41 PAR::Packer, here are the differences:
42
43 * The generated executables are much smaller than PAR created ones.
44
45 Shared objects and the perl binary contain a lot of extra info,
46 while the static nature of staticperl allows the linker to remove
47 all functionality and meta-info not required by the final
48 executable. Even extensions statically compiled into perl at build
49 time will only be present in the final executable when needed.
50
51 In addition, staticperl can strip perl sources much more effectively
52 than PAR.
53
54 * The generated executables start much faster.
55
56 There is no need to unpack files, or even to parse Zip archives
57 (which is slow and memory-consuming business).
58
59 * The generated executables don't need a writable filesystem.
60
61 staticperl loads all required files directly from memory. There is
62 no need to unpack files into a temporary directory.
63
64 * More control over included files.
65
66 PAR tries to be maintenance and hassle-free - it tries to include
67 more files than necessary to make sure everything works out of the
68 box. The extra files (such as the unicode database) can take
69 substantial amounts of memory and file size.
70
71 With staticperl, the burden is mostly with the developer - only
72 direct compile-time dependencies and AutoLoader are handled
73 automatically. This means the modules to include often need to be
74 tweaked manually.
75
76 * PAR works out of the box, staticperl does not.
77
78 Maintaining your own custom perl build can be a pain in the ass, and
79 while staticperl tries to make this easy, it still requires a custom
80 perl build and possibly fiddling with some modules. PAR is likely to
81 produce results faster.
82
83HOW DOES IT WORK?
84 Simple: staticperl downloads, compile and installs a perl version of
85 your choice in ~/.staticperl. You can add extra modules either by
86 letting staticperl install them for you automatically, or by using CPAN
87 and doing it interactively. This usually takes 5-10 minutes, depending
88 on the speed of your computer and your internet connection.
89
90 It is possible to do program development at this stage, too.
91
92 Afterwards, you create a list of files and modules you want to include,
93 and then either build a new perl binary (that acts just like a normal
94 perl except everything is compiled in), or you create bundle files
95 (basically C sources you can use to embed all files into your project).
96
97 This step is very fast (a few seconds if PPI is not used for stripping,
98 more seconds otherwise, as PPI is very slow), and can be tweaked and
99 repeated as often as necessary.
100
101THE STATICPERL SCRIPT
102 This module installs a script called staticperl into your perl binary
103 directory. The script is fully self-contained, and can be used without
104 perl (for example, in an uClibc chroot environment). In fact, it can be
105 extracted from the "App::Staticperl" distribution tarball as
106 bin/staticperl, without any installation.
107
108 staticperl interprets the first argument as a command to execute,
109 optionally followed by any parameters.
110
111 There are two command categories: the "phase 1" commands which deal with
112 installing perl and perl modules, and the "phase 2" commands, which deal
113 with creating binaries and bundle files.
114
115 PHASE 1 COMMANDS: INSTALLING PERL
116 The most important command is install, which does basically everything.
117 The default is to download and install perl 5.12.2 and a few modules
118 required by staticperl itself, but all this can (and should) be changed
119 - see CONFIGURATION, below.
120
121 The command
122
123 staticperl install
124
125 Is normally all you need: It installs the perl interpreter in
126 ~/.staticperl/perl. It downloads, configures, builds and installs the
127 perl interpreter if required.
128
129 Most of the following commands simply run one or more steps of this
130 sequence.
131
132 To force recompilation or reinstallation, you need to run staticperl
133 distclean first.
134
135 staticperl fetch
136 Runs only the download and unpack phase, unless this has already
137 happened.
138
139 staticperl configure
140 Configures the unpacked perl sources, potentially after downloading
141 them first.
142
143 staticperl build
144 Builds the configured perl sources, potentially after automatically
145 configuring them.
146
147 staticperl install
148 Wipes the perl installation directory (usually ~/.staticperl/perl)
149 and installs the perl distribution, potentially after building it
150 first.
151
152 staticperl cpan [args...]
153 Starts an interactive CPAN shell that you can use to install further
154 modules. Installs the perl first if necessary, but apart from that,
155 no magic is involved: you could just as well run it manually via
156 ~/.staticperl/perl/bin/cpan.
157
158 Any additional arguments are simply passed to the cpan command.
159
160 staticperl instcpan module...
161 Tries to install all the modules given and their dependencies, using
162 CPAN.
163
164 Example:
165
166 staticperl instcpan EV AnyEvent::HTTPD Coro
167
168 staticperl instsrc directory...
169 In the unlikely case that you have unpacked perl modules around and
170 want to install from these instead of from CPAN, you can do this
171 using this command by specifying all the directories with modules in
172 them that you want to have built.
173
174 staticperl clean
175 Runs make distclean in the perl source directory (and potentially
176 cleans up other intermediate files). This can be used to clean up
177 intermediate files without removing the installed perl interpreter.
178
179 staticperl distclean
180 This wipes your complete ~/.staticperl directory. Be careful with
181 this, it nukes your perl download, perl sources, perl distribution
182 and any installed modules. It is useful if you wish to start over
183 "from scratch" or when you want to uninstall staticperl.
184
185 PHASE 2 COMMANDS: BUILDING PERL BUNDLES
186 Building (linking) a new perl binary is handled by a separate script. To
187 make it easy to use staticperl from a chroot, the script is embedded
188 into staticperl, which will write it out and call for you with any
189 arguments you pass:
190
191 staticperl mkbundle mkbundle-args...
192
193 In the oh so unlikely case of something not working here, you can run
194 the script manually as well (by default it is written to
195 ~/.staticperl/mkbundle).
196
197 mkbundle is a more conventional command and expect the argument syntax
198 commonly used on UNIX clones. For example, this command builds a new
199 perl binary and includes Config.pm (for perl -V), AnyEvent::HTTPD, URI
200 and a custom httpd script (from eg/httpd in this distribution):
201
202 # first make sure we have perl and the required modules
203 staticperl instcpan AnyEvent::HTTPD
204
205 # now build the perl
206 staticperl mkperl -M'"Config_heavy.pl"' -MAnyEvent::Impl::Perl \
207 -MAnyEvent::HTTPD -MURI::http \
208 --add 'eg/httpd httpd.pm'
209
210 # finally, invoke it
211 ./perl -Mhttpd
212
213 As you can see, things are not quite as trivial: the Config module has a
214 hidden dependency which is not even a perl module (Config_heavy.pl),
215 AnyEvent needs at least one event loop backend that we have to specify
216 manually (here AnyEvent::Impl::Perl), and the URI module (required by
217 AnyEvent::HTTPD) implements various URI schemes as extra modules - since
218 AnyEvent::HTTPD only needs "http" URIs, we only need to include that
219 module. I found out about these dependencies by carefully watching any
220 error messages about missing modules...
221
222 OPTION PROCESSING
223 All options can be given as arguments on the command line (typically
224 using long (e.g. "--verbose") or short option (e.g. "-v") style). Since
225 specifying a lot of modules can make the command line very cumbersome,
226 you can put all long options into a "bundle specification file" (with or
227 without "--" prefix) and specify this bundle file instead.
228
229 For example, the command given earlier could also look like this:
230
231 staticperl mkperl httpd.bundle
232
233 And all options could be in httpd.bundle:
234
235 use "Config_heavy.pl"
236 use AnyEvent::Impl::Perl
237 use AnyEvent::HTTPD
238 use URI::http
239 add eg/httpd httpd.pm
240
241 All options that specify modules or files to be added are processed in
242 the order given on the command line (that affects the "--use" and
243 "--eval" options at the moment).
244
245 MKBUNDLE OPTIONS
246 --verbose | -v
247 Increases the verbosity level by one (the default is 1).
248
249 --quiet | -q
250 Decreases the verbosity level by one.
251
252 --strip none|pod|ppi
253 Specify the stripping method applied to reduce the file of the perl
254 sources included.
255
256 The default is "pod", which uses the Pod::Strip module to remove all
257 pod documentation, which is very fast and reduces file size a lot.
258
259 The "ppi" method uses PPI to parse and condense the perl sources.
260 This saves a lot more than just Pod::Strip, and is generally safer,
261 but is also a lot slower, so is best used for production builds.
262 Note that this method doesn't optimise for raw file size, but for
263 best compression (that means that the uncompressed file size is a
264 bit larger, but the files compress better, e.g. with upx).
265
266 Last not least, in the unlikely case where "pod" is too slow, or
267 some module gets mistreated, you can specify "none" to not mangle
268 included perl sources in any way.
269
270 --perl
271 After writing out the bundle files, try to link a new perl
272 interpreter. It will be called perl and will be left in the current
273 working directory. The bundle files will be removed.
274
275 This switch is automatically used when staticperl is invoked with
276 the "mkperl" command (instead of "mkbundle"):
277
278 # build a new ./perl with only common::sense in it - very small :)
279 staticperl mkperl -Mcommon::sense
280
281 --use module | -Mmodule
282 Include the named module and all direct dependencies. This is done
283 by "require"'ing the module in a subprocess and tracing which other
284 modules and files it actually loads. If the module uses AutoLoader,
285 then all splitfiles will be included as well.
286
287 Example: include AnyEvent and AnyEvent::Impl::Perl.
288
289 staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
290
291 Sometimes you want to load old-style "perl libraries" (.pl files),
292 or maybe other weirdly named files. To do that, you need to quote
293 the name in single or double quotes. When given on the command line,
294 you probably need to quote once more to avoid your shell
295 interpreting it. Common cases that need this are Config_heavy.pl and
296 utf8_heavy.pl.
297
298 Example: include the required files for perl -V to work in all its
299 glory (Config.pm is included automatically by this).
300
301 # bourne shell
302 staticperl mkbundle --use '"Config_heavy.pl"'
303
304 # bundle specification file
305 use "Config_heavy.pl"
306
307 The "-Mmodule" syntax is included as an alias that might be easier
308 to remember than "use". Or maybe it confuses people. Time will tell.
309 Or maybe not. Argh.
310
311 --eval "perl code" | -e "perl code"
312 Sometimes it is easier (or necessary) to specify dependencies using
313 perl code, or maybe one of the modules you use need a special use
314 statement. In that case, you can use "eval" to execute some perl
315 snippet or set some variables or whatever you need. All files
316 "require"'d or "use"'d in the script are included in the final
317 bundle.
318
319 Keep in mind that mkbundle will only "require" the modules named by
320 the "--use" option, so do not expect the symbols from modules you
321 "--use"'d earlier on the command line to be available.
322
323 Example: force AnyEvent to detect a backend and therefore include it
324 in the final bundle.
325
326 staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
327
328 # or like this
329 staticperl mkbundle -MAnyEvent --eval 'use AnyEvent; AnyEvent::detect'
330
331 Example: use a separate "bootstrap" script that "use"'s lots of
332 modules and include this in the final bundle, to be executed
333 automatically.
334
335 staticperl mkbundle --eval 'do "bootstrap"' --boot bootstrap
336
337 --boot filename
338 Include the given file in the bundle and arrange for it to be
339 executed (using a "require") before anything else when the new perl
340 is initialised. This can be used to modify @INC or anything else
341 before the perl interpreter executes scripts given on the command
342 line (or via "-e"). This works even in an embedded interpreter.
343
344 --add "file" | --add "file alias"
345 Adds the given (perl) file into the bundle (and optionally call it
346 "alias"). This is useful to include any custom files into the
347 bundle.
348
349 Example: embed the file httpd as httpd.pm when creating the bundle.
350
351 staticperl mkperl --add "httpd httpd.pm"
352
353 It is also a great way to add any custom modules:
354
355 # specification file
356 add file1 myfiles/file1
357 add file2 myfiles/file2
358 add file3 myfiles/file3
359
360 --static
361 When "--perl" is also given, link statically instead of dynamically.
362 The default is to link the new perl interpreter fully dynamic (that
363 means all perl modules are linked statically, but all external
364 libraries are still referenced dynamically).
365
366 Keep in mind that Solaris doesn't support static linking at all, and
367 systems based on GNU libc don't really support it in a usable
368 fashion either. Try uClibc if you want to create fully statically
369 linked executables, or try the "--staticlibs" option to link only
370 some libraries statically.
371
372 any other argument
373 Any other argument is interpreted as a bundle specification file,
374 which supports most long options (without extra quoting), one option
375 per line.
376
377 STATCPERL CONFIGURATION AND HOOKS
378 During (each) startup, staticperl tries to source the following shell
379 files in order:
380
381 /etc/staticperlrc
382 ~/.staticperlrc
383 $STATICPERL/rc
384
385 They can be used to override shell variables, or define functions to be
386 called at specific phases.
387
388 Note that the last file is erased during staticperl distclean, so
389 generally should not be used.
390
391 CONFIGURATION VARIABLES
392 Variables you *should* override
393 "EMAIL"
394 The e-mail address of the person who built this binary. Has no good
395 default, so should be specified by you.
396
397 Variables you *might want* to override
398 "PERLVER"
399 The perl version to install - default is currently 5.12.2, but 5.8.9
400 is also a good choice (5.8.9 is much smaller than 5.12.2, while
401 5.10.1 is about as big as 5.12.2).
402
403 "CPAN"
404 The URL of the CPAN mirror to use (e.g.
405 <http://mirror.netcologne.de/cpan/>).
406
407 "PERL_CPPFLAGS", "PERL_OPTIMIZE", "PERL_LDFLAGS", "PERL_LIBS"
408 These flags are passed to perl's Configure script, and are generally
409 optimised for small size (at the cost of performance). Since they
410 also contain subtle workarounds around various build issues,
411 changing these usually requires understanding their default values -
412 best look at the top of the staticperl script for more info on
413 these.
414
415 "STATICPERL"
416 The directory where staticperl stores all its files (default:
417 ~/.staticperl).
418
419 "PREFIX"
420 The prefix where perl gets installed (default: $STATICPERL/perl),
421 i.e. where the bin and lib subdirectories will end up.
422
423 "PERL_MM_USE_DEFAULT", "EV_EXTRA_DEFS", others
424 Usually set to 1 to make modules "less inquisitive" during their
425 installation, you can set any environment variable you want - some
426 modules (such as Coro or EV) use environment variables for further
427 tweaking.
428
429 "EXTRA_MODULES"
430 Additional modules installed during staticperl install. Here you can
431 set which modules you want have to installed from CPAN.
432
433 Example: I really really need EV, AnyEvent, Coro and IO::AIO.
434
435 EXTRA_MODULES="EV AnyEvent Coro IO::AIO"
436
437 Note that you can also use a "postinstall" hook to achieve this, and
438 more.
439
440 Variables you *probably do not want* to override
441 "MKBUNDLE"
442 Where staticperl writes the "mkbundle" command to (default:
443 $STATICPERL/mkbundle).
444
445 "STATICPERL_MODULES"
446 Additional modules needed by "mkbundle" - should therefore not be
447 changed unless you know what you are doing.
448
449 OVERRIDABLE HOOKS
450 In addition to environment variables, it is possible to provide some
451 shell functions that are called at specific times. To provide your own
452 commands, just define the corresponding function.
453
454 Example: install extra modules from CPAN and from some directories at
455 staticperl install time.
456
457 postinstall() {
458 rm -rf lib/threads.* # weg mit Schaden
459 instcpan IO::AIO EV
460 instsrc ~/src/AnyEvent
461 instsrc ~/src/XML-Sablotron-1.0100001
462 instcpan AnyEvent::HTTPD
463 }
464
465 postconfigure
466 Called after configuring, but before building perl. Current working
467 directory is the perl source directory.
468
469 Could be used to tailor/patch config.sh (followed by ./Configure -S)
470 or do any other modifications.
471
472 postbuild
473 Called after building, but before installing perl. Current working
474 directory is the perl source directory.
475
476 I have no clue what this could be used for - tell me.
477
478 postinstall
479 Called after perl and any extra modules have been installed in
480 $PREFIX, but before setting the "installation O.K." flag.
481
482 The current working directory is $PREFIX, but maybe you should not
483 rely on that.
484
485 This hook is most useful to customise the installation, by deleting
486 files, or installing extra modules using the "instcpan" or "instsrc"
487 functions.
488
489 The script must return with a zero exit status, or the installation
490 will fail.
491
27AUTHOR 492AUTHOR
28 Marc Lehmann <schmorp@schmorp.de> 493 Marc Lehmann <schmorp@schmorp.de>
29 http://software.schmorp.de/pkg/staticperl.html 494 http://software.schmorp.de/pkg/staticperl.html
30 495

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines