`kerl`

Easy building and installing of Erlang/OTP instances.

kerl aims to be shell agnostic (it runs in a POSIX shell) and its only dependencies, excluding what's required to actually build Erlang/OTP, are curl and git.

All is done so that, once a specific release has been built, creating a new installation is as fast as possible.

Installing kerl
How kerl works
Using kerl
kerl options
Command reference
Important notes
Shell support
The kerl glossary
The kerl project

Installing `kerl`

If you are on macOS, and using homebrew, you can install kerl, along with shell completion, by running:

$ brew install kerl

Alternatively, you can download the script directly from GitHub:

$ curl -O https://raw.githubusercontent.com/kerl/kerl/master/kerl

Then ensure it is executable

$ chmod a+x kerl

and drop it in your $PATH.

Command-line completion

Optionally, download and install kerl's:

bash_completion file from https://github.com/kerl/kerl/raw/master/bash_completion/kerl
zsh_completion file from https://github.com/kerl/kerl/raw/master/zsh_completion/_kerl
fish-completion file from https://github.com/kerl/kerl/raw/master/fish_completion/kerl.fish

depending on your preferred shell.

Updating `kerl` locally

Run:

$ kerl upgrade
Local kerl found (/usr/local/bin/kerl) at version 4.3.1.
Remote kerl found at version 4.4.0.
Versions are different. Upgrading to 4.4.0...
kerl 4.4.0 is now available at /usr/local/bin/kerl.
Updating list of available releases...
... done!

How `kerl` works

kerl keeps tracks of the releases it downloads, builds and installs, allowing easy installations to new destinations (without complete rebuilding) and easy switches between Erlang/OTP installations.

By default, kerl downloads source tarballs from the official Erlang/OTP repository but you can tell kerl to download from the official Erlang/OTP website by setting KERL_BUILD_BACKEND=tarball. However, this website does not use HTTPS and is down more often than GitHub.

You can also install directly from a raw Git repository by using the kerl build git <git_url> <git_version> <build_name> syntax.

Using `kerl`

List the available releases:

$ kerl list releases
17.5.6.10
18.3.4.11
19.3.6.13
20.3.8.26
21.3.8.24
22.3.4.27
23.3.4.20
24.3.4.17
25.3.2.21
26.2.5.12 *
27.3.4 *
28.0 *
Run 'kerl update releases' to update this list.
Run 'kerl list releases all' to view all available releases.
Note: * means "currently supported".

Pick your choice and build it:

$ kerl build 28.0 28.0
Downloading (from GitHub) Erlang/OTP 28.0 to /home/user/.kerl/archives...
Extracting source code for normal build...
Building (normal) Erlang/OTP 28.0 (28.0); please wait...
...
Erlang/OTP 28.0 (28.0) has been successfully built.

Note that named builds allow you to have different builds for the same Erlang/OTP release with different configure options:

$ KERL_BUILD_DOCS=yes kerl build 28.0 28.0-builtdocs
Extracting source code for normal build...
Building (normal) Erlang/OTP 28.0 (28.0-builtdocs); please wait...
...
Building docs...
Erlang/OTP 28.0 (28.0-builtdocs) has been successfully built.

You can verify your build has been registered:

$ kerl list builds
28.0,28.0
28.0,28.0-builtdocs

Now install a build to some location:

$ kerl install 28.0 /usr/local/lib/erlang/28.0
Installing Erlang/OTP 28.0 (28.0) in /usr/local/lib/erlang/28.0...
Building Dialyzer PLT...
Done building /usr/local/lib/erlang/28.0/dialyzer/plt.
You can activate this installation running the following command:
. /usr/local/lib/erlang/28.0/activate
Later on, you can leave the installation typing:
kerl_deactivate

Here again you can check the installation's been registered:

$ kerl list installations
28.0 /usr/local/lib/erlang/28.0

And at last activate it:

$ . /usr/local/lib/erlang/28.0/activate

Activation will backup your $PATH, and prepend it with the installation's bin/ directory. Thus it's only valid for the current shell session, and until you either activate another installation or call kerl_deactivate.

Note: alternatively you can use kerl build-install as a shortcut for the two previous actions to be played in sequence.

$ kerl build-install
usage: kerl build-install <release> [build_name] [directory]

$ kerl build-install git
usage: kerl build-install git <git_url> <git_version> <build_name> [directory]

You're now ready to work with your 28.0 installation:

$ erl -version
Erlang (SMP,ASYNC_THREADS) (BEAM) emulator version 16.0

When you're done just call the shell function:

$ kerl_deactivate

Anytime you can check which installation, if any, is currently active with:

$ kerl active
The current active installation is:
/usr/local/lib/erlang/28.0

You can get an overview of the current kerl state with:

$ kerl status
Available builds:
28.0,28.0
28.0,28.0-builtdocs
----------
Available installations:
28.0 /usr/local/lib/erlang/28.0
----------
The current active installation is:
/usr/local/lib/erlang/28.0
The Dialyzer PLT for the active installation is:
/usr/local/lib/erlang/28.0/dialyzer/plt
The build options for the active installation are:
...

You can delete builds and installations with the following commands:

