__        ___                         
          ____________  |  | ____ _\  |_________   ______  _  __
          \_  __ \__  \ |  |/ /  |  \ __ \_  __ \_/ __ \ \/ \/ /
           |  | \// __ \|    <|  |  / \_\ \  | \/\  ___/\     / 
           |__|  (______/__|__\____/|_____/__|    \_____>\/\_/  
                                                              v39                         __
          ____________  |  | ____ __
          \_  __ \__  \ |  |/ /  |  \
        ___|  | \// __ \|    <|  |  /
        \  |__|__(______/__|__\____/_
         | __ \_  __ \_/ __ \ \/ \/ /
         | \_\ \  | \/\  ___/\     / 
         |_____/__|    \_____>\/\_/  
                                   v39  rakubrew
     v39

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