--- name: "perl6" section: "1" platform: "linux" package: "rakudo" version: "2024.09-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/perl6" --- # perl6(1) Rakudo Raku Compiler ## NAME raku - Rakudo Raku Compiler ## SYNOPSIS ``` raku [switches] [--] [programfile] [arguments] ``` ## DESCRIPTION With no arguments, enters a REPL. With a `"[programfile]"` or the `"-e"` option, compiles the given program and by default also executes the compiled code. ``` -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) ``` Note that only boolean single-letter options may be bundled. The supported values for `"--target"` are: ``` 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 ``` For `"--profile-filename"`, specifying a name ending in `".json"` will write a raw JSON profile dump. The default if this is omitted is `"profile-`*\[timestamp\]*`.html"`. ## 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 `"PATH"`. The underlying virtual machine is also sensitive to a series of environment variables; they are listed in this wiki page \. ### Module loading - "RAKUDOLIB", "RAKULIB" (*Str*; *src/core/Inc.pm*) `"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" (*Bool*; *src/Perl6/ModuleLoader.nqp*) If true, causes the module loader to print debugging information to standard error. ### 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. **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 `"PERL6_EXCEPTIONS_HANDLER"`. - "RAKUDO\_NO\_DEPRECATIONS" (*Bool*; *src/core.c/Deprecations.pm6*) If true, suppresses deprecation warnings triggered by the `"is DEPRECATED"` trait. - "RAKUDO\_DEPRECATIONS\_FATAL" (*Bool*; *src/core.c/Deprecations.pm6*) If true, deprecation warnings become thrown exceptions. - "RAKUDO\_VERBOSE\_STACKFRAME" (*UInt*; *src/core.c/Backtrace.pm6*) 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" (*Bool*; *src/core.c/Backtrace.pm6*) Controls whether `".setting"` files are included in backtraces. ### Affecting precompilation - "RAKUDO\_PREFIX" (*Str*; *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. - "RAKUDO\_PRECOMP\_DIST" (*src/core.c/CompUnit/PrecompilationRepository.pm6*) =item "RAKUDO\_PRECOMP\_LOADING" (*src/core.c/CompUnit/PrecompilationRepository.pm6*) =item "RAKUDO\_PRECOMP\_WITH" (*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. - "RAKUDO\_LOG\_PRECOMP" If set to 1, diagnostic information about the precompilation process is emitted. ### Line editor - "RAKUDO\_LINE\_EDITOR" This specifies the preferred line editor to use; valid values are `"Readline"`, `"Linenoise"`, `"LineEditor"`, 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"`. If the older default file exists and the newer one does not, it will be automatically migrated. ### Other - "RAKUDO\_DEFAULT\_READ\_ELEMS" This specifies the default number of characters to read on an L«`"IO::Handle"`\|/type/IO::Handle» by setting the L«`"$*DEFAULT-READ-ELEMS"`\|/language/variables#$\*DEFAULT-READ-ELEMS» dynamic variable. - "RAKUDO\_ERROR\_COLOR" (*Bool*; *src/core.c/Exception.pm6*) Controls whether to emit ANSI codes for error highlighting. Defaults to true if unset, except on Windows. - "RAKUDO\_MAX\_THREADS" (*UInt*; *src/core.c/ThreadPoolScheduler.pm6*) Indicates the maximum number of threads used by default when creating a `"ThreadPoolScheduler"`. Defaults to 64. - "TMPDIR", "TEMP", "TMP" (*Str*; *src/core.c/IO/Spec/*) 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" (*Str*; *src/core.c/IO/Spec/*) 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 ``` ## AUTHORS Written by the Rakudo contributors, see the CREDITS file. This manual page was written by Reini Urban, Moritz Lenz and the Rakudo contributors. \# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6