$ kerl delete build 28.0-builtdocs
Build '28.0-builtdocs' has been deleted.

$ kerl delete installation 28.0
Installation '28.0' has been deleted.

You can easily deploy an installation to another host having ssh and rsync access with the following command:

$ kerl deploy anotherhost /usr/local/lib/erlang/28.0
Cloning Erlang/OTP 28.0 (/usr/local/lib/erlang/28.0) to anotherhost (/usr/local/lib/erlang/28.0)...

On anotherhost, you can activate this installation running the following command:

$ . /usr/local/lib/erlang/28.0/activate

Later on, you can leave the installation typing:

$ kerl_deactivate

Building Erlang/OTP from a GitHub fork

It is possible to build Erlang/OTP from a GitHub fork, by using the KERL_BUILD_BACKEND=git and setting OTP_GITHUB_URL to the URL of the fork. For example, to build <orgname>'s Erlang/OTP fork:

$ export KERL_BUILD_BACKEND=git
$ export OTP_GITHUB_URL='https://github.com/<orgname>/otp'
$ KERL_INCLUDE_RELEASE_CANDIDATES=yes kerl update releases
Getting releases from GitHub...
The available releases are:
...
26.0-rc3 *
26.0-rc3.1-orgname *
26.2.5.12 *
26.2.5.12.1-orgname *
27.0-rc3 *
27.0-rc3.1-orgname *
27.3.4 *
27.3.4.1-orgname *
28.0-rc4 *
28.0-rc4.1-orgname *
28.0 *
28.0.1-orgname *

Note: this list, kept in a file managed by kerl, is different depending on the build backend you use.

From here (provided the KERL_BUILD_BACKEND and OTP_GITHUB_URL variables remain in place), it is possible to use kerl as before:

$ kerl build 28.0.1-orgname 28.0.1-orgname

Building Erlang/OTP from a Git source

You can build Erlang/OTP directly from a Git repository with a command of the form kerl build git <git_url> <git_version> <build_name> where <git_version> can be either a branch, a tag or a commit id that will be passed to git checkout:

$ kerl build git https://github.com/erlang/otp.git OTP-28.0 28.0
Checking out Erlang/OTP git repository from https://github.com/erlang/otp.git...
Building (git) Erlang/OTP OTP-28.0; please wait...
...
Building docs...
Erlang/OTP '28.0' (from git) has been successfully built.

Debugging `kerl` usage

If KERL_DEBUG is set to a value, then kerl will emit copious debug logging, including a best effort attempt at line numbers. The line numbers may or may not be accurate if kerl is run under the dash shell, as is commonly found in Alpine Linux/Docker images.

Configuring `kerl`

You can tune kerl using the .kerlrc file in your $HOME directory.

`kerl` and OpenSSL

If you're running kerl on macOS, it will try to guess the OpenSSL version to use if none is specified (e.g. via KERL_CONFIGURE_OPTIONS' --with-ssl).

Since Erlang/OTP 25.1, OpenSSL 3.0 is supported, so the following applies

| Erlang/OTP version | OpenSSL version | |- |- | | up until 25.1 | 1.1 | | after 25.1 | 3.0 |

`kerl` options

kerl options can be passed either via .kerlrc or environment variables, as shown below.

Color configuration

`KERL_COLORIZE`

Default: 1 (Enabled) Enable VT100 colorizing if tput available (provided by ncurses). Set to 0 to disable. Colorization will be disabled anyway if necessary requirements are missing.

Color for log levels can be overriden, by setting ANSI numerical color code to variables KERL_COLOR_* :

KERL_COLOR_E : (1=red) Error level color
KERL_COLOR_W : (3=yellow) Warning level color
KERL_COLOR_N : (4=blue) Notice level color
KERL_COLOR_T : (6=cyan) Tip level color
KERL_COLOR_S : (2=green) Success level color
KERL_COLOR_D : (9) Default Terminal color

Locations on disk

`KERL_BASE_DIR`

Defa

Kerl

Install / Use

README

`kerl`

Table of Contents

Installing `kerl`

Command-line completion

Updating `kerl` locally

How `kerl` works

Using `kerl`

Building Erlang/OTP from a GitHub fork

Building Erlang/OTP from a Git source

Debugging `kerl` usage

Configuring `kerl`

`kerl` and OpenSSL

`kerl` options

Color configuration

`KERL_COLORIZE`

Locations on disk

`KERL_BASE_DIR`

Kerl

Install / Use

README

kerl

Table of Contents

Installing kerl

Command-line completion

Updating kerl locally

How kerl works

Using kerl

Building Erlang/OTP from a GitHub fork

Building Erlang/OTP from a Git source

Debugging kerl usage

Configuring kerl

kerl and OpenSSL

kerl options

Color configuration

KERL_COLORIZE

Locations on disk

KERL_BASE_DIR

`kerl`

Installing `kerl`

Updating `kerl` locally

How `kerl` works

Using `kerl`

Debugging `kerl` usage

Configuring `kerl`

`kerl` and OpenSSL

`kerl` options

`KERL_COLORIZE`

`KERL_BASE_DIR`