Rakudo ====== Rakudo is a compiler and runtime for the Raku programming language. This package includes the Rakudo compiler and the module installer Zef. Contents ======== - Set-Env - Running Raku - Installing Modules - Native Code Modules - PATH - Preventing Garbled Text Output - Non-Console Applications - Changes - Where to Get Help or Answers to Questions - Reporting Bugs - Submitting Patches Set-Env ======= This package provides a script to set up a terminal window to work nicely with Raku. It - sets up the PATH variable to contain BOTH paths necessary to directly call `raku` and Raku scripts such as `zef`, - searches for a C build toolchain and if found activates it, so installing modules which compile some C code works and - changes the codepage to UTF-8 so input and output of unicode characters doesn't break. See the following sections for a deeper explanation why all of this is necessary and how to do it manually. To run `set-env` execute the following in CMD: C:\path\to\this\folder\scripts\set-env.bat or when using Powershell (note the dot at the beginning): . C:\path\to\this\folder\scripts\set-env.ps1 Running Raku ============ Once your terminal is set up you can start an interactive Raku environment by typing raku.exe To run a Raku script type raku.exe my_script.raku Installing Modules ================== To install Raku modules you can use the Zef module installer. zef install JSON::Fast Modules will be installed into this Raku package and will thus be available even when moving this package. Native Code Modules ------------------- To install modules that require a compiler toolchain, you need to have the Microsoft Visual C compiler installed. The freely available Microsoft BuildTools contain that compiler. You can use the installer script C:\path\to\this\folder\scripts\vs_build_tools_install_assistant.ps1 to guide you through the installation. Alternatively you can install the BuildTools manually. They can be downloaded [here](https://aka.ms/vs/stable/vs_BuildTools.exe). You'll need to select the `C++ build tools` and recommended components. The compiler is only usable in a special Build Tools CMD / PowerShell window. Once the BuildTools are installed you should see new entries in the start menu: Start Menu -> Visual Studio 20XX -> x64 Native Tools Command Prompt for VS The `set-env` script automatically sets up the terminal for BuildTools as well. PATH ==== THERE IS MORE THAN ONE FOLDER YOU NEED TO ADD TO YOUR PATH! `raku` and it's associated programs are located in the `bin\` subfolder. Installed Raku scripts, including `zef`, are located in the `share\perl6\site\bin\` subfolder. So both need to be in your PATH. Preventing Garbled Text Output ============================== First a bit of background. Windows supports two types of text encoding that applications can choose from. The ancient `Codepage based` approach - texts are made up of 8-bit bytes. The configured codepage determines how to decode those bytes. Different languages bring their own codepages with the characters they need. Later came the newer `Unicode based` approach - texts are made up of 16-bit shorts, no codepages are necessary anymore as the characters of most languages fit into those 16 bits. The approach is still a bit limited as a lot more, but not all unicode characters fit into those 16 bits. For that and many other reasons, UTF-8 came to be. That's an 8-bit based encoding where characters can, but don't need to use more than one byte. Most modern applications use UTF-8. On Windows UTF-8 based applications are once again codepage based, but use a special Codepage - 65001 - that represents UTF-8. The default codepage is sadly not 65001, but some other codepage depending on the language of Windows. This is so as to not break compatibility with ancient applications using that other codepage. When using a UTF-8 application with a wrong codepage, the text output you see is garbled. Raku is such a UTF-8 application. Thus when using Raku in a console window with a non-UTF-8 codepage input and output of Unicode characters will break. So how to solve this? In a CMD window execute `chcp 65001` to set the codepage. You have to execute this every time you open a new CMD window. In a Powershell window execute $OutputEncoding = [console]::InputEncoding = [console]::OutputEncoding = New-Object System.Text.UTF8Encoding to set the codepage. Once again you have to do this every time you open a new window. To do that automatically, add the above line to your Powershell profile. It's also possible to configure the UTF-8 codepage globally in Windows, but that's a beta feature and breaks backward compatibility with a few legacy command line applications. In the Windows System Settings navigate here: Settings --> Time & language --> Language & region --> Administrative language settings --> Change system locale Then check `Beta: Use Unicode UTF-8 for worldwide language support` and restart the computer. Last but not least, the `set-env.ps1` and `set-env.bat` scripts perform the respective commands automatically. Non-Console Applications ======================== On Windows programs are compiled to either be _console_ applications or _non-console_ applications. _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 'w' (`rakuw.exe`, `rakudow.exe`, ...) that are compiled as _non-console_ applications. These do not spawn this console window. **WARNING** These _non-console_ applications do not have their `STDIN`, `STDOUT` and `STDERR` attached. Trying to write to these handles will cause the application to abort. One can place the following snippet at the top of a program to have all its output be silently ignored instead. $*OUT=$*ERR=class {method print(*@args){}}; **WARNING** By default these _non-console_ applications will silently swallow everything that is printed to `STDOUT` and `STDERR`. To receive the output of the program it suffices to redirect it externally: rakuw.exe script.raku >stdout.txt 2>stderr.txt Changes ======= Recent changes and feature additions are documented in the `docs/ChangeLog` text file. Where to Get Help or Answers to Questions ========================================= There are several mailing lists, IRC channels, and wikis available with help for Raku and Rakudo. Figuring out the right one to use is often the biggest battle. Here are some rough guidelines: The central hub for Raku information is [raku.org](https://raku.org/). This is always a good starting point. If you have a question about Raku syntax or the right way to approach a problem using Raku, you probably want the “perl6-users@perl.org” mailing list or the [irc.libera.chat/#raku IRC channel](https://web.libera.chat/#raku). The perl6-users list is primarily for the people who want to use Raku to write programs, so newbie questions are welcomed there. Newbie questions are also welcome on the #raku channel; the Rakudo and Raku development teams tend to hang out there and are generally glad to help. There's a Raku news aggregator at [Planet Raku](https://planet.raku.org/). Questions about NQP can also be posted to the #raku IRC channel. For questions about MoarVM, you can join #moarvm on Libera. Reporting Bugs ============== See https://rakudo.org/issue-trackers Submitting Patches ================== If you have a patch that fixes a bug or adds a new feature, please create a pull request using GitHub's pull request infrastructure. See [our contribution guidelines](https://github.com/rakudo/rakudo/blob/master/CONTRIBUTING.md) for more information. License ======= Rakudo is Copyright © 2008-2025, The Raku Foundation. Rakudo is distributed under the terms of the Artistic License 2.0. For more details, see the full text of the license in the file LICENSE. Authors ======= See CREDITS for the many people that have contributed to the development of the Rakudo compiler.