=begin pod :kind("Programs") :subkind("programs") :category("programs")

=TITLE Running Rakudo

=SUBTITLE How to run Rakudo, a Raku implementation, and modify its behavior
with environment variables.

=head1 NAME

raku - Rakudo Raku Compiler

=head1 SYNOPSIS

=for code :lang<usage>
raku [switches] [--] [programfile] [arguments]

=head1 DESCRIPTION

With no arguments, enters a REPL. With a C<[programfile]> or the C<-e>
option, compiles the given program and by default also executes the
compiled code.

=begin code :lang<usage>
-c                   check syntax only (runs BEGIN and CHECK blocks)
--doc                extract documentation and print it as text
-e program           one line of program, strict is enabled by default
-h, --help           display this help text
-n                   run program once for each line of input
-p                   same as -n, but also print $_ at the end of lines
-I path              adds the path to the module search path
-M module            loads the module prior to running the program
--target=[stage]     specify compilation stage to emit
--optimize=[level]   use the given level of optimization (0..3)
--encoding=[mode]    specify string encoding mode
-o, --output=[name]  specify name of output file
-v, --version        display version information
--stagestats         display time spent in the compilation stages
--ll-exception       display a low level backtrace on errors
--profile            write profile information as HTML file (MoarVM)
--profile-filename   provide a different filename (also allows .json)
--doc=[module]       Use Pod::To::[module] to render inline documentation.
--full-cleanup       try to free all memory and exit cleanly (MoarVM)
--debug-port=port    listen for incoming debugger connections (MoarVM)
--debug-suspend      pause execution at the entry point (MoarVM)
--tracing            output a line to stderr on every interpreter instr (only
                     if enabled in MoarVM)
=end code

Note that only boolean single-letter options may be bundled.

The supported values for C<--target> are:

=begin code :lang<text>
Target     Backend  Description
======     =======  ===========
parse      all      a representation of the parse tree
ast        all      an abstract syntax tree (before optimizations)
optimize   all      an abstract syntax tree (after optimizations)

mbc        MoarVM   MoarVM byte code
jar        JVM      JVM archive
=end code

For C<--profile-filename>, specifying a name ending in C<.json> will write a raw
JSON profile dump. The default if this is omitted is C<profile-I<[timestamp]>.html>.

=head1 ENVIRONMENT VARIABLES

Rakudo's behavior can be tweaked by a (growing) number of environment variables;
this section attempts to document all those currently in use. They are
interpreter specific in all cases, except where some use conventional names
such as C<PATH>.

The underlying virtual machine is also sensitive to a series of environment
variables; they are listed L<in this wiki
page|https://github.com/rakudo/rakudo/wiki/dev-env-vars#moarvm>.

=head2 Module loading

X<|RAKUDOLIB>X<|RAKULIB>X<|PERL6LIB>
=item C<RAKUDOLIB>, C<RAKULIB> (I<Str>; B<src/core/Inc.pm>)

C<RAKUDOLIB> and C<RAKULIB> append a comma-delimited list of paths to the
search list for modules. C<RAKUDOLIB> is evaluated first. B<NOTE:> These env
vars were added in the Rakudo compiler in version 2020.05. The deprecated older
env var C<PERL6LIB> is still available.

X<|RAKUDO_MODULE_DEBUG>
=item C<RAKUDO_MODULE_DEBUG> (I<Bool>; B<src/Perl6/ModuleLoader.nqp>)

If true, causes the module loader to print debugging information to standard
error.

=head2 Error message verbosity and strictness

X<|RAKU_EXCEPTIONS_HANDLER>
X<|PERL6_EXCEPTIONS_HANDLER>
=item C<RAKU_EXCEPTIONS_HANDLER>

If present, the C<print_exception> routine
will use a class of that name to process the exception for output. Rakudo
currently ships with C<Exceptions::JSON> (invoked by setting this variable to
C<JSON>), to override the default output. B<NOTE:> This env var was added in
version 6.e.  Early implementation has been available in Rakudo compiler
as of version 2019.12, and before that it was available as
C<PERL6_EXCEPTIONS_HANDLER>.

X<|RAKUDO_NO_DEPRECATIONS>
=item C<RAKUDO_NO_DEPRECATIONS> (I<Bool>; B<src/core.c/Deprecations.pm6>)

If true, suppresses deprecation warnings triggered by the C<is DEPRECATED>
trait.

X<|RAKUDO_DEPRECATIONS_FATAL>
=item C<RAKUDO_DEPRECATIONS_FATAL> (I<Bool>; B<src/core.c/Deprecations.pm6>)

If true, deprecation warnings become thrown exceptions.

X<|RAKUDO_VERBOSE_STACKFRAME>
=item C<RAKUDO_VERBOSE_STACKFRAME> (I<UInt>; B<src/core.c/Backtrace.pm6>)

Displays source code in stack frames surrounded by the specified number of
lines of context; for instance C<RAKUDO_VERBOSE_STACKFRAME = 1> will use one
context line.

X<|RAKUDO_BACKTRACE_SETTING>
=item C<RAKUDO_BACKTRACE_SETTING> (I<Bool>; B<src/core.c/Backtrace.pm6>)

Controls whether C<.setting> files are included in backtraces.

=head2 Affecting precompilation

X<|RAKUDO_PREFIX>
=item C<RAKUDO_PREFIX> (I<Str>; B<src/core.c/CompUnit/RepositoryRegistry.pm6>)

