running.pod 5.1 KB
Newer Older
1 2 3 4 5 6
=head1 NAME

perl6 - Rakudo Perl 6 Compiler

=head1 SYNOPSIS

7
 perl6 [switches] [--] [programfile] [arguments]
8 9 10

=head1 DESCRIPTION

11 12 13
With no arguments, enters a REPL. With a C<[programfile]> or the C<-e>
option, compiles the given program and by default also executes the
compiled code.
14 15

  -c                   check syntax only (runs BEGIN and CHECK blocks)
16
  --doc                extract documentation and print it as text
17
  -e program           one line of program, strict is enabled by default
18
  -h, --help           display this help text
19 20
  -n                   run program once for each line of input
  -p                   same as -n, but also print $_ at the end of lines
21 22
  -I path              adds the path to the module search path
  -M module            loads the module prior to running the program
23
  --target=[stage]     specify compilation stage to emit
24
  --optimize=[level]   use the given level of optimization (0..3)
25
  --encoding=[mode]    specify string encoding mode
26
  -o, --output=[name]  specify name of output file
27
  -v, --version        display version information
28
  --stagestats         display time spent in the compilation stages
29
  --ll-exception       display a low level backtrace on errors
30
  --profile            write profile information as HTML file (MoarVM)
31 32
  --profile-filename   provide a different filename (also allows .json)
  --doc=[module]       Use Pod::To::[module] to render inline documentation.
33

34
Note that only boolean single-letter options may be bundled.
35

36
The supported values for C<--target> are:
37

38 39 40 41 42
 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)
43

44 45
 mbc        MoarVM   MoarVM byte code
 jar        JVM      JVM archive
46

47 48
For C<--profile-filename>, specifying a name ending in C<.json> will write a raw JSON profile dump.
The default if this is omitted is C<profile-I<[timestamp]>.html>.
49

50 51 52 53 54 55
=head1 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.

=head2 Module Loading
56 57 58

=over

59 60 61 62 63 64 65
=item C<RAKUDOLIB>, C<PERL6LIB> (I<Str>; F<src/core/Inc.pm>)

Appends a comma-delimited list of paths to C<@INC>. C<RAKUDOLIB> is evaluated first.

=item C<RAKUDO_MODULE_DEBUG> (I<Bool>; F<src/Perl6/ModuleLoader.pm>)

Causes the module loader to print debugging information to standard error.
66

67 68 69 70 71
=back

=head2 Error Message Verbosity and Strictness

=over
72

73
=item C<RAKUDO_NO_DEPRECATIONS> (I<Bool>; F<src/core/Deprecations.pm>)
74

75
If true, suppresses deprecation warnings triggered by the C<is DEPRECATED> trait.
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
=item C<RAKUDO_DEPRECATIONS_FATAL> (I<Bool>; F<src/core/Deprecations.pm>)

If true, deprecation warnings become thrown exceptions.

=item C<RAKUDO_VERBOSE_STACKFRAME> (I<UInt>; F<src/core/Backtrace.pm>)

Displays source code in stack frames surrounded by the specified number of lines of context.

=item C<RAKUDO_BACKTRACE_SETTING> (I<Bool>; F<src/core/Backtrace.pm>)

Controls whether .setting files are included in backtraces.

=back

=head2 Affecting Precompilation

=over

=item C<RAKUDO_PREFIX> (I<Str>; F<src/core/CompUnit/RepositoryRegistry.pm>)

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.

=item C<RAKUDO_PRECOMP_DIST> (F<src/core/CompUnit/PrecompilationRepository.pm>)

=item C<RAKUDO_PRECOMP_LOADING> (F<src/core/CompUnit/PrecompilationRepository.pm>)

=item C<RAKUDO_PRECOMP_WITH> (F<src/core/CompUnit/PrecompilationRepository.pm>)

These are internal variables for passing serialized state to precompilation jobs in child processes.
Please do not set them manually.

=back

=head2 Other

=over

=item C<RAKUDO_ERROR_COLOR> (I<Bool>; F<src/core/Exception.pm>)
118 119 120 121

Controls whether to emit ANSI codes for error highlighting. Defaults to true if unset, except on
Win32.

122
=item C<RAKUDO_MAX_THREADS> (I<UInt>; F<src/core/ThreadPoolScheduler.pm>)
123

124
Override the default maximum number of threads used by a thread pool.
125

126
=item C<TMPDIR>, C<TEMP>, C<TMP> (I<Str>; F<src/core/IO/Spec/>)
127

128 129
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'>.
130

131 132
C<IO::Spec::Cygwin> and C<IO::Spec::Win32> use more Win32-appropriate lists which also include the
C<%TEMP%> and C<%TMP%> environment variables.
133

134
=item C<PATH>, C<Path> (I<Str>; F<src/core/IO/Spec/>)
135

136 137
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>.
138

139 140
C<IO::Spec::Win32.path> will read the first defined of either C<%PATH%> or C<%Path%> as a
semicolon-delimited list.
141

142 143
=back

144 145 146 147 148 149
=head1 AUTHORS

Written by the Rakudo contributors, see the CREDITS file.

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