Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pp(3)		      User Contributed Perl Documentation		 pp(3)

NAME
       pp - PAR	Packager

SYNOPSIS
       pp [A -ABCEFILMPTSVXacdefghilmnoprsuvxzA	]
       [A parfileA |A scriptfileA ]...

EXAMPLES
       Note: When running on Microsoft Windows,	the a.out below	will be
       replaced	by a.exe instead.

	   % pp	hello.pl	       # Pack 'hello.pl' into executable 'a.out'
	   % pp	-o hello hello.pl      # Pack 'hello.pl' into executable 'hello'
				       # (or 'hello.exe' on Win32)

	   % pp	-o foo foo.pl bar.pl   # Pack 'foo.pl' and 'bar.pl' into 'foo'
	   % ./foo		       # Run 'foo.pl' inside 'foo'
	   % mv	foo bar; ./bar	       # Run 'bar.pl' inside 'foo'
	   % mv	bar baz; ./baz	       # Error:	Can't open perl	script "baz"

	   % pp	-p file		       # Creates a PAR file, 'a.par'
	   % pp	-o hello a.par	       # Pack 'a.par' to executable 'hello'
	   % pp	-S -o hello file       # Combine the two steps above

	   % pp	-p -o out.par file     # Creates 'out.par' from	'file'
	   % pp	-B -p -o out.par file  # same as above,	but bundles core modules
				       # and removes any local paths from @INC
	   % pp	-P -o out.pl file      # Creates 'out.pl' from 'file'
	   % pp	-B -p -o out.pl	file   # same as above,	but bundles core modules
				       # and removes any local paths from @INC
				       # (-B is	assumed	when making executables)

	   % pp	-e "print 123"	       # Pack a	one-liner into 'a.out'
	   % pp	-p -e "print 123"      # Creates a PAR file 'a.par'
	   % pp	-P -e "print 123"      # Creates a perl	script 'a.pl'

	   % pp	-c hello	       # Check dependencies from "perl -c hello"
	   % pp	-x hello	       # Check dependencies from "perl hello"
	   % pp	-n -x hello	       # same as above,	but skips static scanning

	   % pp	-I /foo	hello	       # Extra include paths
	   % pp	-M Foo::Bar hello      # Extra modules in the include path
	   % pp	-M abbrev.pl hello     # Extra libraries in the	include	path
	   % pp	-X Foo::Bar hello      # Exclude modules
	   % pp	-a data.txt hello      # Additional data files

	   % pp	-r hello	       # Pack 'hello' into 'a.out', runs 'a.out'
	   % pp	-r hello a b c	       # Pack 'hello' into 'a.out', runs 'a.out'
				       # with arguments	'a b c'

	   % pp	hello --log=c	       # Pack 'hello' into 'a.out', logs
				       # messages into 'c'

	   # Pack 'hello' into a console-less 'out.exe'	(Win32 only)
	   % pp	--gui -o out.exe hello

	   % pp	@file hello.pl	       # Pack 'hello.pl' but read _additional_
				       # options from file 'file'

DESCRIPTION
       pp creates standalone executables from Perl programs, using the
       compressed packager provided by PAR, and	dependency detection
       heuristics offered by Module::ScanDeps.	Source files are compressed
       verbatim	without	compilation.

       You may think of	pp as "perlcc that works without hassle". :-)

       A GUI interface is also available as the	tkpp command.

       It does not provide the compilation-step	acceleration provided by
       perlcc (however,	see -f below for byte-compiled,	source-hiding
       techniques), but	makes up for it	with better reliability, smaller
       executable size,	and full retrieval of original source code.

       When a single input program is specified, the resulting executable will
       behave identically as that program.  However, when multiple programs
       are packaged, the produced executable will run the one that has the
       same basename as	$0 (i.e. the filename used to invoke it).  If nothing
       matches,	it dies	with the error "Can't open perl	script "$0"".

