Perl 6

perl6 - the Rakudo Perl 6 Compiler's switches and environment variables

SYNOPSIS

 perl6 [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.

  Option               Purpose
  ======               ==============================================
  -c                   check syntax only (runs BEGIN and CHECK blocks)
  --doc                extract documentation and print it as text
  -e program           one line of programstrict is enabled by default
  -h--help           display this help text
  -n                   run program once for each line of input
  -p                   same as -nbut 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[=kind]     write profile information to an HTML file (MoarVM)
                         instrumented - performance measurements (default)
                         heap - record heap snapshots after every
                                garbage collector run
  --profile-filename=name
                       provide a different filename for profile. Extension
                       controls format:
                            .json outputs in JSON
                            .sql  outputs in SQL
                            any other extension outputs in HTML
  --doc=module         use Pod::To::[moduleto render inline documentation
 

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

To modify the include path, you can set the PERL6LIB environment variable:

PERL6LIB="lib" perl6 example.pl

The include path will be searched recursively for any modules when Rakudo is started. Directories that start with a dot are ignored and symlinks are followed.

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-I<[timestamp]>.html.

For examples, and notes about correct quoting on Windows, see "Perl 6 One Liners".

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.

Other variables are listed in Rakudo's github wiki: https://github.com/rakudo/rakudo/wiki/dev-env-vars.

Module Loading

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

RAKUDO_MODULE_DEBUG (Bool; src/Perl6/ModuleLoader.pm) Causes the module loader to print debugging information to standard error.

Error Message Verbosity and Strictness

RAKUDO_EXCEPTIONS_HANDLER (Str; src/core/Exception.pm) Specifies the name of a custom exceptions handler. For example, to load and use Exceptions::JSON class that comes with Rakudo, set this env var to JSON. The exception handling class needs to implement method process that takes a single positional argument: the exception object. If that method returns a truthy value, the exception will also be printed to the terminal, as if the exception handler was not specified.

RAKUDO_NO_DEPRECATIONS (Bool; src/core/Deprecations.pm) If true, suppresses deprecation warnings triggered by the is DEPRECATED trait.

RAKUDO_DEPRECATIONS_FATAL (Bool; src/core/Deprecations.pm) If true, deprecation warnings become thrown exceptions.

RAKUDO_VERBOSE_STACKFRAME (UInt; src/core/Backtrace.pm) Displays source code in stack frames surrounded by the specified number of lines of context.

RAKUDO_BACKTRACE_SETTING (Bool; src/core/Backtrace.pm) Controls whether .setting files are included in backtraces.

Affecting Precompilation

RAKUDO_PREFIX (Str; 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.

RAKUDO_PRECOMP_DIST (src/core/CompUnit/PrecompilationRepository.pm)

RAKUDO_PRECOMP_LOADING (src/core/CompUnit/PrecompilationRepository.pm)

RAKUDO_PRECOMP_WITH (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.

Other

RAKUDO_ERROR_COLOR (Bool; src/core/Exception.pm) Controls whether to emit ANSI codes for error highlighting. Defaults to true if unset, except on Win32.

RAKUDO_MAX_THREADS (UInt; src/core/ThreadPoolScheduler.pm) Override the default maximum number of threads used by a thread pool. Defaults to 16.

RAKUDO_JDB_PORT (Str; src/core/CompUnit/PrecompilationRepository.pm) In perl6-jdb-server for setting the jdb port

RAKUDO_PRECOMP_NESTED_JDB and RAKUDO_JDB_PORT (Str; src/core/CompUnit/PrecompilationRepository.pm) RAKUDO_PRECOMP_NESTED_JDB uses perl6-jdb-server with increasing ports for precompilation and RAKUDO_JDB_PORT in perl6-jdb-server is for setting the jdb port.

TMPDIR, TEMP, TMP (Str; src/core/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 Win32-appropriate lists which also include the %TEMP% and %TMP% environment variables.

PATH, Path (Str; src/core/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.

PERL6_TEST_TIMES, (Bool; lib/Test.pm6)

When set to a true value will cause timing information to be printed when the test suite is running:

    $ PERL6_TEST_TIMES=1 perl6 -MTest -e 'plan 2; is sleep(2), Nil; nok sleep(.5)'
    1..2
    # between two timestamps 1 microseconds 
    ok 1 -
    # t=2000562 
    ok 2 -
    # t=500388 

The # between two timestamps is printed when plan is called and indicates how long it takes just to read the clock to produce a timestamp. # t= values that follow are printed after each test function is executed and the value represents the time in microseconds that elapsed from the previous timestamp (or the # between... message).

Note that if you use done-testing instead of plan, the # between... message will not be displayed and the first # t= value will be a NaN.

PERL6_TEST_DIE_ON_FAIL, (Bool; lib/Test.pm6)

When set to a true value will cause the test suite to abort on first failure, even if there are more tests to be run:

    $ PERL6_TEST_DIE_ON_FAIL=1 perl6 t/test-filename.t

RAKUDO_OPTIMIZER_DEBUG, (Bool; src/Perl6/Optimizer.nqp)

When set to a true value, causes to produce extra debugging output, useful for debugging Rakudo's static optimizer.

$*DEFAULT-READ-ELEMS

Default number of bytes or chars read by .readchars and .Supply methods in IO::Handle and IO::CatHandle. Defaults to 65536 or the value of RAKUDO_DEFAULT_READ_ELEMS environmental variable, if set.