+----------v---------v-------+ | Unix-ish | Windows | MacOS | +----------^---------^-------+ rakubrew (called rakudobrew in a previous life) is a [Raku][1] installation tool. It allows you to have multiple versions of different Raku implementations installed in parallel and switch between them. It's a [perlbrew][2] and [plenv][3] look alike and supports both flavours of commands. Features ======== - Works about anywhere - Windows, MacOS, Linux, BSD - Powershell, CMD, Bash, Zsh, Fish, ... - No dependencies except Perl on Unixy machines - Can get Raku installed and running in seconds - Autocomplete Installation ============ Just copy and paste the following piece of code into a console. curl https://rakubrew.org/install-on-perl.sh | sh Bare bones installation ======================= If the above installation script somehow doesn't work for you, you can install rakubrew manually. First download the rakubrew executable: https://rakubrew.org/perl/rakubrew Then give that file executable permissions: chmod +x rakubrew Add the rakubrew and shim folders to your `PATH`: # Bash & ZSH export PATH=/path/where/rakubrew/is:$PATH export PATH=$(rakubrew home)/shims:$PATH # Fish fish_add_path -g /path/where/rakubrew/is fish_add_path -g (rakubrew home)/shims Finally run rakubrew mode shim That's all! Shell hook ---------- If you want to use `env` mode, the `shell` command or have auto-completion, you need to install the shell hook. To get the instructions on how to do that type rakubrew init Installation path ----------------- To make rakubrew use a different directory to store its files set the `RAKUBREW_HOME` environment variable prior to calling it. Put the following into your `.bashrc` or similar: export RAKUBREW_HOME=~/rakubrew # or some other path CPAN ---- Installation via [CPAN][4] is possible as well. Just use your favorite CPAN client to install `App::Rakubrew`. cpanm App::Rakubrew How === # list available versions rakubrew available # download and install the latest Rakudo on MoarVM version rakubrew download # switch to use that version (substitute the version you just installed) rakubrew switch moar-2019.11 raku -e 'say "Now running {$*RAKU.compiler.version}!"' global, shell, local ==================== rakubrew knows three different versions that can be set separately. The `global` version is the one that is selected when neither the `shell` version nor the `local` version are active. The `shell` version changes the active Raku version just in the current shell. Closing the current shell also looses the `shell` version. The `local` version is specific to a folder. When CWD is in that folder or a sub folder that version of Raku is used. Only works in `shim` mode. To unset a local version one must delete the `.RAKU_VERSION` file in the respective folder. Modes ===== rakubrew can work in two distinct modes: `env` and `shim` In `env` mode rakubrew modifies the `$PATH` variable as needed when switching between versions. This is neat because one then runs the executables directly. This is the default mode on *nix. In `shim` mode rakubrew generates wrapper scripts called shims for all executables it can find in all the different Raku installations. These shims forward to the actual executable when called. This mechanism allows for some advanced features, such as local versions. When installing a module that adds scripts one must make rakubrew aware of these new scripts. This is done with rakubrew rehash In `env` mode this is not necessary. Registering external versions ============================= To add a Raku installation to rakubrew that was created outside of rakubrew one should do: rakubrew register name-of-version /path/to/raku/install/directory Upgrading ========= rakubrew self-upgrade Uninstall ========= To remove rakubrew and any Raku implementations it has installed on your system, delete the `~/.rakubrew` and `~/.local/share/rakubrew` directories. Automation ========== Rakubrew is designed as a tool to be used by humans. Using it in automated workflows usually brings no benefit over building or downloading a Rakudo directly. To download and activate a pre-compiled Rakudo (which already includes Zef) the following few commands are a good fit: VER=2020.07 BUILD_REV=01 NAME=rakudo-moar-$VER-$BUILD_REV-linux-x86_64-gcc curl -o $NAME.tar.gz https://rakudo.org/dl/rakudo/$NAME.tar.gz tar -xzf $NAME.tar.gz rm $NAME.tar.gz eval "$($NAME/scripts/set-env.sh --quiet)" To build and activate a Rakudo and Zef: VER=2020.07 INST_DIR=/home/me/rakudo NAME=rakudo-$VER mkdir INST_DIR curl -o $NAME.tar.gz https://rakudo.org/dl/rakudo/rakudo-$VER.tar.gz tar -xzf $NAME.tar.gz pushd $NAME perl Configure.pl --gen-moar --make-install --prefix=$INST_DIR PATH=$INST_DIR/bin:$INST_DIR/share/perl6/site/bin:$PATH git clone https://github.com/ugexe/zef.git cd zef raku -I. bin/zef install . popd rm -rf $NAME.tar.gz $NAME Common Errors ============= Git not found ------------- In case your git binary is not in the `PATH` on your system, you can specify a custom path to the git binary using the `GIT_BINARY` environment variable: GIT_BINARY="%USERPROFILE%\Local Settings\Application Data\GitHub\ PORTAB~1\bin\git.exe" rakubrew build all Git clone failing ----------------- When git fails to clone any repositories, it might be you are sitting behind a firewall that blocks the network protocol / port git uses by default. You can change the protocol to something that will usually be acceptable to firewalls by setting the `GIT_PROTOCOL` environment variable: # for https GIT_PROTOCOL=https rakubrew list-available # for ssh GIT_PROTOCOL=ssh rakubrew list-available Build failing, build dir with spaces ------------------------------------ Rakudo can currently not be built in a directory that contains spaces. As a result the `rakubrew build` and `rakubrew triple` commands also can't work when rakubrew is installed in a directory with spaces in the path. To circumvent this limitation change the rakubrew home to a different path that contains no spaces. See the `Installation path` paragraph above for instructions on how to do so. "rakubrew" cannot be opened because the developer cannot be verified -------------------------------------------------------------------- If you observe an error message similar to this "rakubrew" cannot be opened because the developer cannot be verified. macOS cannot verify that this app is free from malware. Chrome downloaded this file today at 10:08 AM from rakubrew.org then MacOS is blocking you from running rakubrew, because `rakubrew` is an unsigned executable. To solve this you need to open the `rakubrew` executable according to the instructions at https://support.apple.com/guide/mac-help/open-a -mac-app-from-an-unidentified-developer-mh40616. Why don't we sign the rakubrew executable? Sadly signing executables requires an Apple Developer Program account, which costs $99 per year. I do not want to pay that yearly fee for publishing a free and open source application. (I don't even own a Mac!) So we'll just have to live with unsigned executables and the above inconvenience for the time being. Command-line switches ===================== `version` or `current` ---------------------- Show the currently active Raku version. `versions` or `list` -------------------- List all installed Raku installations. `global [version]` or `switch [version]` ---------------------------------------- Show or set the globally configured Raku version. `shell [--unset|version]` ------------------------- Show, set or unset the shell version. `local [--unset|version]` ------------------------- Show, set or unset the local version. `nuke [version]` or `unregister [version]` ------------------------------------------ Removes an installed or registered version. Versions built by rakubrew are actually deleted, registered versions are only unregistered but not deleted. `rehash` -------- Regenerate all shims. Newly installed scripts will not work unless this is called. This is only necessary in `shim` mode. `list-available` or `available` ------------------------------- List all Rakudo versions that can be installed. Installed versions will be marked with an asterisk at the beginning of the line. Releases marked with a 'D' have a precompiled archive available and can be downloaded and installed without compilation with the `download` subcommand. `build[-rakudo] [jvm|moar|moar-blead|all] [tag|branch|sha-1] [--configure-opts=]` --------------------------------------------------------------------------------- Download, compile and install a Rakudo version. Please note that this can take a while, be patient. The arguments are: - The backend. - `moar-blead` is the moar and nqp backends at their main branch. - `all` will build all backends. - The version to build. Call `list-available` to see a list of available versions. When left empty the latest release is built. It is also possible to specify a commit sha or branch to build. It is also possible to specify a tag, branch name or commit sha in the `rakudo` repo. - Configure options. Do note that it's not possible to specify a different installation folder with `--prefix`. If you want a rakudo to be installed into a different folder, build it manually and then use `rakubrew register` to have it available in Rakubrew. `triple [rakudo-ver [nqp-ver [moar-ver]]]` ------------------------------------------ Build a specific set of Rakudo, NQP and MoarVM commits. `register <name> <path>` ------------------------ Register an externaly built / installed Raku version with rakubrew. `build-zef [<zef-version>]` ------------------------- Install Zef (at the given version) into the current Rakudo version. `download[-rakudo] [<%backends%>] [<rakudo-version>]` ----------------------------------------------------- Download and install a precompiled release archive. `exec [--with <version>] <command> [command-args]` -------------------------------------------------- Explicitly call an executable. You normally shouldn't need to do this. You can optionally pass a version string to execute a command in a specific version. `which <command>` ----------------- Show the full path to the executable. `whence [--path] <command>` --------------------------- List all versions that contain the given command. when `--path` is given the path of the executables is given instead. `mode [env|shim]` ----------------- Show or set the mode of operation. `self-upgrade` -------------- Upgrade rakubrew. `init` ------ Show installation instructions. `test [version|all]` -------------------- Run tests in the current or given version. `help [--verbose|<command>]` ---------------------------- Display an overview of rakubrew commands. Add a specific command to display instructions for that command. Print the entire manual with the `--verbose` flag. `home` ------ Display the currently configured rakubrew home directory. `rakubrew-version` ------------------ Display the version of this rakubrew installation and some other information helpful for debugging. Include this information when you report a bug. Bugs 'n' Development ==================== rakubrew is developed on [GitHub][5]. To report a bug, head over there and create a new issue. The sources of this website are maintained in a separate [GitHub repository][6]. Authors ======= - Patrick Böker (large rewrite and current maintainer) - Tadeusz Sośnierz (original author) [1]: https://raku.org/ [2]: https://perlbrew.pl/ [3]: https://github.com/tokuhirom/plenv [4]: https://metacpan.org/pod/App::Rakubrew [5]: https://github.com/Raku/App-Rakubrew/ [6]: https://github.com/Raku/rakubrew.org