+----------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=]`
---------------------------------------------------------------------------------
Build a Raku version. The arguments are:
- The backend.
- `moar-blead` is the moar and nqp backends at the master 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.
- Configure options.
`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 <command> [command-args]`
-------------------------------
Explicitly call an executable. You normally shouldn't need to do this.
`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