-
Notifications
You must be signed in to change notification settings - Fork 292
/
03-environment-variables.rakudoc
204 lines (143 loc) · 7.51 KB
/
03-environment-variables.rakudoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
=begin pod :kind("Programs") :subkind("programs") :category("programs")
=TITLE Environment variables used by the C<raku> command line
=SUBTITLE How to run Rakudo, a Raku implementation, and modify its behavior
with 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<|Programs,RAKUDOLIB>X<|Programs,RAKULIB>X<|Programs,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<|Programs,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<|Programs,RAKU_EXCEPTIONS_HANDLER>
X<|Programs,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<|Programs,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<|Programs,RAKUDO_DEPRECATIONS_FATAL>
=item C<RAKUDO_DEPRECATIONS_FATAL> (I<Bool>; B<src/core.c/Deprecations.pm6>)
If true, deprecation warnings become thrown exceptions.
X<|Programs,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<|Programs,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<|Programs,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<|Programs,RAKUDO_PRECOMP_DIST>
=item C<RAKUDO_PRECOMP_DIST> (B<src/core.c/CompUnit/PrecompilationRepository.pm6>)
X<|Programs,RAKUDO_PRECOMP_LOADING>
=item C<RAKUDO_PRECOMP_LOADING> (B<src/core.c/CompUnit/PrecompilationRepository.pm6>)
X<|Programs,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<|Programs,RAKUDO_LOG_PRECOMP>
=item C<RAKUDO_LOG_PRECOMP>
If set to 1, diagnostic information about the precompilation process is
emitted.
=head2 Line editor
X<|Programs,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<|Programs,RAKUDO_DISABLE_MULTILINE>
=item C<RAKUDO_DISABLE_MULTILINE>
If set to 1, will disable multiline input for the REPL.
X<|Programs,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<|Programs,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<|Programs,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<|Programs,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 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 "B<unlimited>" or "B<Inf>" to indicate that the number of threads
available by the operating system, will be the limiting factor.
X<|Programs,TMPDIR>X<|Programs,TEMP>X<|Programs,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<|Programs,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<|Programs,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<|Programs,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<|Programs,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<|Programs,rakuw.exe>X<|Programs,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
=end pod