diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 306 |
1 files changed, 223 insertions, 83 deletions
@@ -7,10 +7,16 @@ Kerl aims to be shell agnostic and its only dependencies, excluding what's requi All is done so that, once a specific release has been built, creating a new installation is as fast as possible. + Downloading ----------- -You can download the script directly from github: +If you are on MacOS, and using [homebrew](https://github.com/Homebrew/brew), 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 @@ -36,60 +42,64 @@ By default, kerl downloads source tarballs from the [official Erlang website](ht you can tell kerl to download tarballs of Erlang source code from the tags pushed to the [official source code](https://github.com/erlang/otp) by setting `KERL_BUILD_BACKEND=git` +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 list releases - Getting the available releases from erlang.org... - R10B-0 R10B-2 R10B-3 R10B-4 R10B-5 R10B-6 R10B-7 R10B-8 R10B-9 R11B-0 R11B-1 - R11B-2 R11B-3 R11B-4 R11B-5 R12B-0 R12B-1 R12B-2 R12B-3 R12B-4 R12B-5 R13A - R13B R13B01 R13B02 R13B03 R13B04 R14A R14B R14B01 R14B02 - Run "./kerl update releases" to update this list from erlang.org + R10B-0 R10B-10 R10B-1a R10B-2 R10B-3 R10B-4 R10B-5 R10B-6 R10B-7 R10B-8 + R10B-9 R11B-0 R11B-1 R11B-2 R11B-3 R11B-4 R11B-5 R12B-0 R12B-1 R12B-2 R12B-3 + R12B-4 R12B-5 R13A R13B01 R13B02-1 R13B02 R13B03 R13B04 R13B R14A R14B01 + R14B02 R14B03 R14B04 R14B R14B_erts-5.8.1.1 R15B01 R15B02 + R15B02_with_MSVCR100_installer_fix R15B03-1 R15B03 R15B + R16A_RELEASE_CANDIDATE R16B01 R16B02 R16B03-1 R16B03 R16B 17.0-rc1 17.0-rc2 + 17.0 17.1 17.3 17.4 17.5 18.0 18.1 18.2 18.2.1 18.3 19.0 19.1 19.2 + Run '/usr/local/bin/kerl update releases' to update this list from erlang.org Pick your choice and build it: - $ kerl build R14B02 r14b02 - Downloading otp_src_R14B02.tar.gz to /home/evax/.kerl/archives - (curl progresses...) + $ kerl build 19.2 19.2 Verifying archive checksum... - (curl progresses...) - Checksum verified (229fb8f193b09ac04a57a9d7794349b7) + Checksum verified (7cdd18a826dd7bda0ca46d1c3b2efca6) Extracting source code - Building Erlang/OTP R14B02 (r14b02), please wait... - Erlang/OTP R14B02 has been successfully built + 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_CONFIGURE_OPTIONS=--enable-hipe kerl build R14B02 r14b02_hipe + $ KERL_BUILD_DOCS=yes kerl build 19.2 19.2-builtdocs Verifying archive checksum... - Checksum verified (229fb8f193b09ac04a57a9d7794349b7) + Checksum verified (7cdd18a826dd7bda0ca46d1c3b2efca6) Extracting source code - Building Erlang/OTP R14B02 (r14b02_hipe), please wait... - Erlang/OTP R14B02 (r14b02_hipe) has been successfully built + 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 - R14B02,r14b02 - R14B02,r14b02_hipe + 19.2,19.2 + 19.2,19.2-builtdocs Now install a build to some location: - $ kerl install r14b02 /path/to/install/dir/ - Installing Erlang/OTP R14B02 (r14b02) in /path/to/install/dir... + $ 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: - . /path/to/install/dir/activate + . /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 - r14b02 /path/to/install/dir + 19.2 /Users/sanmiguel/kerl/19.2 And at last activate it: @@ -99,10 +109,10 @@ 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 r14b02 installation: +You're now ready to work with your 19.2 installation: $ erl -version - Erlang (SMP,ASYNC_THREADS,HIPE) (BEAM) emulator version 5.8.3 + Erlang (SMP,ASYNC_THREADS,HIPE) (BEAM) emulator version 8.2 When you're done just call the shell function: @@ -111,38 +121,68 @@ When you're done just call the shell function: Anytime you can check which installation, if any, is currently active with: $ kerl active - No Erlang/OTP kerl installation is currently 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: - R14B02,r14b02 - R14B02,r14b02_hipe + 19.2,19.2 ---------- Available installations: - r14b02 /path/to/install/dir + 19.2 /Users/sanmiguel/kerl/19.2 ---------- - Currently active installation: The current active installation is: - /path/to/install/dir + /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 r14b02 - The r14b02 build has been deleted + $ 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 r14b02 (/path/to/install/dir) to 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: + + $ export KERL_BUILD_BACKEND=git + $ export OTP_GITHUB_URL="https://github.com/basho/otp" + $ kerl update releases + The available releases are: + R13B03 R13B04 R14A R14B R14B01 R14B02 R14B03 R14B04 R15A R15B R15B01 + R15B01_basho1 R15B01p R15B02 R15B03 R15B03-1 R16A_RELEASE_CANDIDATE R16B + R16B01 R16B01_RC1 R16B02 R16B02_basho R16B02_basho10 R16B02_basho10rc1 + R16B02_basho10rc2 R16B02_basho10rc3 R16B02_basho2 R16B02_basho3 R16B02_basho4 + R16B02_basho5 R16B02_basho6 R16B02_basho7 R16B02_basho8 R16B02_basho9 + R16B02_basho9rc1 R16B03 R16B03-1 R16B03_yielding_binary_to_term 17.0 17.0-rc1 + 17.0-rc2 17.0.1 17.0.2 17.1 17.1.1 17.1.2 17.2 17.2.1 17.2.2 17.3 17.3.1 + 17.3.2 17.3.3 17.3.4 17.4 17.4.1 17.5 17.5.1 17.5.2 17.5.3 17.5.4 17.5.5 + 17.5.6 17.5.6.1 17.5.6.2 17.5.6.3 17.5.6.4 17.5.6.5 17.5.6.6 17.5.6.7 + 17.5.6.8 17.5.6.9 18.0 18.0-rc1 18.0-rc2 18.0.1 18.0.2 18.0.3 18.1 18.1.1 + 18.1.2 18.1.3 18.1.4 18.1.5 18.2 18.2.1 18.2.2 18.2.3 18.2.4 18.2.4.1 + 18.3 18.3.1 18.3.2 18.3.3 18.3.4 18.3.4.1 19.0 19.0-rc1 19.0-rc2 19.0.1 + 18.0.2 + + +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 -------------------------- @@ -150,46 +190,147 @@ 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 r14b02_dev - Checking Erlang/OTP git repositoy from https://github.com/erlang/otp.git... - Building Erlang/OTP r14b02_dev from git, please wait... - Erlang/OTP r14b02_dev from git has been successfully built + $ 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. -You can set the following variables: - -- `KERL_BUILD_BACKEND` which source code download provider to use - (`tarball` - default) erlang.org or github (`git`) -- `KERL_DOWNLOAD_DIR` where to put downloaded files, defaults to $HOME/.kerl/archives -- `KERL_BUILD_DIR` where to hold the builds, defaults to $HOME/.kerl/builds -- `KERL_DEFAULT_INSTALL_DIR` if set in ~/.kerlrc, install builds to this dir if no path is provided on installs, (recommend `$KERL_BASE_DIR/installs`) -- `KERL_CONFIGURE_OPTIONS` options to pass to Erlang's `./configure` script, e.g. `--without-termcap` -- `KERL_CONFIGURE_APPLICATIONS` if non-empty, subset of applications used in the builds (and subsequent installations) process, e.g. `kernel stdlib sasl` -- `KERL_CONFIGURE_DISABLE_APPLICATIONS` if non-empty, subset of applications disabled in the builds (and subsequent installations) process, e.g. `odbc` -- `KERL_SASL_STARTUP` use SASL system startup instead of minimal -- `KERL_DEPLOY_SSH_OPTIONS` if additional options are required, e.g. `-qx -o PasswordAuthentication=no` -- `KERL_DEPLOY_RSYNC_OPTIONS` if additional options are required, e.g. `--delete` -- `KERL_ENABLE_PROMPT` if set, will enable the prompt to be prefixed with what is set in `KERL_PROMPT_FORMAT`. -- `KERL_PROMPT_FORMAT` the format string to use as a prefix for the prompt. If not set (or empty) will default to `(%BUILDNAME%)`. The following variables are available for use in the format string. - - `%RELEASE%` The active release (e.g. `18.0` or `R16B02`) - - `%BUILDNAME%` The active buildname (e.g. `my_test_build_18.0`) -- `KERL_BUILD_DOCS` if set, will build documentation from source code repository -- `KERL_USE_AUTOCONF` use autoconf in the builds process (**note**: implied by the `git` build backend) - -### Options for tarball builds only ### - -These options only work when `KERL_BUILD_BACKEND=tarball` (the default) **and** -if `KERL_BUILD_DOCS` is not set. That is, they are *strictly* for backward -compatibility. They will probably be removed in a future release. - -- `KERL_INSTALL_MANPAGES` if non-empty will install manpages into `/install/path/man` -- `KERL_INSTALL_HTMLDOCS` if non-empty will install HTML docs into `/install/path/html` - -If you want documentation for git based builds, set `KERL_BUILD_DOCS=yes` - and if -you don't want to download 120MB of docs from erlang.org, also set `KERL_BUILD_DOCS=yes` +## 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 + +Options to pass to `configure` when building OTP. + + +### KERL_CONFIGURE_APPLICATIONS + +List of OTP applications which should exclusively be built. + + +### KERL_CONFIGURE_DISABLE_APPLICATIONS + +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` + + +### KERL_BUILD_BACKEND + +Default value: `tarball` +Acceptable values: `tarball`, `git` + +- `tarball`: Fetch erlang releases from erlang.org +- `git`: Fetch erlang releases from [`$OTP_GITHUB_URL`](#otp_github_url) + +NB: Docs are only fetched when this is set to `tarball`. To enable creation of docs when set to `git`, one must also set [`$KERL_BUILD_DOCS`](#kerl_build_docs). + +NB: This setting has no effect when using `kerl build git...`, which invokes kerl to directly clone a git repository and build from there. + + +### OTP_GITHUB_URL + +Default value: `https://github.com/erlang/otp` +Acceptable value: any github fork of OTP, e.g. `https://github.com/basho/otp` + + +### KERL_BUILD_DOCS +### KERL_INSTALL_MANPAGES +### KERL_INSTALL_HTMLDOCS + +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 bia `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`. + +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) ). + + +### 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_DEPLOY_SSH_OPTIONS +### KERL_DEPLOY_RSYNC_OPTIONS + +Options passed to `ssh` and `rsync` during `kerl deploy` tasks. Note on .kerlrc --------------- @@ -254,8 +395,8 @@ Commands reference Creates a named build either from an official Erlang/OTP release or from a git repository. - $ kerl build R14B02 r14b02 - $ kerl build git https://github.com/erlang/otp dev r14b02_dev + $ kerl build 19.2 19.2 + $ kerl build git https://github.com/erlang/otp dev 19.2_dev #### Tuning @@ -265,7 +406,7 @@ 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. - $ KERL_CONFIGURE_OPTIONS=--enable-hipe kerl build R14B02 r14b02_hipe + $ KERL_CONFIGURE_OPTIONS=--enable-hipe kerl build 19.2 19.2-hipe ##### Configure applications @@ -308,8 +449,7 @@ after activating a kerl installation of Erlang/OTP. Here is an example of #### Building documentation -Prior to kerl 1.0, kerl always downloaded prepared documentation from erlang.org. Now -if `KERL_BUILD_DOCS=yes` is set, kerl will build the man pages and HTML +Prior to kerl 1.0, kerl always downloaded prepared documentation from erlang.org. Now if `KERL_BUILD_DOCS=yes` is set, kerl will build the man pages and HTML documentation from the source repository in which is working. **Note**: This variable takes precedent over the other documentation parameters. @@ -320,7 +460,7 @@ documentation from the source repository in which is working. Installs a named build to the specified filesystem location. - $ kerl install r14b02 /srv/otp/r14b02 + $ kerl install 19.2 /srv/otp/19.2 If path is omitted the current working directory will be used. However, if `KERL_DEFAULT_INSTALL_DIR` is defined in ~/.kerlrc, @@ -422,13 +562,13 @@ Lists the releases, builds or installations available. Deletes the specified build or installation. ``` -$ kerl delete build r14b02 -The r14b02 build has been deleted +$ kerl delete build 19.2 +The 19.2 build has been deleted ``` ``` -$ kerl delete installation /srv/otp/r14b02 -The installation in /srv/otp/r14b02 has been deleted +$ kerl delete installation /srv/otp/19.2 +The installation in /srv/otp/19.2 has been deleted ``` ### active @@ -439,7 +579,7 @@ Prints the path of the currently active installation, if any. $ kerl active The current active installation is: - /srv/otp/r14b02 + /srv/otp/19.2 ### status @@ -449,12 +589,12 @@ Prints the available builds and installations as well as the currently active in $ kerl status Available builds: - R14B02,r14b02 - git,r14b02_dev + 19.2,19.2 + git,19.2_dev ---------- Available installations: - r14b02 /srv/otp/r14b02 - r14b02 /srv/otp/r14b02_dev + 19.2 /srv/otp/19.2 + 19.2 /srv/otp/19.2_dev ---------- No Erlang/OTP kerl installation is currently active |