=head1 NAME

pugs::run - How to execute Pugs

=head1 SYNOPSYS

B<pugs> S<[ B<-h> ]> S<[ B<-v> ]>
     S<[ B<-V>[:I<configvar>] ]>
     S<[ B<-c> [I<file>] ]>
     S<[ B<-C>I<backend> [I<file>] ]>
     S<[ B<-B>I<backend> [I<file>] ]>
     S<[ B<-M>I<module> ]>
     S<[ B<--external> [I<file>] ] >
     S<[ B<-e> I<program> ]>

=head1 DESCRIPTION

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, by starting B<pugs> with no
program source.  Upon startup, Pugs looks for your program in one of the
following places:

WRITEME

=head2 Command line options

You can pass various command line options to Pugs.

=over

=item C<-e I<program>>

causes Pugs to not look for any program files in the command line options, but
instead run the one-line program specified. Multiple C<-e> commands work too.

=item C<-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...
    }

=item C<-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;
    }

=item C<-c>

causes Pugs to not run the program, but merely check its syntax.

Note that C<BEGIN {...}> and C<CHECK {...}> blocks, as well as C<use Module>,
are still executed, because these might change the grammar or create new
operators, etc. So the following is B<not> safe:

    pugs -c 'BEGIN { system "evil command" }'

If you want to run a potentially unsafe program safely, see the safemode Pugs
provides.

=item C<-BI<backend>>

causes Pugs to execute the program using C<I<backend>>. Currently, valid
backends are C<Pugs>, C<Parrot>, and C<Haskell>.

=item C<-CI<backend>>

causes Pugs to compile the program using C<I<backend>>. Currently, valid
backends are C<Pugs>, C<Parrot>, and C<Haskell>.

Note that, as with C<-c>, C<BEGIN {...}> and C<CHECK {...}> blocks, as well as
C<use Module>, are still executed. So don't try to compile potentially unsafe
code!

=item C<-MI<module>>

causes Pugs to load C<I<module>> before executing your program:

    use module;
    ...your code here...

=item C<-h> or C<--help>

outputs a short summary of the available command line options. No programs are
executed.

=item C<-V>

outputs the version of Pugs you're running and long configuration information.

=item C<-V:I<item>>

outputs short configuration information for C<I<item>>.

    $ pugs -V:pugs_version
    pugs_versnum: 6.2.6

=item C<-v> or C<--version>

outputs the version of Pugs you're running.

=item C<-l>, C<-d>, and C<-w>

are ignored for compatibility with Perl 5.

=back

=head1 ENVIRONMENT

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 will be listed here as well.

=over

=item C<HARNESS_PERL> [BUILD]

This does not affect C<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
C<make test> or C<make smoke>, you should not need to set this manually; but if
you want to use C<prove>, set it to C<./pugs> (or C<pugs.exe> on Windows).

=item C<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 C<PERL6LIB> is not defined, C<PERLLIB> is used.
Directories are separated (like in C<PATH>) by a colon on unixish platforms and
by a semicolon on Windows (the proper path separator being given by the command
C<pugs -V:path_sep>).

When building your own pugs, set C<PERL6LIB> to C<blib6/lib> to make tests use
the correct version of the libraries. C<make test> and C<make smoke> should do
this for you.

=item C<PERLLIB>

A list of directories in which to look for Perl library files before
looking in the standard library and the current directory. Not consulted
if C<PERL6LIB> is defined. See C<PERL6LIB> for details on paths.

=item C<PUGS_BYPASS_PRELUDE>

Many Perl functions 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 C<PUGS_BYPASS_PRELUDE> is set to anything except C<"">
or C<"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 F<Prelude.pm> like this:

    # in this example, Prelude.pm will be searched for in @*INC
    $ env PUGS_BYPASS_PRELUDE=1 pugs -MPrelude -e '...'

=item C<PUGS_SAFEMODE>

Pugs provides a global "safe mode" which makes many operations that are deemed
"unsafe", i.e. operations which use IO, unavailable to a Perl program.

    $ env PUGS_SAFEMODE=1 pugs -e 'say "I am unsafe"'
    *** No compatible subroutine found: "&say"
        at -e line 1, column 1-9

=item C<PUGS_SMOKE_UPLOAD> [BUILD]

If set, F<util/run-smoke.pl> (C<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

=item C<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
F<util/yaml_harness.pl> will run that amount of tests in parallel.

On a single-processor hyper-threading machine that is otherwise unused,
C<2> is a good value. On real multiprocessor machines, one more than the
CPU count is suggested.

Equivalent to running C<util/yaml_harness.pl -j I<number>> .

[Has no effect on Windows.]

=back

=head1 SEE ALSO

L<Perl6::Pugs>