This file was automatically generated from http://svn.pugscode.org/pugs/docs/Pugs/Doc/Run.pod on Wed Jun 6 22:16:50 2007 GMT, revision 16639.
Pugs::Doc::Run - How to run Pugs
pugs [ -h ] [ -v ] [ -V[:configvar] ] [ -c [file] ] [ -Cbackend [file] ] [ -Bbackend [file] ] [ -Mmodule ] [ --external [file] ] [ -e program ]
The normal way to run a Perl program is by making it directly executable, or else by passing the name of the source file as an argument on the command line. An interactive Pugs environment is also available when pugs is started with no program source. Upon startup, Pugs looks for your program in one of the following places:
WRITEME
You can pass various command line options to Pugs.
-e program
-e commands work too.
-n
causes Pugs to assume the following loop around your program, which makes it iterate over filename arguments somewhat like sed -n or awk:
while =<> {
...your program here...
}
-p
causes Pugs to assume the following loop around your program, which makes it iterate over filename arguments somewhat like sed:
while =<> {
...your program here...
say;
}
-c
causes Pugs to not run the program, but merely check its syntax.
Note that BEGIN {...} and CHECK {...} blocks, as well as use Module,
are still executed, because these might change the grammar or create new
operators, etc. So the following is not safe:
pugs -c 'BEGIN { system "evil command" }'
If you want to run a potentially unsafe program safely, see the safemode Pugs provides.
-Bbackend
causes Pugs to execute the program using backend. Currently, valid
backends are PIR (execution via Parrot), JS (JavaScript), and Pugs.
To start the interactive shell of a backend, run pugs -Bbackend, but note
that currently only the Perl 5 and JavaScript backends provide interactive
shells.
The normal runcore supports more features than the other runcores, the Parrot backend is quite fast, the JavaScript backend is good on binding and references, and Perl 6 on Perl 5 offers excellent support for laziness.
-Cbackend
causes Pugs to compile the program using backend. Currently, valid
backends are Pugs, PIR, GHC, JS, and various variants of PIL:
PIL1, PIL1-Binary, PIL1-JSON, PIL1-Perl5 (and PIL2-...).
Note that, as with -c, BEGIN {...} and CHECK {...} blocks, as well as
use Module statements, are still executed. So don't try to compile
potentially unsafe code!
-Mmodule
causes Pugs to load module before executing your program:
use module;
...your code here...
-h or --help
-V
-V:item
displays short configuration information for item.
$ pugs -V:pugs_versnum
pugs_versnum: 6.2.6
-v or --version
-l, -d, and -w
The Pugs runtime environment is affected by several environment variables.
The build environment is likewise controlled by several environment variables; since Pugs is still in heavy development, they are listed here as well.
HARNESS_PERL [BUILD]
pugs itself at all. When building Pugs from source, the
Perl 5 test system should be instructed to use your copy of Pugs. If you use
make test or make smoke, you should not need to set this manually; but if
you want to use prove, set it to ./pugs (or pugs.exe on Windows).
PERL6LIB
A list of directories in which to look for Perl library files before looking in
the standard library and the current directory. Any architecture-specific
directories under the specified locations are automatically included if they
exist. If PERL6LIB is not defined, PERLLIB is used.
Directories are separated (as in PATH) by a colon on unixish platforms and
by a semicolon on Windows (the proper path separator being given by the command
pugs -V:path_sep).
When building your own pugs, set PERL6LIB to blib6/lib to make tests use
the correct version of the libraries. make test and make smoke should do
this for you.
PERLLIB
PERL6LIB is defined. See PERL6LIB for details on paths.
PUGS_BYPASS_PRELUDE
Many Perl subroutines are provided to Pugs by a library called the Standard
Prelude, which is inlined into the pugs executable and loaded by default on
each startup of pugs. If PUGS_BYPASS_PRELUDE is set to anything except ""
or "0", then pugs will not load the Prelude automatically. This gives a
minor speedup on startup, as well as allowing you to load your alternate
version of Prelude.pm like this:
# In this example, Prelude.pm will be searched for in @*INC
$ env PUGS_BYPASS_PRELUDE=1 pugs -MPrelude -e '...'
PUGS_COMPILE_PRELUDE
PUGS_COMPILE_PRELUDE to true, you
override this default and the Prelude will be compiled along with your code.
This is normally not needed, as the prelude should already be provided as
part of the target runtime environment.
PUGS_SAFEMODE
Pugs provides a global "safe mode" which makes many operations that are deemed "unsafe" -- e.g. operations which use IO -- unavailable to a Perl program.
$ env PUGS_SAFEMODE=1 pugs -e 'unlink "foo"'
*** No compatible subroutine found: "&unlink"
at -e line 1, column 1-13
PUGS_PARROT_OPTS
If you haven't embedded Parrot in your Pugs build, Pugs will start an external Parrot if needed. You can set additional options Pugs should pass to parrot:
$ env PUGS_PARROT_OPTS="-j" pugs -e 'eval("...", :lang<PIR>)'
# Use JIT
If PUGS_PARROT_OPTS is not set, -C will be passed to parrot, selecting
the computed goto core.
PUGS_SMOKE_UPLOAD [BUILD]
If set, util/run-smoke.pl (make smoke) uses this to upload your smoke
tests results automatically. Set this to a command to run, e.g.
rsync -avz smoke.html perlcabal.org:public_html
You may alternatively set the smoke_upload option in config.yml to
have smokes uploaded to the public smokeserver automatically.
PUGS_TESTS_CONCURRENT [BUILD]
Smoke tests can take quite some time to complete. If you have a multiprocessor machine, you can set this to a small integer value, and util/yaml_harness.pl will run that amount of tests in parallel.
On a single-processor, HyperThreaded machine that is otherwise unused,
2 is a good value. On real multiprocessor machines, one more than the
CPU count is suggested.
This is equivalent to running util/yaml_harness.pl -j number.
(Has no effect on Windows.)
PUGS_BUILD_CONFIG [BUILD]
PUGS_BUILD_CONFIG will be used as
configuration file. The default is config.yml.