Easy building and installing of Erlang/OTP instances.
Kerl aims to be shell agnostic 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.
OTP Support Policy
As of 2021 September 17, we are supporting the current OTP release version
and 2 prior release versions (same as upstream OTP.) Older OTP releases
may or may not work. We will advance release support as new releases of OTP
become available.
Triage cadence
We triage kerl pull requests and issues at least once a month, typically on
the fourth Tuesday of the month at 1 pm US/Pacific or 8 pm UTC.
IRC channel
We have a channel on Libera called #kerl -
feel free to join and ask support or implementation questions any time. If
no one is around, feel free to open an issue with your question or problem
instead.
Downloading
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:
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 repository tags
but you can tell kerl to download from the official Erlang 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.
Usage
List the available releases (kerl ignores releases < 10):
$ kerl build 19.2 19.2
Verifying archive checksum...
Checksum verified (7cdd18a826dd7bda0ca46d1c3b2efca6)
Extracting source code
Building Erlang/OTP 19.2 (19.2), please wait...
Erlang/OTP 19.2 (19.2) 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 19.2 19.2-builtdocs
Verifying archive checksum...
Checksum verified (7cdd18a826dd7bda0ca46d1c3b2efca6)
Extracting source code
Building Erlang/OTP 19.2 (19.2-builtdocs), please wait...
Building docs...
Erlang/OTP 19.2 (19.2-builtdocs) has been successfully built
(Note that kerl uses the otp_build script internally, and ./otp_build configure disables HiPE on linux)
You can verify your build has been registered:
$ kerl list builds
19.2,19.2
19.2,19.2-builtdocs
Now install a build to some location:
$ kerl install 19.2 ~/kerl/19.2
Installing Erlang/OTP 19.2 (19.2) in /Users/sanmiguel/kerl/19.2...
You can activate this installation running the following command:
. /Users/sanmiguel/kerl/19.2/activate
Later on, you can leave the installation typing:
kerl_deactivate
Here again you can check the installation's been registered:
$ kerl list installations
19.2 /Users/sanmiguel/kerl/19.2
And at last activate it:
$ . /path/to/install/dir/activate
Activation will backup your $PATH, prepend it with the installation's bin/
directory. Thus it's only valid for the current shell session, and until you
activate another installation or call kerl_deactivate.
You're now ready to work with your 19.2 installation:
$ erl -version
Erlang (SMP,ASYNC_THREADS,HIPE) (BEAM) emulator version 8.2
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:
/Users/sanmiguel/kerl/19.2
You can get an overview of the current kerl state with:
$ kerl status
Available builds:
19.2,19.2
----------
Available installations:
19.2 /Users/sanmiguel/kerl/19.2
----------
The current active installation is:
/Users/sanmiguel/kerl/19.2
There's no Dialyzer PLT for the active installation
You can delete builds and installations with the following commands:
$ kerl delete build 19.2
The 19.2 build has been deleted
$ kerl delete installation /path/to/install/dir
The installation in /path/to/install/dir has been deleted
You can easily deploy an installation to another host having ssh and rsync access with the following command:
$ kerl deploy anotherhost /path/to/install/dir
Cloning Erlang/OTP 19.2 (/path/to/install/dir) to anotherhost (/path/to/install/dir) ...
On anotherhost, you can activate this installation running the following command:
. /path/to/install/dir/activate
Later on, you can leave the installation typing:
kerl_deactivate
Building from a github fork
It is possible to build Erlang 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 Basho's OTP fork:
From here (provided the KERL_BUILD_BACKEND and OTP_GITHUB_URL variables remain in place), it is possible to use kerl as normal:
$ kerl build R16B02_basho10 16b02-basho10
Building from a git source
You can build Erlang 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 dev 19.2_dev
Checking Erlang/OTP git repository from https://github.com/erlang/otp.git...
Building Erlang/OTP 19.2_dev from git, please wait...
Erlang/OTP 19.2_dev from git has been successfully built
Tuning
You can tune kerl using the .kerlrc file in your $HOME directory.
Colors 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
Default: "$HOME"/.kerl
Directory in which kerl will cache artefacts for building and installing.
KERL_CONFIG
Default: "$HOME"/.kerlrc
File from which to source kerl configuration
KERL_DOWNLOAD_DIR
Default: ${KERL_BASE_DIR}/archives
Directory in which to place downloaded artefacts
KERL_BUILD_DIR
Default: ${KERL_BASE_DIR}/builds
Directory in which kerl will perform builds
KERL_GIT_DIR
Default: ${KERL_BASE_DIR}/gits
Directory in which kerl will clone git repositories for building.
Build configuration
KERL_CONFIGURE_OPTIONS
Space-separated options to pass to configure when building OTP.
KERL_CONFIGURE_APPLICATIONS
Space-separated list of OTP applications which should exclusively be built.
KERL_CONFIGURE_DISABLE_APPLICATIONS
Space-separated list of OTP applications to disable during building.
KERL_BUILD_PLT
Create a PLT file alongside the built release.
KERL_USE_AUTOCONF
Use autoconf during build process.
NB: Automatically enabled when using KERL_BUILD_BACKEND=git
Default value: https://github.com/erlang/otp
Acceptable value: any github fork of OTP, e.g. https://github.com/basho/otp
KERL_BUILD_DOCS
If $KERL_BUILD_DOCS is set, kerl will create docs from the built erlang version regardless of origin (tarball backend from erlang.org or via kerl build git, or via git backend).
If $KERL_BUILD_DOCS is unset, kerl will only install docs when NOT installing a build created via kerl build git..., and according to KERL_INSTALL_HTMLDOCS and KERL_INSTALL_MANPAGES.
KERL_DOC_TARGETS
Default: chunks
Available targets:
man: install manpage docs.
html: install HTML docs.
pdf: install PDF docs.
chunks: install chunnks format for get documentation from erl.
You can set multiple type of targets separated by space, example $KERL_DOC_TARGETS="man html pdf chunks"
KERL_INSTALL_MANPAGES
Install man pages when not building from git source.
It's noteworthy that when not using KERL_BUILD_DOCS=yes, the docset that may be downloaded can be up to 120MB.
KERL_INSTALL_HTMLDOCS
Install HTML documentation when not building from git source.
It's noteworthy that when not using KERL_BUILD_DOCS=yes, the docset that may be downloaded can be up to 120MB.
KERL_SASL_STARTUP
Build OTP to use SASL startup instead of minimal (default, when var is unset).
Installation configuration
Activation configuration
The following apply when activating an installation (i.e. . ${KERL_DEFAULT_INSTALL_DIR}/19.2/activate).
KERL_ENABLE_PROMPT
When set, automatically prefix the shell prompt with a section containing the erlang version (see $KERL_PROMPT_FORMAT ).
KERL_PROMPT_FORMAT
Default: (%BUILDNAME%)
Available variables:
%BUILDNAME%: Name of the kerl build (e.g. my_test_build_18.0)
%RELEASE%: Name of the erlang release (e.g. 19.2 or R16B02)
The format of the prompt section to add.
KERL_DEFAULT_INSTALL_DIR
Effective when calling kerl install <build> with no installation location argument.
If unset, $PWD is used.
If set, install the build under $KERL_DEFAULT_INSTALL_DIR/${buildname}.
KERL_APP_INSTALL_DIR
Effective when calling kerl upgrade. This is the folder where the kerl application
resides.
If unset, $PWD is used.
If set, kerl is installed at $KERL_APP_INSTALL_DIR/kerl.
KERL_DEPLOY_SSH_OPTIONS
KERL_DEPLOY_RSYNC_OPTIONS
Options passed to ssh and rsync during kerl deploy tasks.
Note on .kerlrc
Since .kerlrc is a dot file for /bin/sh, running shell commands inside the
.kerlrc will affect the shell and environment variables for the commands being
executed later. For example, the shell export commands in .kerlrc will affect
your login shell environment when activating curl. Use with care.
Fish shell support
kerl has basic support for the fish shell.
To activate an installation:
source /path/to/install/dir/activate.fish
Deactivation is the same as in other shells:
kerl_deactivate
Please note: if you've installed a build with an older version of kerl
(1.2.0 older) it won't have the activate.fish script.
C shell support
kerl has basic support for the C shells (csh/tcsh/etc.).
To activate an installation:
source /path/to/install/dir/activate.csh
The activation script sources file .kerlrc.csh instead of .kerlrc.
Deactivation is the same as in other shells:
kerl_deactivate
Please note: if you've installed a build with an older version of kerl
it won't have the activate.csh script.
You can specify the configure options to use when building Erlang/OTP with the
KERL_CONFIGURE_OPTIONS variable, either in your $HOME/.kerlrc file or
prepending it to the command line. Full list of all options can be in
Erlang documentation.
If non-empty, you can specify the subset of applications to use when building
(and subsequent installing) Erlang/OTP with the KERL_CONFIGURE_APPLICATIONS
variable, either in your $HOME/.kerlrc file or prepending it to the command
line.
If non-empty, you can specify the subset of applications to disable when
building (and subsequent installing) Erlang/OTP with the
KERL_CONFIGURE_DISABLE_APPLICATIONS variable, either in your $HOME/.kerlrc
file or prepending it to the command line.
You can enable the use of autoconf in the build process setting
KERL_USE_AUTOCONF=yes in your $HOME/.kerlrc file
Note: autoconf is always enabled for git builds
Using shell export command in .kerlrc
Configure variables which includes spaces such as those in CFLAGS cannot be
passed on with KERL_CONFIGURE_OPTIONS. In such a case you can use shell
export command to define the environment variables for ./configure. Note
well: this method has a side effect to change your shell execution environment
after activating a kerl installation of Erlang/OTP. Here is an example of
.kerlrc for building Erlang/OTP for FreeBSD with clang compiler:
In case you cannot access the default directory for temporary files (/tmp) or simply want them somewhere else, you can also provide your own directory with the variable TMP_DIR