TITLE

SUBTITLE

head

Program C<rakudoc> is a command-line-interface (CLI) program that reads
Raku pod from B<installed> modules' source code, in contrast to
running C<raku --doc=MODULE programfile> which reads Raku pod from
the named source file.


Note that C<rakudoc> may not be installed automatically depending upon
how you installed Rakudo Raku.  To install it use C<zef>:


code

With no switches or arguments, C<rakudoc> lists its help to C<$*OUT> (C<stdout>).
For C«rakudoc:ver<0.2.5>», this output is:


=begin code :lang<output>
Usage:
  rakudoc [-d|--doc-sources=<Directories>] [-D|--no-default-docs] <query>
  rakudoc -b|--build-index [-d|--doc-sources=<Directories>] [-D|--no-default-docs]
  rakudoc -V|--version
  rakudoc -h|--help <ARGUMENTS>

    <query>                           Example: 'Map', 'IO::Path.add', '.add'
    -d|--doc-sources=<Directories>    Additional directories to search for documentation
    -D|--no-default-docs              Use only directories in --doc-sources / $RAKUDOC
    -b|--build-index                  Index all documents found in doc source directories
=end code


The text output can be captured and converted to other forms if desired.


If you want to use ANSI escape sequences, which will apply boldface
and other enhancements when the output is printed to a terminal, you
will have to set the environment variable POD_TO_TEXT_ANSI, which is
unset by default


Currently C<rakudoc> can only extract embedded Raku pod from installed
module source files (as listed in a distribution's C<META6.json>
file).  It is planned to add a feature for C<rakudoc> (in conjunction
with C<META6.json> changes) to extract B<all> Raku pod in files
included with the installed distribution.


root

Modules and applications used to debug Raku programs


Debugging


How to run Rakudo, a Raku implementation, and modify its behavior
with environment variables.


Environment variables used by the raku command line


How to run Rakudo, a Raku implementation, and the command line
options you can use with it.


Running Raku


rakudoc - the Raku pod reader


para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

Reading the docs


Environment variables used by the C<raku> command line


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


Affecting execution from the command line


item

Available as of the 2022.02 Rakudo compiler release.


The C<RAKUDO_OPT> environment variable provides a way to specify default
compiler command line options, overridable by explicitly specifications
on the command line. For example:


would ignore the C<-I.> but would honor the C<--ll-exception> command
line argument.


A simple space splitter is used to separate arguments, making it impossible
to use arguments with spaces in them.


X<|Programs,RAKUDOLIB>X<|Programs,RAKULIB>X<|Programs,PERL6LIB>


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.


If true, causes the module loader to print debugging information to standard
error.


X<|Programs,RAKUDO_PRECOMPILATION_PROGRESS>


Available as of the 2012.12 release of the Rakudo compiler.


If true, causes the module loader to print the names of modules that are being
re-precompiled on standard error.  As such it is a simplified version of the
functionality offered by C<RAKUDO_MODULE_DEBUG>.


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.


Available as of the 2020.01 release of the Rakudo compiler.  Before that it
was available as C<PERL6_EXCEPTIONS_HANDLER> (which was removed in the
2023.04 release of the Rakudo compiler).


Intended to be used by environments that embed the Raku Programming Language,
such as IDEs.


If true, suppresses deprecation warnings triggered by the C<is DEPRECATED>
trait.


If true, deprecation warnings become thrown exceptions.


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.


Controls whether C<.setting> files are included in backtraces.


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.


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


If set to 1, diagnostic information about the precompilation process is
emitted.


If set to 1, precompilation will be disabled. Available as of the 2023.08
release of the Rakudo compiler.


The C<trace> pragma causes the program to print out step-by-step which
lines get executed:


use trace;
sub foo { say "hi" }
foo;
# OUTPUT:
# 2 (/tmp/script.raku line 2)
# sub foo { say "hi" }
# 5 (/tmp/script.raku line 3)
# foo
# 3 (/tmp/script.raku line 2)
# say "hi"
# hi


N<This routine is a Rakudo-specific debugging feature and not
standard Raku.>


The I<Tiny Data Dumper>: This function takes the input list of variables
and C<note>s them (on C<$*ERR>) in an easy to read format, along with
the C<name> of the variable.  For example, this prints to the standard
error stream the variables passed as arguments:


=begin code :ok-test<dd>
my $a = 42;
my %hash = "a" => 1, "b" => 2, "c" => 3;

dd %hash, $a;
#`( OUTPUT:
    Hash %hash = {:a(1), :b(2), :c(3)}
    Int $a = 42
)
=end code


Please note that C<dd> will ignore named parameters. You can use a
L<C<Capture>|/type/Capture> or L<C<Array>|/type/Array> to force it to dump everything passed to it.


=begin code :ok-test<dd>
dd \((:a(1), :b(2)), :c(3));
dd [(:a(1), :b(2)), :c(3)];
=end code


If you don't specify any parameters at all, it will just print the type
and name of the current subroutine / method to the standard error
stream:


=begin code :ok-test<dd>
sub a { dd }; a   # OUTPUT: «sub a()␤»
=end code


This can be handy as a cheap trace function.


The L<C<Backtrace>|/type/Backtrace> class gets the current call stack, and can return it as
a string:


my $trace = Backtrace.new;
sub inner { say ~Backtrace.new; }
sub outer { inner; }
outer;


# OUTPUT:
# raku /tmp/script.raku
#   in sub inner at /tmp/script.raku line 2
#   in sub outer at /tmp/script.raku line 3
#   in block <unit> at /tmp/script.raku line 4


See L<Raku Environment
Variables|https://github.com/rakudo/rakudo/wiki/dev-env-vars> and
L<Running rakudo from the command
line|https://github.com/rakudo/rakudo/wiki/Running-rakudo-from-the-command-line>
for more information.


There are at least two useful debuggers and two tracers available for Rakudo
(the Raku compiler).  For more information on these modules, please refer to
their documentation.


Historically other modules have existed and others are likely to be
written in the future. Please check the L<Raku
Modules|https://raku.land/> website for more modules like these.


L<C<Debugger::UI::CommandLine>|https://raku.land/github:jnthn/Debugger::UI::CommandLine>


A command-line debugger frontend for Rakudo. This module installs the
C<raku-debug-m> command-line utility, and is bundled with the Rakudo
Star distributions. Please check
L<its repository|https://github.com/jnthn/rakudo-debugger>
for instructions and a tutorial.


L<C<Grammar::Debugger>|https://raku.land/github:jnthn/Grammar::Debugger> (and C<Grammar::Tracer> in the same distribution)


Simple tracing and debugging support for Raku grammars.


L<C<Trait::Traced>|https://raku.land/cpan:KAIEPI/Trait::Traced>


This provides the C<is traced> trait, which automatically traces usage of
features of whatever the trait is applied to. What features of whatever the
trace is applied to get traced and how traces are handled are customizable.
Refer to its documentation for more information on how this works.


The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


Reading the docs

INTRODUCTION

SYNOPSIS

DESCRIPTION

LIMITATIONS

See Also