When this is set, Rakudo will look for the standard repositories (perl, vendor,
site) in the specified directory. This is intended as an escape hatch for
build-time bootstrapping issues, where Rakudo may be built as an unprivileged
user without write access to the runtime paths in NQP's config.

X<|RAKUDO_PRECOMP_DIST>
=item C<RAKUDO_PRECOMP_DIST> (B<src/core.c/CompUnit/PrecompilationRepository.pm6>)
X<|RAKUDO_PRECOMP_LOADING>
=item C<RAKUDO_PRECOMP_LOADING> (B<src/core.c/CompUnit/PrecompilationRepository.pm6>)
X<|RAKUDO_PRECOMP_WITH>
=item C<RAKUDO_PRECOMP_WITH> (B<src/core.c/CompUnit/PrecompilationRepository.pm6>)

These are internal variables for passing serialized state to precompilation jobs
in child processes. Please do not set them manually.

X<|RAKUDO_LOG_PRECOMP>
=item C<RAKUDO_LOG_PRECOMP>

If set to 1, diagnostic information about the precompilation process is
emitted.

=head2 Line editor

X<|RAKUDO_LINE_EDITOR>
=item C<RAKUDO_LINE_EDITOR>

This specifies the preferred line editor to use; valid values are C<Readline>,
C<Linenoise>, and none. A value of none is useful if you want to avoid the
recommendation message upon REPL startup.

X<|RAKUDO_DISABLE_MULTILINE>
=item C<RAKUDO_DISABLE_MULTILINE>

If set to 1, will disable multiline input for the REPL.

X<|RAKUDO_HIST>
=item C<RAKUDO_HIST>

This specifies the location of the history file used by the
line editor; the default is C<~/.raku/rakudo-history>.
Before Rakudo version 2020.02 the default was
C<~/.perl6/rakudo-history>.

=head2 Other

X<|RAKUDO_DEFAULT_READ_ELEMS>
=item C<RAKUDO_DEFAULT_READ_ELEMS>

This specifies the default number of characters to read on an
L«C<IO::Handle>|/type/IO::Handle» by setting the
L«C<$*DEFAULT-READ-ELEMS>|/language/variables#$*DEFAULT-READ-ELEMS» dynamic
variable.

X<|RAKUDO_ERROR_COLOR>
=item C<RAKUDO_ERROR_COLOR> (I<Bool>; B<src/core.c/Exception.pm6>)

Controls whether to emit ANSI codes for error highlighting. Defaults to true
if unset, except on Windows.

X<|RAKUDO_MAX_THREADS>
=item C<RAKUDO_MAX_THREADS> (I<UInt>; B<src/core.c/ThreadPoolScheduler.pm6>)

Indicates the maximum number of threads used by default when creating a
C<ThreadPoolScheduler>. Defaults to 64.

X<|TMPDIR>X<|TEMP>X<|TMP>
=item C<TMPDIR>, C<TEMP>, C<TMP> (I<Str>; B<src/core.c/IO/Spec/>)

The C<IO::Spec::Unix.tmpdir> method will return C<$TMPDIR> if it points to a
directory with full access permissions for the current user, with a fallback
default of C<'/tmp'>.

C<IO::Spec::Cygwin> and C<IO::Spec::Win32> use more Windows-appropriate lists
which also include the C<%TEMP%> and C<%TMP%> environment variables.

X<|PATH>
=item C<PATH>, C<Path> (I<Str>; B<src/core.c/IO/Spec/>)

The C<IO::Spec::Unix.path> method splits C<$PATH> as a
shell would; i.e. as a colon-separated list. C<IO::Spec::Cygwin> inherits this
from C<IO::Spec::Unix>. C<IO::Spec::Win32.path> will read the first defined of
either C<%PATH%> or C<%Path%> as a semicolon-delimited list.

X<|RAKUDO_SNAPPER>
=item C<RAKUDO_SNAPPER>

Indicates the period in which the telemetry snapper will take a snapshot.
Defaults to .1 for 10 snapshots per second.

X<|RAKUDO_HOME>
=item C<RAKUDO_HOME>

Allows to override the Raku installation path. Defaults to
C<[rakudo_executable_dir]/../share/perl6> in relocatable builds and the
absolute path to that folder in non-relocatable builds.

X<|NQP_HOME>
=item C<NQP_HOME>

Allows to override the NQP installation path. Defaults to
C<[rakudo_executable_dir]/../share/nqp> in relocatable builds and the absolute
path to that folder in non-relocatable builds.

=head1 WINDOWS PECULIARITIES

X<|rakuw.exe>X<|rakudow.exe>
=head2 Non-console applications

On Windows programs are compiled to either be I<console> applications or
I<non-console> applications. I<Console> applications always open a console
window. There is no straightforward way to suppress this window.

Rakudo provides a separate set of executables suffixed with a C<'w'>
(C<rakuw.exe>, C<rakudow.exe>, ...) that are compiled as I<non-console>
applications. These do not spawn this console window.

B<WARNING> By default these I<non-console> applications will silently swallow
everything that is printed to C<STDOUT> and C<STDERR>.

To receive the output of the program it suffices to redirect it externally:

=for code :lang<batch>
rakuw.exe script.raku >stdout.txt 2>stderr.txt

=head1 AUTHORS

Written by the Rakudo contributors, see the CREDITS file.

This manual page was written by Reini Urban, Moritz Lenz and the Rakudo
contributors.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
