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 PATH
.
The underlying virtual machine is also sensitive to a series of environment variables; they are listed in this wiki page.
Affecting execution from the command line§
RAKUDO_OPT
Available as of the 2022.02 Rakudo compiler release.
The RAKUDO_OPT
environment variable provides a way to specify default compiler command line options, overridable by explicitly specifications on the command line. For example:
RAKUDO_OPT="-I. --ll-exception" raku -Ilib test.raku
would ignore the -I.
but would honor the --ll-exception
command line argument.
A simple space splitter is used to separate arguments, making it impossible to use arguments with spaces in them.
Module loading§
RAKUDOLIB
,RAKULIB
Type: Str
.
RAKUDOLIB
and RAKULIB
append a comma-delimited list of paths to the search list for modules. RAKUDOLIB
is evaluated first. NOTE: These env vars were added in the Rakudo compiler in version 2020.05. The deprecated older env var PERL6LIB
is still available.
RAKUDO_MODULE_DEBUG
Type: Bool
.
If true, causes the module loader to print debugging information to standard error.
RAKUDO_PRECOMPILATION_PROGRESS
Type: Bool
.
Available as of the 2021.12 release of the Rakudo compiler.
If true, causes the module loader to print the names of modules that are being re-precompiled on standard error. As such it is a simplified version of the functionality offered by RAKUDO_MODULE_DEBUG
.
Error message verbosity and strictness§
RAKU_EXCEPTIONS_HANDLER
If present, the print_exception
routine will use a class of that name to process the exception for output. Rakudo currently ships with Exceptions::JSON
(invoked by setting this variable to JSON
), to override the default output.
Available as of the 2020.01 release of the Rakudo compiler. Before that it was available as PERL6_EXCEPTIONS_HANDLER
(which was removed in the 2023.04 release of the Rakudo compiler).
Intended to be used by environments that embed the Raku Programming Language, such as IDEs.
RAKU_EXCEPTIONS_HANDLER=JSON raku -e 'die "foo"'
# {"X::AdHoc":{"payload":"foo","message":"foo"}}
RAKUDO_NO_DEPRECATIONS
Type: Bool
.
If true, suppresses deprecation warnings triggered by the is DEPRECATED
trait.
RAKUDO_DEPRECATIONS_FATAL
Type: Bool
.
If true, deprecation warnings become thrown exceptions.
RAKUDO_VERBOSE_STACKFRAME
Type: UInt
.
Displays source code in stack frames surrounded by the specified number of lines of context; for instance RAKUDO_VERBOSE_STACKFRAME = 1
will use one context line.
RAKUDO_BACKTRACE_SETTING
Type: Bool
.
Controls whether .setting
files are included in backtraces.
Affecting precompilation§
RAKUDO_PREFIX
Type: Str
.
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.
These are internal variables for passing serialized state to precompilation jobs in child processes. Please do not set them manually.
RAKUDO_LOG_PRECOMP
If set to 1, diagnostic information about the precompilation process is emitted.
RAKUDO_NO_PRECOMPILATION
If set to 1, precompilation will be disabled. Available as of the 2023.08 release of the Rakudo compiler.
REPL (Read-eval-print loop)§
RAKU_REPL_OUTPUT_METHOD
This specifies the name of the method that should be called on the result value of a statement in the REPL if the statement did not cause any output of its own. If absent, gist
will be assumed. One can use raku
to force a more literal, parsable representation. Or Str
to force a complete string representation. Available as of the 2020.06 release of the Rakudo compiler.
RAKUDO_LINE_EDITOR
This specifies the preferred line editor to use; valid values are LineEditor
, Readline
, Linenoise
, and none. A value of none is useful if you want to avoid the recommendation message upon REPL startup.
RAKUDO_DISABLE_MULTILINE
If set to 1, will disable multiline input for the REPL.
RAKUDO_HIST
This specifies the location of the history file used by the line editor; the default is ~/.raku/rakudo-history
. Before Rakudo version 2020.02 the default was ~/.perl6/rakudo-history
.
Other§
RAKUDO_DEFAULT_READ_ELEMS
This specifies the default number of characters to read on an IO::Handle
by setting the $*DEFAULT-READ-ELEMS
dynamic variable.
RAKUDO_ERROR_COLOR
Type: Bool
.
Controls whether to emit ANSI codes for error highlighting. Defaults to true if unset, except on Windows.
INSIDE_EMACS
Supported as of release 2022.04 of the Rakudo compiler. If specified with a true value, will not try to load any of the line editing modules in the REPL
. This allows the REPL
to be better integrated in the Emacs environment (which sets this environment variable).
RAKUDO_MAX_THREADS
Type: UInt
.
Indicates the maximum number of threads used by default when creating a ThreadPoolScheduler
. Defaults to 64 unless there appear to be more than 8 CPU cores available: in which case it defaults to 8 * number of cores.
As of release 2022.06 of the Rakudo compiler, it is also possible to specify "unlimited" or "Inf" to indicate that the number of threads available by the operating system, will be the limiting factor.
TMPDIR
,TEMP
,TMP
Type: Str
.
The IO::Spec::Unix.tmpdir
method will return $TMPDIR
if it points to a directory with full access permissions for the current user, with a fallback default of '/tmp'
.
IO::Spec::Cygwin
and IO::Spec::Win32
use more Windows-appropriate lists which also include the %TEMP%
and %TMP%
environment variables.
PATH
,Path
Type: Str
.
The IO::Spec::Unix.path
method splits $PATH
as a shell would; i.e. as a colon-separated list. IO::Spec::Cygwin
inherits this from IO::Spec::Unix
. IO::Spec::Win32.path
will read the first defined of either %PATH%
or %Path%
as a semicolon-delimited list.
RAKUDO_SNAPPER
Indicates the period in which the telemetry snapper will take a snapshot. Defaults to .1 for 10 snapshots per second.
RAKUDO_HOME
Allows to override the Raku installation path. Defaults to [rakudo_executable_dir]/../share/perl6
in relocatable builds and the absolute path to that folder in non-relocatable builds.
NQP_HOME
Allows to override the NQP installation path. Defaults to [rakudo_executable_dir]/../share/nqp
in relocatable builds and the absolute path to that folder in non-relocatable builds.
WINDOWS PECULIARITIES§
Non-console applications§
On Windows programs are compiled to either be console applications or non-console applications. 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 'w'
(rakuw.exe
, rakudow.exe
, ...) that are compiled as non-console applications. These do not spawn this console window.
WARNING By default these non-console applications will silently swallow everything that is printed to STDOUT
and STDERR
.
To receive the output of the program it suffices to redirect it externally:
rakuw.exe script.raku >stdout.txt 2>stderr.txt