.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "perl6 1" .TH perl6 1 2024-03-10 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME raku \- Rakudo Raku Compiler .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& raku [switches] [\-\-] [programfile] [arguments] .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" With no arguments, enters a REPL. With a \f(CW\*(C`[programfile]\*(C'\fR or the \f(CW\*(C`\-e\*(C'\fR option, compiles the given program and by default also executes the compiled code. .PP .Vb 10 \& \-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) .Ve .PP Note that only boolean single-letter options may be bundled. .PP The supported values for \f(CW\*(C`\-\-target\*(C'\fR are: .PP .Vb 5 \& 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 .Ve .PP For \f(CW\*(C`\-\-profile\-filename\*(C'\fR, specifying a name ending in \f(CW\*(C`.json\*(C'\fR will write a raw JSON profile dump. The default if this is omitted is \f(CW\*(C`profile\-\fR\f(CI[timestamp]\fR\f(CW.html\*(C'\fR. .SH "ENVIRONMENT VARIABLES" .IX Header "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 \f(CW\*(C`PATH\*(C'\fR. .PP The underlying virtual machine is also sensitive to a series of environment variables; they are listed in this wiki page . .SS "Module loading" .IX Subsection "Module loading" .ie n .IP """RAKUDOLIB"", ""RAKULIB"" (\fIStr\fR; \fIsrc/core/Inc.pm\fR)" 4 .el .IP "\f(CWRAKUDOLIB\fR, \f(CWRAKULIB\fR (\fIStr\fR; \fIsrc/core/Inc.pm\fR)" 4 .IX Item "RAKUDOLIB, RAKULIB (Str; src/core/Inc.pm)" \&\f(CW\*(C`RAKUDOLIB\*(C'\fR and \f(CW\*(C`RAKULIB\*(C'\fR append a comma-delimited list of paths to the search list for modules. \f(CW\*(C`RAKUDOLIB\*(C'\fR is evaluated first. \fBNOTE:\fR These env vars were added in the Rakudo compiler in version 2020.05. The deprecated older env var \f(CW\*(C`PERL6LIB\*(C'\fR is still available. .ie n .IP """RAKUDO_MODULE_DEBUG"" (\fIBool\fR; \fIsrc/Perl6/ModuleLoader.nqp\fR)" 4 .el .IP "\f(CWRAKUDO_MODULE_DEBUG\fR (\fIBool\fR; \fIsrc/Perl6/ModuleLoader.nqp\fR)" 4 .IX Item "RAKUDO_MODULE_DEBUG (Bool; src/Perl6/ModuleLoader.nqp)" If true, causes the module loader to print debugging information to standard error. .SS "Error message verbosity and strictness" .IX Subsection "Error message verbosity and strictness" .ie n .IP """RAKU_EXCEPTIONS_HANDLER""" 4 .el .IP \f(CWRAKU_EXCEPTIONS_HANDLER\fR 4 .IX Item "RAKU_EXCEPTIONS_HANDLER" If present, the \f(CW\*(C`print_exception\*(C'\fR routine will use a class of that name to process the exception for output. Rakudo currently ships with \f(CW\*(C`Exceptions::JSON\*(C'\fR (invoked by setting this variable to \&\f(CW\*(C`JSON\*(C'\fR), to override the default output. \fBNOTE:\fR 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 \&\f(CW\*(C`PERL6_EXCEPTIONS_HANDLER\*(C'\fR. .ie n .IP """RAKUDO_NO_DEPRECATIONS"" (\fIBool\fR; \fIsrc/core.c/Deprecations.pm6\fR)" 4 .el .IP "\f(CWRAKUDO_NO_DEPRECATIONS\fR (\fIBool\fR; \fIsrc/core.c/Deprecations.pm6\fR)" 4 .IX Item "RAKUDO_NO_DEPRECATIONS (Bool; src/core.c/Deprecations.pm6)" If true, suppresses deprecation warnings triggered by the \f(CW\*(C`is DEPRECATED\*(C'\fR trait. .ie n .IP """RAKUDO_DEPRECATIONS_FATAL"" (\fIBool\fR; \fIsrc/core.c/Deprecations.pm6\fR)" 4 .el .IP "\f(CWRAKUDO_DEPRECATIONS_FATAL\fR (\fIBool\fR; \fIsrc/core.c/Deprecations.pm6\fR)" 4 .IX Item "RAKUDO_DEPRECATIONS_FATAL (Bool; src/core.c/Deprecations.pm6)" If true, deprecation warnings become thrown exceptions. .ie n .IP """RAKUDO_VERBOSE_STACKFRAME"" (\fIUInt\fR; \fIsrc/core.c/Backtrace.pm6\fR)" 4 .el .IP "\f(CWRAKUDO_VERBOSE_STACKFRAME\fR (\fIUInt\fR; \fIsrc/core.c/Backtrace.pm6\fR)" 4 .IX Item "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 \f(CW\*(C`RAKUDO_VERBOSE_STACKFRAME = 1\*(C'\fR will use one context line. .ie n .IP """RAKUDO_BACKTRACE_SETTING"" (\fIBool\fR; \fIsrc/core.c/Backtrace.pm6\fR)" 4 .el .IP "\f(CWRAKUDO_BACKTRACE_SETTING\fR (\fIBool\fR; \fIsrc/core.c/Backtrace.pm6\fR)" 4 .IX Item "RAKUDO_BACKTRACE_SETTING (Bool; src/core.c/Backtrace.pm6)" Controls whether \f(CW\*(C`.setting\*(C'\fR files are included in backtraces. .SS "Affecting precompilation" .IX Subsection "Affecting precompilation" .ie n .IP """RAKUDO_PREFIX"" (\fIStr\fR; \fIsrc/core.c/CompUnit/RepositoryRegistry.pm6\fR)" 4 .el .IP "\f(CWRAKUDO_PREFIX\fR (\fIStr\fR; \fIsrc/core.c/CompUnit/RepositoryRegistry.pm6\fR)" 4 .IX Item "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. .ie n .IP """RAKUDO_PRECOMP_DIST"" (\fIsrc/core.c/CompUnit/PrecompilationRepository.pm6\fR) =item ""RAKUDO_PRECOMP_LOADING"" (\fIsrc/core.c/CompUnit/PrecompilationRepository.pm6\fR) =item ""RAKUDO_PRECOMP_WITH"" (\fIsrc/core.c/CompUnit/PrecompilationRepository.pm6\fR)" 4 .el .IP "\f(CWRAKUDO_PRECOMP_DIST\fR (\fIsrc/core.c/CompUnit/PrecompilationRepository.pm6\fR) =item \f(CWRAKUDO_PRECOMP_LOADING\fR (\fIsrc/core.c/CompUnit/PrecompilationRepository.pm6\fR) =item \f(CWRAKUDO_PRECOMP_WITH\fR (\fIsrc/core.c/CompUnit/PrecompilationRepository.pm6\fR)" 4 .IX Item "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. .ie n .IP """RAKUDO_LOG_PRECOMP""" 4 .el .IP \f(CWRAKUDO_LOG_PRECOMP\fR 4 .IX Item "RAKUDO_LOG_PRECOMP" If set to 1, diagnostic information about the precompilation process is emitted. .SS "Line editor" .IX Subsection "Line editor" .ie n .IP """RAKUDO_LINE_EDITOR""" 4 .el .IP \f(CWRAKUDO_LINE_EDITOR\fR 4 .IX Item "RAKUDO_LINE_EDITOR" This specifies the preferred line editor to use; valid values are \f(CW\*(C`Readline\*(C'\fR, \&\f(CW\*(C`Linenoise\*(C'\fR, \f(CW\*(C`LineEditor\*(C'\fR, and \f(CW\*(C`none\*(C'\fR. A value of \f(CW\*(C`none\*(C'\fR is useful if you want to avoid the recommendation message upon REPL startup. .ie n .IP """RAKUDO_DISABLE_MULTILINE""" 4 .el .IP \f(CWRAKUDO_DISABLE_MULTILINE\fR 4 .IX Item "RAKUDO_DISABLE_MULTILINE" If set to 1, will disable multiline input for the REPL. .ie n .IP """RAKUDO_HIST""" 4 .el .IP \f(CWRAKUDO_HIST\fR 4 .IX Item "RAKUDO_HIST" This specifies the location of the history file used by the line editor; the default is \f(CW\*(C`~/.raku/rakudo\-history\*(C'\fR. Before Rakudo version 2020.02 the default was \f(CW\*(C`~/.perl6/rakudo\-history\*(C'\fR. If the older default file exists and the newer one does not, it will be automatically migrated. .SS Other .IX Subsection "Other" .ie n .IP """RAKUDO_DEFAULT_READ_ELEMS""" 4 .el .IP \f(CWRAKUDO_DEFAULT_READ_ELEMS\fR 4 .IX Item "RAKUDO_DEFAULT_READ_ELEMS" This specifies the default number of characters to read on an L«\f(CW\*(C`IO::Handle\*(C'\fR|/type/IO::Handle» by setting the L«\f(CW\*(C`$*DEFAULT\-READ\-ELEMS\*(C'\fR|/language/variables#$*DEFAULT\-READ\-ELEMS» dynamic variable. .ie n .IP """RAKUDO_ERROR_COLOR"" (\fIBool\fR; \fIsrc/core.c/Exception.pm6\fR)" 4 .el .IP "\f(CWRAKUDO_ERROR_COLOR\fR (\fIBool\fR; \fIsrc/core.c/Exception.pm6\fR)" 4 .IX Item "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. .ie n .IP """RAKUDO_MAX_THREADS"" (\fIUInt\fR; \fIsrc/core.c/ThreadPoolScheduler.pm6\fR)" 4 .el .IP "\f(CWRAKUDO_MAX_THREADS\fR (\fIUInt\fR; \fIsrc/core.c/ThreadPoolScheduler.pm6\fR)" 4 .IX Item "RAKUDO_MAX_THREADS (UInt; src/core.c/ThreadPoolScheduler.pm6)" Indicates the maximum number of threads used by default when creating a \&\f(CW\*(C`ThreadPoolScheduler\*(C'\fR. Defaults to 64. .ie n .IP """TMPDIR"", ""TEMP"", ""TMP"" (\fIStr\fR; \fIsrc/core.c/IO/Spec/\fR)" 4 .el .IP "\f(CWTMPDIR\fR, \f(CWTEMP\fR, \f(CWTMP\fR (\fIStr\fR; \fIsrc/core.c/IO/Spec/\fR)" 4 .IX Item "TMPDIR, TEMP, TMP (Str; src/core.c/IO/Spec/)" The \f(CW\*(C`IO::Spec::Unix.tmpdir\*(C'\fR method will return \f(CW$TMPDIR\fR if it points to a directory with full access permissions for the current user, with a fallback default of \f(CW\*(Aq/tmp\*(Aq\fR. .Sp \&\f(CW\*(C`IO::Spec::Cygwin\*(C'\fR and \f(CW\*(C`IO::Spec::Win32\*(C'\fR use more Windows-appropriate lists which also include the \f(CW\*(C`%TEMP%\*(C'\fR and \f(CW\*(C`%TMP%\*(C'\fR environment variables. .ie n .IP """PATH"", ""Path"" (\fIStr\fR; \fIsrc/core.c/IO/Spec/\fR)" 4 .el .IP "\f(CWPATH\fR, \f(CWPath\fR (\fIStr\fR; \fIsrc/core.c/IO/Spec/\fR)" 4 .IX Item "PATH, Path (Str; src/core.c/IO/Spec/)" The \f(CW\*(C`IO::Spec::Unix.path\*(C'\fR method splits \f(CW$PATH\fR as a shell would; i.e. as a colon-separated list. \f(CW\*(C`IO::Spec::Cygwin\*(C'\fR inherits this from \f(CW\*(C`IO::Spec::Unix\*(C'\fR. \f(CW\*(C`IO::Spec::Win32.path\*(C'\fR will read the first defined of either \f(CW\*(C`%PATH%\*(C'\fR or \f(CW\*(C`%Path%\*(C'\fR as a semicolon-delimited list. .ie n .IP """RAKUDO_SNAPPER""" 4 .el .IP \f(CWRAKUDO_SNAPPER\fR 4 .IX Item "RAKUDO_SNAPPER" Indicates the period in which the telemetry snapper will take a snapshot. Defaults to .1 for 10 snapshots per second. .ie n .IP """RAKUDO_HOME""" 4 .el .IP \f(CWRAKUDO_HOME\fR 4 .IX Item "RAKUDO_HOME" Allows to override the Raku installation path. Defaults to \&\f(CW\*(C`[rakudo_executable_dir]/../share/perl6\*(C'\fR in relocatable builds and the absolute path to that folder in non-relocatable builds. .ie n .IP """NQP_HOME""" 4 .el .IP \f(CWNQP_HOME\fR 4 .IX Item "NQP_HOME" Allows to override the NQP installation path. Defaults to \&\f(CW\*(C`[rakudo_executable_dir]/../share/nqp\*(C'\fR in relocatable builds and the absolute path to that folder in non-relocatable builds. .SH "WINDOWS PECULIARITIES" .IX Header "WINDOWS PECULIARITIES" .SS "Non-console applications" .IX Subsection "Non-console applications" On Windows programs are compiled to either be \fIconsole\fR applications or \&\fInon-console\fR applications. \fIConsole\fR applications always open a console window. There is no straightforward way to suppress this window. .PP Rakudo provides a separate set of executables suffixed with a \f(CW\*(Aqw\*(Aq\fR (\f(CW\*(C`rakuw.exe\*(C'\fR, \f(CW\*(C`rakudow.exe\*(C'\fR, ...) that are compiled as \fInon-console\fR applications. These do not spawn this console window. .PP \&\fBWARNING\fR By default these \fInon-console\fR applications will silently swallow everything that is printed to \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR. .PP To receive the output of the program it suffices to redirect it externally: .PP .Vb 1 \& rakuw.exe script.raku >stdout.txt 2>stderr.txt .Ve .SH AUTHORS .IX Header "AUTHORS" Written by the Rakudo contributors, see the CREDITS file. .PP This manual page was written by Reini Urban, Moritz Lenz and the Rakudo contributors. .PP # vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6