Raku

Warning: This article is in an early stage.

Installing Rakudo and zef

Rakudo is the preferred implementation of Raku, and the zef the preferred module manager. Install them in a nix shell via

nix-shell -p rakudo zef

or install them permanently system-wide by adding pkgs.rakudo and pkgs.zef to your NixOS configuration file.

To create a Nix user environment on NixOS, run

nix-env -iA nixos.rakudo nixos.zef

(For environments or flakes on non-NixOS machines, different recommendations apply.)

No Nix packages currently exist for the Rakudo Star distribution, which bundles Rakudo with a collection of modules and the language documentation. Thus, to use it, you need to download and compile it. This has the additional advantage of always giving you the latest version of Rakudo.

Making the Readline library available

When opening an interactive environment (by running rakudo, or its symlink raku, without arguments), you may get an error message like this:

I ran into a problem while trying to set up Readline: Could not instantiate role 'ReadlineBehavior'; exception details:
  Cannot locate native library 'libreadline.so.7': libreadline.so.7: cannot open shared object file: No such file or directory
  in method setup at [...]
Falling back to Linenoise (if present)
No line editor found.

You may want to exit first and `zef install Readline`, `zef install
Linenoise`, or `zef install Terminal::LineEditor` or install `rlwrap`
for a line editor before entering the REPL again.

With this error, Readline and its functions such as command history and cursor movement will not be available. To fix it, tell Raku the location of your Readline library by appending or prepending its directory path to the environment variable $LD_LIBRARY_PATH. This can be done by adding the following code to your NixOS configuration (and then rebuilding and logging out and back in):

{
  #...
  environment.sessionVariables = rec {
    LD_LIBRARY_PATH = pkgs.lib.makeLibraryPath [ 
      pkgs.readline70
    ];
  };
  #...
}

For Nix shells, see for instance this example.

Setting up the Debugger

Alongside rakudo ships the binary rakudo-debug. In order to be able to use it, you'll likely have to run

zef install Debugger::UI::CommandLine

This seems to work fine with the packages provided for NixOS.

If, on the other hand, you're using a Rakudo Star distribution compiled by yourself, you may get the error Could not find Terminal::ANSIColor in: [list of paths], but attempting to install this module via zef install Terminal::ANSIColor reports that it's already installed. One way around this is to first uninstall it and then retry the original command:

# alias zef="path/to/rakudo-star-2025.XY/share/perl6/site/bin/zef"
zef uninstall Terminal::ANSIColor
zef install Debugger::UI::CommandLine

Since the first module is a dependency of the latter, it will get re-installed along the way.

Various Modules

Cro, OpenSSL

When trying to zef install Cro::HTTP or only its dependency OpenSSL, you may get the error

Cannot locate native library 'libssl.so': libssl.so: cannot open shared object file: No such file or directory

Resolving this error can be done similarly as for the Readline library:

{
  #...
  environment.sessionVariables = rec {
    LD_LIBRARY_PATH = pkgs.lib.makeLibraryPath [ 
      # pkgs.readline70, etc...
      pkgs.openssl
      pkgs.openssl.dev # compare https://nixos.org/manual/nixpkgs/stable/#chap-multiple-output
    ];
  };
  #...
}

Then rebuild, open a new TTY and try again. A cleaner way than this global configuration, especially once you go about packaging things, could be via a Nix shell. (Compare FAQ: I installed a library but my compiler is not finding it. Why?) For example, add the lines pkgs.openssl and pkgs.openssl.dev in this example where currently pkgs.readline70 stands.

You can also try

nix-shell -p git cmake gcc openssl openssl.dev
zef install Cro::HTTP

and then test success e.g. via use Cro::HTTP::Client in the Raku REPL.

LibCurl

Trying to install LibCurl may also result in a complaint about missing dependencies. The error message is not quite the same as with the OpenSSL example.

$ zef install LibCurl
===> Searching for: LibCurl
===> Searching for missing dependencies: curl:ver<4>:from<native>
===> Failed to find dependencies: curl:ver<4>:from<native>
Failed to resolve some missing dependencies (use e.g. --exclude="curl" to skip)

If you know a clean way to resolve this, please share it here. For now, here's an ugly way:

$ find /nix -name libcurl.so.4\*
...
/nix/store/aw9m5pswamgx2sck6isg4pr1ly1i0b1l-curl-8.4.0/lib/libcurl.so.4
... 
$ echo $LD_LIBRARY_PATH
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/nix/store/aw9m5pswamgx2sck6isg4pr1ly1i0b1l-curl-8.4.0/lib
$ zef install LibCurl

If it fails, retry with other paths output by the find command. (People have experienced the same type of issue when trying to zef install LibCurl on Android. They resolved it by symlinking to a suitable libcurl.so.4 library.)

Resources

• Various examples for Raku Nix Shells: https://github.com/rcmlz/Raku-Nix-Shells