App-Staticperl
view release on metacpan or search on metacpan
staticperl mkbundle --app myexe --boot appfile
"--ignore-env"
Generates extra code to unset some environment variables before
initialising/running perl. Perl supports a lot of environment
variables that might alter execution in ways that might be
undesirablre for standalone applications, and this option
removes those known to cause trouble.
Specifically, these are removed:
"PERL_HASH_SEED_DEBUG" and "PERL_DEBUG_MSTATS" can cause
undesirable output, "PERL5OPT", "PERL_DESTRUCT_LEVEL",
"PERL_HASH_SEED" and "PERL_SIGNALS" can alter execution
significantly, and "PERL_UNICODE", "PERLIO_DEBUG" and "PERLIO"
can affect input and output.
The variables "PERL_LIB" and "PERL5_LIB" are always ignored
because the startup code used by staticperl overrides @INC in
all cases.
This option will not make your program more secure (unless you
are running with elevated privileges), but it will reduce the
surprise effect when a user has these environment variables set
and doesn't expect your standalone program to act like a perl
interpreter.
"--static"
Add "-static" to bundle.ldopts, which means a fully static (if
supported by the OS) executable will be created. This is not
immensely useful when just creating the bundle files, but is
most useful when linking a binary with the "--perl" or "--app"
options.
The default is to link the new binary dynamically (that means
all perl modules are linked statically, but all external
libraries are still referenced dynamically).
Keep in mind that Solaris doesn't support static linking at all,
and systems based on GNU libc don't really support it in a very
usable fashion either. Try uClibc if you want to create fully
statically linked executables, or try the "--staticlib" option
to link only some libraries statically.
"--staticlib" libname
When not linking fully statically, this option allows you to
link specific libraries statically. What it does is simply
replace all occurrences of "-llibname" with the GCC-specific
"-Wl,-Bstatic -llibname -Wl,-Bdynamic" option.
This will have no effect unless the library is actually linked
against, specifically, "--staticlib" will not link against the
named library unless it would be linked against anyway.
Example: link libcrypt statically into the final binary.
staticperl mkperl -MIO::AIO --staticlib crypt
# ldopts might now contain:
# -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
"--extra-cflags" string
Specifies extra compiler flags, used when compiling the bundle
file. The flags are appended to all the existing flags, so can
be sued to override settings.
"--extra-ldflags" string
Specifies extra linker flags, used when linking the bundle.
"--extra-libs" string
Extra linker flags, appended at the end when linking. The
difference to "--extra-ldflags" is that the ldflags are appended
to the flags, before the objects and libraries, and the extra
libs are added at the end.
EXTENDED GLOB PATTERNS
Some options of staticperl mkbundle expect an *extended glob pattern*.
This is neither a normal shell glob nor a regex, but something in
between. The idea has been copied from rsync, and there are the current
matching rules:
Patterns starting with / will be a anchored at the root of the library
tree.
That is, /unicore will match the unicore directory in @INC, but
nothing inside, and neither any other file or directory called
unicore anywhere else in the hierarchy.
Patterns not starting with / will be anchored at the end of the path.
That is, idna.pl will match any file called idna.pl anywhere in the
hierarchy, but not any directories of the same name.
A * matches anything within a single path component.
That is, /unicore/*.pl would match all .pl files directly inside
"/unicore", not any deeper level .pl files. Or in other words, *
will not match slashes.
A ** matches anything.
That is, /unicore/**.pl would match all .pl files under /unicore, no
matter how deeply nested they are inside subdirectories.
A ? matches a single character within a component.
That is, /Encode/??.pm matches /Encode/JP.pm, but not the
hypothetical /Encode/J/.pm, as ? does not match /.
STATICPERL CONFIGURATION AND HOOKS
During (each) startup, staticperl tries to source some shell files to
allow you to fine-tune/override configuration settings.
In them you can override shell variables, or define shell functions
("hooks") to be called at specific phases during installation. For
example, you could define a "postinstall" hook to install additional
modules from CPAN each time you start from scratch.
If the env variable $STATICPERLRC is set, then staticperl will try to
source the file named with it only. Otherwise, it tries the following
shell files in order:
/etc/staticperlrc
~/.staticperlrc
$STATICPERL/rc
generally should not be used.
CONFIGURATION VARIABLES
Variables you *should* override
"EMAIL"
The e-mail address of the person who built this binary. Has no good
default, so should be specified by you.
"CPAN"
The URL of the CPAN mirror to use (e.g.
<http://mirror.netcologne.de/cpan/>).
"EXTRA_MODULES"
Additional modules installed during staticperl install. Here you can
set which modules you want have to installed from CPAN.
Example: I really really need EV, AnyEvent, Coro and AnyEvent::AIO.
EXTRA_MODULES="EV AnyEvent Coro AnyEvent::AIO"
Note that you can also use a "postinstall" hook to achieve this, and
more.
Variables you might *want* to override
"STATICPERL"
The directory where staticperl stores all its files (default:
~/.staticperl).
"DLCACHE"
The path to a directory (will be created if it doesn't exist) where
downloaded perl sources are being cached, to avoid downloading them
again. The default is empty, which means there is no cache.
"PERL_VERSION"
The perl version to install - 5.12.5 is a good choice for small
builds, but 5.8.9 is also a good choice (5.8.9 is much smaller than
5.12.5), if it builds on your system.
You can also set this variable to the absolute URL of a tarball
(.tar, .tar.gz, .tar.bz2, .tar.lzma or .tar.xz), or to the absolute
path of an unpacked perl source tree, which will be copied.
The default is currently
http://stableperl.schmorp.de/dist/latest.tar.gz, i.e. the latest
stableperl release.
"PERL_MM_USE_DEFAULT", "EV_EXTRA_DEFS", ...
Usually set to 1 to make modules "less inquisitive" during their
installation. You can set (and export!) any environment variable you
want - some modules (such as Coro or EV) use environment variables
for further tweaking.
"PERL_PREFIX"
The directory where perl gets installed (default: $STATICPERL/perl),
i.e. where the bin and lib subdirectories will end up. Previous
contents will be removed on installation.
"PERL_CONFIGURE"
Additional Configure options - these are simply passed to the perl
Configure script. For example, if you wanted to enable dynamic
loading, you could pass "-Dusedl". To enable ithreads (Why would you
want that insanity? Don't! Use forks instead!) you would pass
"-Duseithreads" and so on.
More commonly, you would either activate 64 bit integer support
("-Duse64bitint"), or disable large files support (-Uuselargefiles),
to reduce filesize further.
"PERL_CC", "PERL_CCFLAGS", "PERL_OPTIMIZE", "PERL_LDFLAGS", "PERL_LIBS"
These flags are passed to perl's Configure script, and are generally
optimised for small size (at the cost of performance). Since they
also contain subtle workarounds around various build issues,
changing these usually requires understanding their default values -
best look at the top of the staticperl script for more info on
these, and use a ~/.staticperlrc to override them.
Most of the variables override (or modify) the corresponding
Configure variable, except "PERL_CCFLAGS", which gets appended.
The default for "PERL_OPTIMIZE" is "-Os" (assuming gcc), and for
"PERL_LIBS" is "-lm -lcrypt", which should be good for most (but not
all) systems.
For other compilers or more customised optimisation settings, you
need to adjust these, e.g. in your ~/.staticperlrc.
With gcc on x86 and amd64, you can get more space-savings by using:
-Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args
-mno-inline-stringops-dynamically -mno-align-stringops
And on x86 and pentium3 and newer (basically everything you might
ever want to run on), adding these is even better for space-savings
(use -mtune=core2 or something newer for much faster code, too):
-fomit-frame-pointer -march=pentium3 -mtune=i386
Variables you probably *do not want* to override
"MAKE"
The make command to use - default is "make".
"MKBUNDLE"
Where staticperl writes the "mkbundle" command to (default:
$STATICPERL/mkbundle).
"STATICPERL_MODULES"
Additional modules needed by "mkbundle" - should therefore not be
changed unless you know what you are doing.
OVERRIDABLE HOOKS
In addition to environment variables, it is possible to provide some
shell functions that are called at specific times. To provide your own
commands, just define the corresponding function.
The actual order in which hooks are invoked during a full install from
scratch is "preconfigure", "patchconfig", "postconfigure", "postbuild",
"postinstall".
Example: install extra modules from CPAN and from some directories at
staticperl install time.
postinstall() {
rm -rf lib/threads* # weg mit Schaden
instcpan IO::AIO EV
instsrc ~/src/AnyEvent
instsrc ~/src/XML-Sablotron-1.0100001
instcpan Anyevent::AIO AnyEvent::HTTPD
}
preconfigure
Called just before running ./Configure in the perl source directory.
Current working directory is the perl source directory.
This can be used to set any "PERL_xxx" variables, which might be
costly to compute.
patchconfig
Called after running ./Configure in the perl source directory to
create ./config.sh, but before running ./Configure -S to actually
apply the config. Current working directory is the perl source
directory.
Can be used to tailor/patch config.sh or do any other modifications.
postconfigure
Called after configuring, but before building perl. Current working
directory is the perl source directory.
postbuild
Called after building, but before installing perl. Current working
directory is the perl source directory.
I have no clue what this could be used for - tell me.
postinstall
Called after perl and any extra modules have been installed in
$PREFIX, but before setting the "installation O.K." flag.
The current working directory is $PREFIX, but maybe you should not
rely on that.
This hook is most useful to customise the installation, by deleting
files, or installing extra modules using the "instcpan" or "instsrc"
functions.
The script must return with a zero exit status, or the installation
will fail.
ANATOMY OF A BUNDLE
When not building a new perl binary, "mkbundle" will leave a number of
files in the current working directory, which can be used to embed a
perl interpreter in your program.
Intimate knowledge of perlembed and preferably some experience with
embedding perl is highly recommended.
"mkperl" (or the "--perl" option) basically does this to link the new
interpreter (it also adds a main program to bundle.):
$Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts)
bundle.h
A header file that contains the prototypes of the few symbols
( run in 1.105 second using v1.01-cache-2.11-cpan-d06a3f9ecfd )