perl6(1)

📦
version 2024.09 · 4 versions
, in ubuntu resolute, ubuntu stonking

✨ perl6(1) ✨

okay bestie, listen 💖 this is the User Contributed Perl Documentation page for perl6, section 1 of the manual. Yes the title says perl6 but the thing it documents is raku, and honestly? iconic. Let's go. 🦋

🌸 NAME 🌸

raku — the Rakudo Raku Compiler. that's it, that's the whole name, slay 👑

✨ SYNOPSIS ✨

raku [switches] [--] [programfile] [arguments]

look at her. so simple. so powerful. 💅

🎀 DESCRIPTION 🎀

If you run her with no arguments at all, she drops you into a REPL. Live. Interactive. Just you and the prompt. 🫶

If you give her a [programfile], or you use the -e option, she compiles the program you gave her — and by default she also executes the compiled code. So it actually runs. no cap.

here's the full switch lineup, every single one, no skips:

  • -c — check syntax only (and yes, it still runs BEGIN and CHECK blocks)
  • --doc — extract documentation and print it as text
  • -e program — one line of program, and 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)
⚠️ heads up bestie: only boolean single-letter options may be bundled. don't get cute with the multi-letter ones.

💫 the --target values 💫

here's what you can ask her to emit, plus which backend it belongs to and what it actually is:

  • parse — backend: all — a representation of the parse tree
  • ast — backend: all — an abstract syntax tree (before optimizations)
  • optimize — backend: all — an abstract syntax tree (after optimizations)
  • mbc — backend: MoarVM — MoarVM byte code
  • jar — backend: JVM — JVM archive

🧚 about --profile-filename 🧚

if the name you give it ends in .json, she writes a raw JSON profile dump. and if you just omit it entirely, the default is profile-[timestamp].html. so cute, so timestamped. ⭐

🌈 ENVIRONMENT VARIABLES 🌈

Rakudo's behavior can be tweaked by a (growing) number of environment variables, and this section is doing its best to document all of the ones 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 whole series of environment variables; those are listed in this wiki page: <https://github.com/rakudo/rakudo/wiki/dev-env-vars#moarvm> (sorry bestie, no clickable links in here, you're gonna have to copy-paste it 💀).

✨ 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. 😭 yes, they jump you.
  • 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)
  • RAKUDO_PRECOMP_LOADING (src/core.c/CompUnit/PrecompilationRepository.pm6)
  • 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. glow-up handled for you 💖

🌟 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 (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. that's just the vibe over there, we don't make the rules.

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. gone. deleted. not me losing all my output 😭

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

rakuw.exe script.raku >stdout.txt 2>stderr.txt

there she is. redirect your way to freedom 🫶

👑 AUTHORS 👑

Written by the Rakudo contributors, see the CREDITS file.

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

and finally, the little incantation tucked at the bottom of the source file, exactly as written:

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

okay that's the whole page, you ate it bestie 💅 the footer energy on this one is perl v5.40.1, dated 2026-02-11, and it lives as perl6(1) — User Contributed Perl Documentation. periodt. 🌸🦋💖

📦 where this page comes from