OPTIONS
       Options are available in	a short	form and a long	form.  For example,
       the three lines below are all equivalent:

	   % pp	-o output.exe input.pl
	   % pp	--output output.exe input.pl
	   % pp	--output=output.exe input.pl

       Since the command lines can become sufficiently long to reach the
       limits imposed by some shells, it is possible to	have pp	read some of
       its options from	one or more text files.	The basic usage	is to just
       include an argument starting with an 'at' (@) sigil. This argument will
       be interpreted as a file	to read	options	from. Mixing ordinary options
       and @file options is possible. This is implemented using	the
       Getopt::ArgvFile	module,	so read	its documentation for advanced usage.

       -a, --addfile=FILE|DIR
	   Add an extra	file into the package.	If the file is a directory,
	   recursively add all files inside that directory, with links turned
	   into	actual files.

	   By default, files are placed	under "/" inside the package with
	   their original names.  You may override this	by appending the
	   target filename after a ";",	like this:

	       % pp -a "old_filename.txt;new_filename.txt"
	       % pp -a "old_dirname;new_dirname"

	   You may specify "-a"	multiple times.

       -A, --addlist=FILE
	   Read	a list of file/directory names from FILE, adding them into the
	   package.  Each line in FILE is taken	as an argument to -a above.

	   You may specify "-A"	multiple times.

       -B, --bundle
	   Bundle core modules in the resulting	package.  This option is
	   enabled by default, except when "-p"	or "-P"	is specified.

	   Since PAR version 0.953, this also strips any local paths from the
	   list	of module search paths @INC before running the contained
	   script.

       -C, --clean
	   Clean up temporary files extracted from the application at runtime.
	   By default, these files are cached in the temporary directory; this
	   allows the program to start up faster next time.

       -c, --compile
	   Run "perl -c	inputfile" to determine	additional run-time
	   dependencies.

       -cd, --cachedeps=FILE
	   Use FILE to cache detected dependencies. Creates FILE unless
	   present. This will speed up the scanning process on subsequent
	   runs.

       -d, --dependent
	   Reduce the executable size by not including a copy of perl
	   interpreter.	 Executables built this	way will need a	separate
	   perl5x.dll or libperl.so to function	correctly.  This option	is
	   only	available if perl is built as a	shared library.

       -e, --eval=STRING
	   Package a one-liner,	much the same as "perl -e '...'"

       -E, --evalfeature=STRING
	   Behaves just	like "-e", except that it implicitly enables all
	   optional features (in the main compilation unit) with Perl 5.10 and
	   later.  See feature.

       -x, --execute
	   Run "perl inputfile"	to determine additional	run-time dependencies.

	   Using this option, pp may be	able to	detect the use of modules that
	   can't be determined by static analysis of "inputfile". Examples are
	   stuff loaded	by run-time loaders like Module::Runtime or "plugin"
	   loaders like	Module::Loader.	Note that which	modules	are detected
	   depends on which parts of your program are exercised	when running
	   "inputfile".	E.g. if	your program immediately terminates when run
	   as "perl inputfile" because it lacks	mandatory arguments, then this
	   option will probably	have no	effect.	You may	use --xargs to supply
	   arguments in	this case.

       --xargs=STRING
	   If -x is given, splits the "STRING" using the function "shellwords"
	   from	Text::ParseWords and passes the	result as @ARGV	when running
	   "perl inputfile".

       -X, --exclude=MODULE
	   Exclude the given module from the dependency	search path and	from
	   the package.	If the given file is a zip or par or par executable,
	   all the files in the	given file (except MANIFEST, META.yml and
	   script/*) will be excluded and the output file will "use" the given
	   file	at runtime.

       -f, --filter=FILTER
	   Filter source script(s) with	a PAR::Filter subclass.	 You may
	   specify multiple such filters.

	   If you wish to hide the source code from casual prying, this	will
	   do:

	       % pp -f Bleach source.pl

	   If you are more serious about hiding	your source code, you should
	   have	a look at Steve	Hay's PAR::Filter::Crypto module. Make sure
	   you understand the Filter::Crypto caveats!

	   Note: Most filters are incompatible with "__DATA__" sections	in
	   your	source.	 The packed executable typically aborts	with an	error
	   message like

	     readline()	on unopened filehandle DATA at (eval 13) line 3.

       -g, --gui
	   Build an executable that does not have a console window. This
	   option is ignored on	non-MSWin32 platforms or when "-p" is
	   specified.

       -h, --help
	   Show	basic usage information.

       -I, --lib=DIR
	   Add the given directory to the perl module search path.  May	be
	   specified multiple times.

       -l, --link=FILE|LIBRARY
	   Add the given shared	library	(a.k.a.	shared object or DLL) into the
	   packed file.	 Also accepts names under library paths; i.e.  "-l
	   ncurses" means the same thing as "-l	libncurses.so" or "-l
	   /usr/local/lib/libncurses.so" in most Unixes.  May be specified
	   multiple times.

       -L, --log=FILE
	   Log the output of packaging to a file rather	than to	stdout.

       -F, --modfilter=FILTER[=REGEX],
	   Filter included perl	module(s) with a PAR::Filter subclass.	You
	   may specify multiple	such filters.

	   By default, the PodStrip filter is applied.	In case	that causes
	   trouble, you	can turn this off by setting the environment variable
	   "PAR_VERBATIM" to 1.

	   Since PAR 0.958, you	can use	an optional regular expression (REGEX
	   above) to select the	files in the archive which should be filtered.
	   Example:

	     pp	-o foo.exe -F Bleach=warnings\.pm$ foo.pl

	   This	creates	a binary executable foo.exe from foo.pl	packaging all
	   files as usual except for files ending in "warnings.pm" which are
	   filtered with PAR::Filter::Bleach.

	   Note: The same restriction on "__DATA__" sections holds as for
	   --filter.

       -M, --module=MODULE
	   Add the specified module into the package, along with its
	   dependencies.

	   The following variants may be used to add whole module namespaces:

	   -M Foo::**
	       Add every module	in the "Foo" namespace except "Foo" itself,
	       i.e.  add "Foo::Bar", "Foo::Bar::Quux" etc up to	any depth.

	   -M Foo::*
	       Add every module	at level 1 in the "Foo"	namespace, i.e.	 add
	       "Foo::Bar", but neither "Foo::Bar::Quux"	nor "Foo".

	   -M Foo::
	       Shorthand for "-M Foo -M	Foo:**": every module in the "Foo"
	       namespace including "Foo" itself.

	   Instead of a	module name, MODULE may	also be	specified as a
	   filename relative to	the @INC path, i.e.  "-M Module/ScanDeps.pm"
	   means the same thing	as "-M Module::ScanDeps".

	   If MODULE has an extension that is not ".pm"/".ix"/".al", it	will
	   not be scanned for dependencies, and	will be	placed under "/"
	   instead of "/lib/" inside the PAR file.  This use is	deprecated --
	   consider using the -a option	instead.

	   You may specify "-M"	multiple times.

       -m, --multiarch
	   Build a multi-architecture PAR file.	 Implies -p.

       -n, --noscan
	   Skip	the default static scanning altogether,	using run-time
	   dependencies	from -c	or -x exclusively.

       -N, --namespace=NAMESPACE
	   Add all modules in the namespace into the package, along with their
	   dependencies. If "NAMESPACE"	is something like "Foo::Bar" then this
	   will	add all	modules	"Foo/Bar/Quux.pm", "Foo/Bar/Fred/Barnie.pm"
	   etc that can	be located in your module search path. It mimics the
	   behaviour of	"plugin" loaders like Module::Loader.

	   This	is different from using	"-M Foo::Bar::", as the	latter insists
	   on adding "Foo/Bar.pm" which	might not exist	in the above "plugin"
	   scenario.

	   You may specify "-N"	multiple times.

       -o, --output=FILE
	   File	name for the final packaged executable.

       -p, --par
	   Create PAR archives only; do	not package to a standalone binary.

       -P, --perlscript
	   Create stand-alone perl script; do not package to a standalone
	   binary.

       -r, --run
	   Run the resulting packaged script after packaging it.

       --reusable
	   EXPERIMENTAL

	   Make	the packaged executable	reusable for running arbitrary,
	   external Perl scripts as if they were part of the package:

	     pp	-o myapp --reusable someapp.pl
	     ./myapp --par-options --reuse otherapp.pl

	   The second line will	run otherapp.pl	instead	of someapp.pl.

       -S, --save
	   Do not delete generated PAR file after packaging.

       -s, --sign
	   Cryptographically sign the generated	PAR or binary file using
	   Module::Signature.

       -T, --tempcache
	   Set the program unique part of the cache directory name that	is
	   used	if the program is run without -C. If not set, a	hash of	the
	   executable is used.

	   When	the program is run, its	contents are extracted to a temporary
	   directory.  On Unix systems,	this is	commonly
	   /tmp/par-USER/cache-XXXXXXX.	 USER is replaced by the name of the
	   user	running	the program, but "spelled" in hex.  XXXXXXX is either
	   a hash of the executable or the value passed	to the "-T" or
	   "--tempcache" switch.

       -u, --unicode
	   Note: This option is	ignored	for Perl 5.32 and above.

	   Package Unicode support (essentially	utf8_heavy.pl and everything
	   below the directory unicore in your perl library).

	   This	option exists because it is impossible to detect using static
	   analysis whether your program needs Unicode support at runtime.
	   (Note: If your program contains "use	utf8" this does	not imply it
	   needs Unicode support. It merely says that your program source is
	   written in UTF-8.)

	   If your packed program exits	with an	error message like

	     Can't locate utf8_heavy.pl	in @INC	(@INC contains:	...)

	   try to pack it with "-u" (or	use "-x").

       -v, --verbose[=NUMBER]
	   Increase verbosity of output; NUMBER	is an integer from 1 to	3, 3
	   being the most verbose.  Defaults to	1 if specified without an
	   argument.  Alternatively, -vv sets verbose level to 2, and -vvv
	   sets	it to 3.

       -V, --version
	   Display the version number and copyrights of	this program.

       -z, --compress=NUMBER
	   Set zip compression level; NUMBER is	an integer from	0 to 9,	0 = no
	   compression,	9 = max	compression.  Defaults to 6 if -z is not used.

ENVIRONMENT
       PP_OPTS
	   Command-line	options	(switches).  Switches in this variable are
	   taken as if they were on every pp command line.

NOTES
       Here are	some recipes showing how to utilize pp to bundle source.pl
       with all	its dependencies, on target machines with different expected
       settings:

       Stone-alone setup:
	   To make a stand-alone executable, suitable for running on a machine
	   that	doesn't	have perl installed:

	       % pp -o packed.exe source.pl	   # makes packed.exe
	       # Now, deploy 'packed.exe' to target machine...
	       $ packed.exe			   # run it

       Perl interpreter	only, without core modules:
	   To make a packed .pl	file including core modules, suitable for
	   running on a	machine	that has a perl	interpreter, but where you
	   want	to be sure of the versions of the core modules that your
	   program uses:

	       % pp -B -P -o packed.pl source.pl   # makes packed.pl
	       # Now, deploy 'packed.pl' to target machine...
	       $ perl packed.pl			   # run it

       Perl with core modules installed:
	   To make a packed .pl	file without core modules, relying on the
	   target machine's perl interpreter and its core libraries.  This
	   produces a significantly smaller file than the previous version:

	       % pp -P -o packed.pl source.pl	   # makes packed.pl
	       # Now, deploy 'packed.pl' to target machine...
	       $ perl packed.pl			   # run it

       Perl with PAR.pm	and its	dependencies installed:
	   Make	a separate archive and executable that uses the	archive. This
	   relies upon the perl	interpreter and	libraries on the target
	   machine.

	       % pp -p source.pl		   # makes source.par
	       % echo "use PAR 'source.par';" >	packed.pl;
	       % cat source.pl >> packed.pl;	   # makes packed.pl
	       # Now, deploy 'source.par' and 'packed.pl' to target machine...
	       $ perl packed.pl			   # run it, perl + core modules required

       Note that even if your perl was built with a shared library, the
       'Stand-alone executable'	above will not need a separate perl5x.dll or
       libperl.so to function correctly.  But even in this case, the
       underlying system libraries such	as libc	must be	compatible between the
       host and	target machines.  Use "--dependent" if you are willing to ship
       the shared library with the application,	which can significantly	reduce
       the executable size.

SEE ALSO
       tkpp, par.pl, parl, perlcc

       PAR, PAR::Packer, Module::ScanDeps

       Getopt::Long, Getopt::ArgvFile

ACKNOWLEDGMENTS
       Simon Cozens, Tom Christiansen and Edward Peschko for writing perlcc;
       this program try	to mimic its interface as close	as possible, and
       copied liberally	from their code.

       Jan Dubois for writing the exetype.pl utility, which has	been partially
       adapted into the	"-g" flag.

       Mattia Barbon for providing the "myldr" binary loader code.

       Jeff Goff for suggesting	the name pp.

AUTHORS
       Audrey Tang <cpan@audreyt.org>, Steffen Mueller <smueller@cpan.org>
       Roderich	Schupp <rschupp@cpan.org>

       You can write to	the mailing list at <par@perl.org>, or send an empty
       mail to <par-subscribe@perl.org>	to participate in the discussion.

       Please submit bug reports to <bug-par-packer@rt.cpan.org>.

COPYRIGHT
       Copyright 2002-2009 by Audrey Tang <cpan@audreyt.org>.

       Neither this program nor	the associated parl program impose any
       licensing restrictions on files generated by their execution, in
       accordance with the 8th article of the Artistic License:

	   "Aggregation	of this	Package	with a commercial distribution is
	   always permitted provided that the use of this Package is embedded;
	   that	is, when no overt attempt is made to make this Package's
	   interfaces visible to the end user of the commercial	distribution.
	   Such	use shall not be construed as a	distribution of	this Package."

       Therefore, you are absolutely free to place any license on the
       resulting executable, as	long as	the packed 3rd-party libraries are
       also available under the	Artistic License.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

       See LICENSE.

perl v5.32.1			  2021-01-13				 pp(3)

NAME | SYNOPSIS | EXAMPLES | DESCRIPTION | OPTIONS | ENVIRONMENT | NOTES | SEE ALSO | ACKNOWLEDGMENTS | AUTHORS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pp&sektion=3pm&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help