1kerl [![CircleCI](https://circleci.com/gh/kerl/kerl.svg?style=svg)](https://circleci.com/gh/kerl/kerl) 2==== 3 4Easy building and installing of [Erlang/OTP](https://www.erlang.org) instances. 5 6Kerl aims to be shell agnostic and its only dependencies, excluding what's 7required to actually build Erlang/OTP, are `curl` and `git`. 8 9All is done so that, once a specific release has been built, creating a new 10installation is as fast as possible. 11 12OTP Support Policy 13------------------ 14As of 2021 September 17, we are supporting the current OTP release version 15and 2 prior release versions (same as upstream OTP.) Older OTP releases 16may or may not work. We will advance release support as new releases of OTP 17become available. 18 19Triage cadence 20-------------- 21We triage kerl pull requests and issues at least once a month, typically on 22the fourth Tuesday of the month at 1 pm US/Pacific or 8 pm UTC. 23 24IRC channel 25----------- 26We have a channel on [Libera](https://web.libera.chat/gamja/) called `#kerl` - 27feel free to join and ask support or implementation questions any time. If 28no one is around, feel free to open an issue with your question or problem 29instead. 30 31Downloading 32----------- 33 34If you are on MacOS, and using [homebrew](https://github.com/Homebrew/brew), 35you can install kerl, along with shell completion, by running: 36 37 $ brew install kerl 38 39Alternatively, you can download the script directly from github: 40 41 $ curl -O https://raw.githubusercontent.com/kerl/kerl/master/kerl 42 43Then ensure it is executable 44 45 $ chmod a+x kerl 46 47and drop it in your $PATH 48 49Optionally download and install kerl's bash_completion file from 50https://github.com/kerl/kerl/raw/master/bash_completion/kerl 51 52Optionally download and install kerl's zsh-completion file from 53https://github.com/kerl/kerl/raw/master/zsh_completion/_kerl 54 55 56How it works 57------------ 58 59Kerl keeps tracks of the releases it downloads, builds and installs, allowing 60easy installations to new destinations (without complete rebuilding) and easy 61switches between Erlang/OTP installations. 62 63By default, kerl downloads source tarballs from the [official repository tags](https://github.com/erlang/otp/tags) 64but you can tell kerl to download from the [official Erlang website](https://www.erlang.org/downloads) by setting `KERL_BUILD_BACKEND=tarball`. 65However this website does not use HTTPS and is down more often than Github. 66 67You can also install directly from a raw git repository by using the `kerl build git <git_url> <git_version> <build_name>` syntax. 68 69 70Usage 71----- 72 73List the available releases (kerl ignores releases < 10): 74 75 $ kerl list releases 76 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 77 Run '/usr/local/bin/kerl update releases' to update this list from erlang.org 78 79Pick your choice and build it: 80 81 $ kerl build 19.2 19.2 82 Verifying archive checksum... 83 Checksum verified (7cdd18a826dd7bda0ca46d1c3b2efca6) 84 Extracting source code 85 Building Erlang/OTP 19.2 (19.2), please wait... 86 Erlang/OTP 19.2 (19.2) has been successfully built 87 88Note that named builds allow you to have different builds for the same Erlang/OTP release with different configure options: 89 90 $ KERL_BUILD_DOCS=yes kerl build 19.2 19.2-builtdocs 91 Verifying archive checksum... 92 Checksum verified (7cdd18a826dd7bda0ca46d1c3b2efca6) 93 Extracting source code 94 Building Erlang/OTP 19.2 (19.2-builtdocs), please wait... 95 Building docs... 96 Erlang/OTP 19.2 (19.2-builtdocs) has been successfully built 97 98(Note that kerl uses the otp_build script internally, and `./otp_build configure` disables HiPE on linux) 99 100You can verify your build has been registered: 101 102 $ kerl list builds 103 19.2,19.2 104 19.2,19.2-builtdocs 105 106Now install a build to some location: 107 108 $ kerl install 19.2 ~/kerl/19.2 109 Installing Erlang/OTP 19.2 (19.2) in /Users/sanmiguel/kerl/19.2... 110 You can activate this installation running the following command: 111 . /Users/sanmiguel/kerl/19.2/activate 112 Later on, you can leave the installation typing: 113 kerl_deactivate 114 115Here again you can check the installation's been registered: 116 117 $ kerl list installations 118 19.2 /Users/sanmiguel/kerl/19.2 119 120And at last activate it: 121 122 $ . /path/to/install/dir/activate 123 124Activation will backup your $PATH, prepend it with the installation's bin/ 125directory. Thus it's only valid for the current shell session, and until you 126activate another installation or call `kerl_deactivate`. 127 128You're now ready to work with your 19.2 installation: 129 130 $ erl -version 131 Erlang (SMP,ASYNC_THREADS,HIPE) (BEAM) emulator version 8.2 132 133When you're done just call the shell function: 134 135 $ kerl_deactivate 136 137Anytime you can check which installation, if any, is currently active with: 138 139 $ kerl active 140 The current active installation is: 141 /Users/sanmiguel/kerl/19.2 142 143You can get an overview of the current kerl state with: 144 145 $ kerl status 146 Available builds: 147 19.2,19.2 148 ---------- 149 Available installations: 150 19.2 /Users/sanmiguel/kerl/19.2 151 ---------- 152 The current active installation is: 153 /Users/sanmiguel/kerl/19.2 154 There's no Dialyzer PLT for the active installation 155 156You can delete builds and installations with the following commands: 157 158 $ kerl delete build 19.2 159 The 19.2 build has been deleted 160 $ kerl delete installation /path/to/install/dir 161 The installation in /path/to/install/dir has been deleted 162 163You can easily deploy an installation to another host having `ssh` and `rsync` access with the following command: 164 165 $ kerl deploy anotherhost /path/to/install/dir 166 Cloning Erlang/OTP 19.2 (/path/to/install/dir) to anotherhost (/path/to/install/dir) ... 167 On anotherhost, you can activate this installation running the following command: 168 . /path/to/install/dir/activate 169 Later on, you can leave the installation typing: 170 kerl_deactivate 171 172 173Building from a github fork 174--------------------------- 175 176It 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: 177 178 $ export KERL_BUILD_BACKEND=git 179 $ export OTP_GITHUB_URL='https://github.com/basho/otp' 180 $ kerl update releases 181 The available releases are: 182 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.2 183 184 185From here (provided the `KERL_BUILD_BACKEND` and `OTP_GITHUB_URL` variables remain in place), it is possible to use kerl as normal: 186 187 $ kerl build R16B02_basho10 16b02-basho10 188 189 190Building from a git source 191-------------------------- 192 193You can build Erlang directly from a git repository with a command of the form 194`kerl build git <git_url> <git_version> <build_name>` where `<git_version>` can 195be either a branch, a tag or a commit id that will be passed to `git checkout`: 196 197 $ kerl build git https://github.com/erlang/otp.git dev 19.2_dev 198 Checking Erlang/OTP git repository from https://github.com/erlang/otp.git... 199 Building Erlang/OTP 19.2_dev from git, please wait... 200 Erlang/OTP 19.2_dev from git has been successfully built 201 202 203Tuning 204------ 205 206You can tune kerl using the .kerlrc file in your $HOME directory. 207 208## Locations on disk 209 210### KERL_BASE_DIR 211 212Default: `"$HOME"/.kerl` 213Directory in which kerl will cache artefacts for building and installing. 214 215 216### KERL_CONFIG 217 218Default: `"$HOME"/.kerlrc` 219File from which to source kerl configuration 220 221 222### KERL_DOWNLOAD_DIR 223 224Default: `${KERL_BASE_DIR}/archives` 225Directory in which to place downloaded artefacts 226 227 228### KERL_BUILD_DIR 229 230Default: `${KERL_BASE_DIR}/builds` 231Directory in which kerl will perform builds 232 233 234### KERL_GIT_DIR 235 236Default: `${KERL_BASE_DIR}/gits` 237Directory in which kerl will clone git repositories for building. 238 239 240## Build configuration 241 242### KERL_CONFIGURE_OPTIONS 243 244Space-separated options to pass to `configure` when building OTP. 245 246 247### KERL_CONFIGURE_APPLICATIONS 248 249Space-separated list of OTP applications which should exclusively be built. 250 251 252### KERL_CONFIGURE_DISABLE_APPLICATIONS 253 254Space-separated list of OTP applications to disable during building. 255 256 257### KERL_BUILD_PLT 258 259Create a PLT file alongside the built release. 260 261 262### KERL_USE_AUTOCONF 263 264Use `autoconf` during build process. 265NB: Automatically enabled when using `KERL_BUILD_BACKEND=git` 266 267 268### KERL_BUILD_BACKEND 269 270Default value: `git` 271Acceptable values: `tarball`, `git` 272 273- `tarball`: Fetch erlang releases from erlang.org 274- `git`: Fetch erlang releases from [`$OTP_GITHUB_URL`](#otp_github_url) 275 276NB: 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). 277 278NB: This setting has no effect when using `kerl build git...`, which invokes kerl to directly clone a git repository and build from there. 279 280 281### KERL_BUILD_DEBUG_VM 282 283Allows building, alongside the regular VM, a debug VM (available via `cerl -debug`). 284NB: Enable this build using `KERL_BUILD_DEBUG_VM=true` 285 286 287### OTP_GITHUB_URL 288 289Default value: `https://github.com/erlang/otp` 290Acceptable value: any github fork of OTP, e.g. `https://github.com/basho/otp` 291 292 293### KERL_BUILD_DOCS 294 295If `$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). 296 297If `$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`. 298 299### KERL_DOC_TARGETS 300 301Default: `chunks` 302Available targets: 303 - `man`: install manpage docs. 304 - `html`: install HTML docs. 305 - `pdf`: install PDF docs. 306 - `chunks`: install chunnks format for get documentation from `erl`. 307 308You can set multiple type of targets separated by space, example `$KERL_DOC_TARGETS="man html pdf chunks"` 309 310### KERL_INSTALL_MANPAGES 311 312Install man pages when not building from git source. 313 314It's noteworthy that when not using `KERL_BUILD_DOCS=yes`, the docset that may be downloaded can be up to 120MB. 315 316 317### KERL_INSTALL_HTMLDOCS 318 319Install HTML documentation when not building from git source. 320 321It's noteworthy that when not using `KERL_BUILD_DOCS=yes`, the docset that may be downloaded can be up to 120MB. 322 323 324### KERL_SASL_STARTUP 325 326Build OTP to use SASL startup instead of minimal (default, when var is unset). 327 328 329## Installation configuration 330 331 332## Activation configuration 333 334The following apply when activating an installation (i.e. `. ${KERL_DEFAULT_INSTALL_DIR}/19.2/activate`). 335 336### KERL_ENABLE_PROMPT 337 338When set, automatically prefix the shell prompt with a section containing the erlang version (see [`$KERL_PROMPT_FORMAT`](#kerl_prompt_format) ). 339 340 341### KERL_PROMPT_FORMAT 342 343Default: `(%BUILDNAME%)` 344Available variables: 345 - `%BUILDNAME%`: Name of the kerl build (e.g. `my_test_build_18.0`) 346 - `%RELEASE%`: Name of the erlang release (e.g. `19.2` or `R16B02`) 347 348The format of the prompt section to add. 349 350 351### KERL_DEFAULT_INSTALL_DIR 352 353Effective when calling `kerl install <build>` with no installation location argument. 354 355If unset, `$PWD` is used. 356 357If set, install the build under `$KERL_DEFAULT_INSTALL_DIR/${buildname}`. 358 359 360### KERL_DEPLOY_SSH_OPTIONS 361### KERL_DEPLOY_RSYNC_OPTIONS 362 363Options passed to `ssh` and `rsync` during `kerl deploy` tasks. 364 365Note on .kerlrc 366--------------- 367 368Since .kerlrc is a dot file for `/bin/sh`, running shell commands inside the 369.kerlrc will affect the shell and environment variables for the commands being 370executed later. For example, the shell `export` commands in .kerlrc will affect 371*your login shell environment* when activating `curl`. Use with care. 372 373Fish shell support 374------------------ 375 376kerl has basic support for the fish shell. 377 378To activate an installation: 379 380 source /path/to/install/dir/activate.fish 381 382Deactivation is the same as in other shells: 383 384 kerl_deactivate 385 386Please note: if you've installed a build with an older version of kerl 387(1.2.0 older) it won't have the `activate.fish` script. 388 389C shell support 390--------------- 391 392kerl has basic support for the C shells (csh/tcsh/etc.). 393 394To activate an installation: 395 396 source /path/to/install/dir/activate.csh 397 398The activation script sources file .kerlrc.csh instead of .kerlrc. 399 400Deactivation is the same as in other shells: 401 402 kerl_deactivate 403 404Please note: if you've installed a build with an older version of kerl 405it won't have the `activate.csh` script. 406 407Glossary 408-------- 409 410Here are the abstractions kerl is handling: 411 412- **releases**: Erlang/OTP releases from [erlang.org](https://erlang.org) 413 414- **builds**: the result of configuring and compiling releases or git repositories 415 416- **installations**: the result of deploying builds to filesystem locations (also referred to as "sandboxes") 417 418Commands reference 419------------------ 420 421### build 422 423 kerl build <release_code> <build_name> 424 kerl build git <git_url> <git_version> <build_name> 425 426Creates a named build either from an official Erlang/OTP release or from a git repository. 427 428 $ kerl build 19.2 19.2 429 $ kerl build git https://github.com/erlang/otp dev 19.2_dev 430 431#### Tuning 432 433##### Configure options 434 435You can specify the configure options to use when building Erlang/OTP with the 436`KERL_CONFIGURE_OPTIONS` variable, either in your $HOME/.kerlrc file or 437prepending it to the command line. Full list of all options can be in 438[Erlang documentation](https://erlang.org/doc/installation_guide/INSTALL.html#Advanced-configuration-and-build-of-ErlangOTP_Configuring). 439 440 $ KERL_CONFIGURE_OPTIONS=--enable-hipe kerl build 19.2 19.2-hipe 441 442##### Configure applications 443 444If non-empty, you can specify the subset of applications to use when building 445(and subsequent installing) Erlang/OTP with the `KERL_CONFIGURE_APPLICATIONS` 446variable, either in your $HOME/.kerlrc file or prepending it to the command 447line. 448 449 $ KERL_CONFIGURE_APPLICATIONS="kernel stdlib sasl" kerl build R15B01 r15b01_minimal 450 451##### Configure disable applications 452 453If non-empty, you can specify the subset of applications to disable when 454building (and subsequent installing) Erlang/OTP with the 455`KERL_CONFIGURE_DISABLE_APPLICATIONS` variable, either in your $HOME/.kerlrc 456file or prepending it to the command line. 457 458 $ KERL_CONFIGURE_DISABLE_APPLICATIONS="odbc" kerl build R16B02 r16b02_no_odbc 459 460##### Enable autoconf 461 462You can enable the use of `autoconf` in the build process setting 463`KERL_USE_AUTOCONF=yes` in your $HOME/.kerlrc file 464 465**Note**: `autoconf` is always enabled for git builds 466 467##### Using shell export command in .kerlrc 468 469Configure variables which includes spaces such as those in `CFLAGS` cannot be 470passed on with `KERL_CONFIGURE_OPTIONS`. In such a case you can use shell 471`export` command to define the environment variables for `./configure`. Note 472well: this method has a side effect to change your shell execution environment 473after activating a kerl installation of Erlang/OTP. Here is an example of 474.kerlrc for building Erlang/OTP for FreeBSD with clang compiler: 475 476 # for clang 477 export CC=clang CXX=clang CFLAGS="-g -O3 -fstack-protector" LDFLAGS="-fstack-protector" 478 # compilation options 479 KERL_CONFIGURE_OPTIONS="--disable-native-libs --enable-vm-probes --with-dynamic-trace=dtrace --with-ssl=/usr/local --with-javac --enable-hipe --enable-kernel-poll --with-wx-config=/usr/local/bin/wxgtk2u-2.8-config --without-odbc --enable-threads --enable-sctp --enable-smp-support" 480 481 482In 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` 483 484 export TMP_DIR=/your/custom/temporary/dir 485 486#### Building documentation 487 488Prior 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 489documentation from the source repository in which is working. 490 491**Note**: This variable takes precedent over the other documentation parameters. 492 493### install 494 495 kerl install <build_name> [path] 496 497Installs a named build to the specified filesystem location. 498 499 $ kerl install 19.2 /srv/otp/19.2 500 501If path is omitted the current working directory will be used. However, if 502`KERL_DEFAULT_INSTALL_DIR` is defined in ~/.kerlrc, 503`KERL_DEFAULT_INSTALL_DIR/<build-name>` will be used instead. 504 505#### Install location restrictions 506 507**WARNING**: kerl assumes the given installation directory is for its sole use. 508If you later delete it with the `kerl delete` command, the whole directory will 509be deleted, along with anything you may have added to it! 510 511So please only install kerl in an empty (or non-existant) directory. 512 513If you attempt to install kerl in `$HOME` or `.erlang` or `$KERL_BASE_DIR`, 514then kerl will give you an error and refuse to proceed. If you try to install 515kerl in a directory that exists and is not empty, kerl will give you an error. 516 517#### Tuning 518 519##### SASL startup 520 521You can have SASL started automatically setting `KERL_SASL_STARTUP=yes` in your 522$HOME/.kerlrc file or prepending it to the command line. 523 524##### Manpages installation 525 526You can have manpages installed automatically setting 527`KERL_INSTALL_MANPAGES=yes` in your $HOME/.kerlrc file or prepending it to the 528command line. 529 530**Note**: for git-based builds, you want to set `KERL_BUILD_DOCS=yes` 531 532##### HTML docs installation 533 534You can have HTML docs installed automatically setting 535`KERL_INSTALL_HTMLDOCS=yes` in your $HOME/.kerlrc file or prepending it to the 536command line. 537 538*Note*: for git-based builds, you want to set `KERL_BUILD_DOCS=yes` 539 540#### Documentation installation 541 542Man pages will be installed to `[path]/man` and HTML docs will be installed in 543`[path]/html`. The kerl `activate` script manipulates the MANPATH of the current 544shell such that `man 3 gen_server` or `erl -man gen_server` should work perfectly. 545 546(Do not fret - `kerl_deactivate` restores your shell's MANPATH to whatever its 547original value was.) 548 549### deploy 550 551 kerl deploy <[user@]host> [directory] [remote_directory] 552 553Deploys the specified installation to the given host and location. 554 555 $ kerl deploy anotherhost /path/to/install/dir 556 557If remote_directory is omitted the specified directory will be used. 558 559If directory and remote_directory is omitted the current working directory will be used. 560 561*NOTE*: kerl assumes the specified host is accessible via `ssh` and `rsync`. 562 563#### Tuning 564 565##### Additional SSH options 566 567You can have additional options given to `ssh` by setting them in the 568`KERL_DEPLOY_SSH_OPTIONS` variable in your $HOME/.kerlrc file or on the command 569line, e.g. `KERL_DEPLOY_SSH_OPTIONS='-qx -o PasswordAuthentication=no'`. 570 571##### Additional RSYNC options 572 573You can have additional options given to `rsync` by setting them in the 574`KERL_DEPLOY_RSYNC_OPTIONS` variable in your $HOME/.kerlrc file or on the 575command line, e.g. `KERL_DEPLOY_RSYNC_OPTIONS='--delete'`. 576 577### update 578 579 kerl update releases 580 581If `KERL_BUILD_BACKEND=tarball` this command fetches the up-to-date list of OTP 582releases from erlang.org. 583 584If it is set to `KERL_BUILD_BACKEND=git` this command fetches an up-to-date 585list of OTP tags from the official OTP github repository. 586 587### list 588 589 kerl list <releases|builds|installations> 590 591Lists the releases, builds or installations available. 592 593### delete 594 595 kerl delete build <build_name> 596 kerl delete installation <path> 597 598Deletes the specified build or installation. 599 600``` 601$ kerl delete build 19.2 602The 19.2 build has been deleted 603``` 604 605``` 606$ kerl delete installation /srv/otp/19.2 607The installation in /srv/otp/19.2 has been deleted 608``` 609 610### active 611 612 kerl active 613 614Prints the path of the currently active installation, if any. 615 616 $ kerl active 617 The current active installation is: 618 /srv/otp/19.2 619 620### status 621 622 kerl status 623 624Prints the available builds and installations as well as the currently active installation. 625 626 $ kerl status 627 Available builds: 628 19.2,19.2 629 git,19.2_dev 630 ---------- 631 Available installations: 632 19.2 /srv/otp/19.2 633 19.2 /srv/otp/19.2_dev 634 ---------- 635 No Erlang/OTP kerl installation is currently active 636 637### path 638 639 kerl path [installation] 640 641Prints the path of the currently active installation if one is active. When given an 642installation name, it will return the path to that installation location on disk. 643This makes it useful for automation without having to run kerl's output through 644other tools to extract to path information. 645 646 $ kerl path 647 No active kerl-managed erlang installation 648 649 $ kerl path 19.2.3 650 /aux/erlangs/19.2.3 651 652### install-docsh 653 654 kerl install-docsh 655 656**Important note**: docsh only supports OTP versions 18 and later. 657 658Install `erl` shell documentation access 659extension - [docsh](https://github.com/erszcz/docsh). 660This extends the shell with new helpers, which enable access to full 661function help (via `h/{1,2,3}`), function specs (`s/{1,2,3}`) and type 662information (`t/{1,2,3}`). 663 664If you already have an OTP installation, you will need to remove it and 665re-install it **before** you execute `install-docsh`, 666since docsh needs some environment variables of its own to be set up 667and managed by the activate script. 668 669Activating a docsh-enabled Erlang installation will try to create 670a `$HOME/.erlang` symlink. 671If this file exists (i.e. you have created it manually), 672please consider removing it - otherwise, docsh won't work. 673Deactivating the kerl Erlang installation will remove the symlink. 674 675Alternatively, if the file exists and you have to keep it you can extend 676it with the content of [a docsh-specific `.erlang`][docsh-dot-erlang] - this 677task is left as an exercise for the reader - and export 678`KERL_DOCSH_DOT_ERLANG=exists` to silence unwanted warnings. 679The [manual setup guide][docsh-manual-setup] will probably come in handy 680if you decide to take this route. 681 682[docsh-dot-erlang]: https://github.com/erszcz/docsh/blob/2d9843bce794e726f591bbca49c88aedbb435f8c/templates/dot.erlang 683[docsh-manual-setup]: https://github.com/erszcz/docsh/blob/ecf35821610977e36b04c0c256990a5b0dab4870/doc/manual-setup.md 684 685Compiling crypto on Macs 686------------------------ 687Apple stopped shipping OpenSSL in OS X 10.11 (El Capitan) in favor of Apple's 688own SSL library. That makes using homebrew the most convenient way to install 689openssl on macOS 10.11 or later. Additionally, homebrew [stopped creating](https://github.com/Homebrew/brew/pull/612) 690symlinks from the homebrew installation directory to `/usr/local`, so in 691response to this, *if* you're running El Capitan, Sierra, or High Sierra 692*and* you have homebrew installed, *and* you used it to install openssl, 693kerl will ask homebrew for the openssl installation prefix and configure Erlang 694to build with that location automatically. 695 696**Important**: If you already have `--with-ssl` in your .kerlrc, kerl 697will honor that instead, and will not do any automatic configuration. 698 699Compiling crypto on Red Hat systems 700----------------------------------- 701Red Hat believes there's a [patent 702issue](https://bugzilla.redhat.com/show_bug.cgi?id=319901#c2) and has disabled 703elliptic curve crypto algorithms in its distributions for over 10 years. 704 705This causes Erlang builds to die when its compiling its own crypto libraries. 706 707As a workaround, you can set `CFLAGS="-DOPENSSL_NO_EC=1"` to tell the 708Erlang crypto libraries to not build the elliptic curve cipher suite. 709 710This issue applies to Fedora, Red Hat Enterprise Linux, CentOS and all 711derivatives of those distributions. 712 713There is a [tracking issue](https://github.com/kerl/kerl/issues/212) to 714automatically set this compiler flag, if you wish to follow how kerl 715will eventually deal with this issue. 716 717Changelog 718--------- 7191 November 2021 - 2.2.2 720 721 - Enable autoconf when patches are applied on macOS; fixes #384 (#385) 722 7238 October 2021 - 2.2.1 724 725 - Fix downloads for certain OTP releases (#383) 726 - Pin openssl to version 1.1 (#380) 727 72817 September 2021 - 2.2.0 729 730 - Download prebuilt binaries (if available) from github to speed builds (#376) 731 7323 June 2021 - 2.1.2 733 734 - Do not munge `LD_` flags on macOS any more (#372) 735 73622 March 2021 - 2.1.1 737 738 - grep `with-ssl` (#367) 739 - Add a `\` to commands to bypass any shell alias (#363) 740 - Enable multiple doc targets (#362) 741 74226 January 2021 - 2.1.0 743 744 - Fix Big Sur build issues again (#358) 745 - Automate building a debug Erlang (#360) 746 74710 December 2020 - 2.0.2 748 749 - Fix Big Sur build issue (#356) (see also [OTP #2871](https://github.com/erlang/otp/pull/2871)) 750 75120 October 2020 - 2.0.1 752 753 - Use `-path` in `find` (#345) 754 - Redownload a tarball if it's corrupted (#348) 755 - Update to build on Catalina and Big Sur (#355) 756 7574 May 2020 - 2.0.0 758 759 - **Important**: possible breaking change - releases are now fetched 760 through github tags by default (#277) 761 - Fix documentation building, especially for inline REPL help (#336) 762 - Fix builds on Catalina (#337, #339) - if you are on Catalina and 763 need to build older Erlangs, you should downgrade your XCode to an 764 earlier version. 765 7663 March 2020 - 1.8.7 767 768 - Implement version sorting (#319) 769 - Fix CI breakage (#327) 770 - Include `erl_call` in the path (#330) 771 77216 September 2019 - 1.8.6 773 774 - Remove almost all special cases for older macOS releases 775 77625 September 2018 - 1.8.5 777 778 - Support Mojave builds (#301) 779 - Disable SC2207 for Bash completion (#296) 780 7813 August 2018 - 1.8.4 782 783 - Support docsh 0.6.1 (#290) 784 - Update docs about KERL_INSTALL_MANPAGES & HTML_DOCS (#292) 785 - Fix bash completion for Bash 3 (#295) 786 7873 July 2018 - 1.8.3 788 789 - Update testing to include OTP 21 (#286) 790 - Fix an issue affecting CD\_PATH during builds (#284) 791 7925 March 2018 - 1.8.2 793 794 - Apply zlib patch when building OTP 17-19. (#258) 795 - Add CircleCI (#246) 796 - Fix empty package name warning (#245) 797 79813 November 2017 - 1.8.1 799 800 - Fix removing an installation by its name. (#244) 801 8028 November 2017 - 1.8.0 803 804 - Include support for installing and managing docsh (#213) 805 - Fix a function name typo (#241) 806 80723 October 2017 - 1.7.0 808 809 - Suggest the proper activation script based on the shell you're using (#225) 810 - Automatically turn on built-in shell history when using an OTP release >= 811 20 (#214) 812 - Warn when a Linux does not appear to have a pre-requisite library/package 813 to compile Erlang from source code. (#222) 814 8152 October 2017 - 1.6.0 816 817 - Support clang 9 and High Sierra command-line tools (CLT) on older Erlang 818 builds. (#234) 819 - Fix a pointer error in wx on macOS/clang 9 (#235) 820 82125 May 2017 - 1.5.1 822 823 - Bug Fix: Remove spurious spaces (#209) 824 82524 May 2017 - 1.5.0 826 827 - Published an OTP support policy, triage schedule, IRC channel 828 - Apply build patches for Perls >= 5.22 on older OTP releases (#198) 829 - Fix bad `read` usage (#200) 830 - Add a force flag for mv (#201) 831 - Use a more portable way to get perl minor release version (#204) 832 - Force 64 bit flag on macOS (#205) 833 - Fix documentation symlinks (#206) 834 83522 February 2017 - 1.4.2 836 837 - Fixed a syntax error when comparing hash outputs on reconfigurations (#191) 838 - Added the path subcommand; enabled Travis-CI (#190) 839 - Fixed mistakenly omitted version string from past 2 releases. 840 84112 February 2017 - 1.4.1 842 843 - Fix reading a checksum file for compile options (#180) 844 - Get a little smarter about figuring out what apps to use 845 when building a PLT file for dialyzer (#181) 846 8475 February 2017 - 1.4.0 848 849 - Fix environment variable handling and a typo (#179) 850 - Overhaul the README; document all environment variables (#178) 851 - Store build configuration in a file. Enables detecting if configuration has 852 changed from build to build and also allows outputing build time options 853 in `kerl status` (#177) 854 - Assert perl exists before attempting build (#176); fixes issue #170 855 85613 October 2016 - 1.3.4 857 858 - Use a more portable way to restore PATH (#165) 859 - Exit if curl fails. Download files if they are 0 length. (#166) 860 86107 October 2016 - 1.3.3 862 863 - Add support for (T)CSH (#155) 864 - If homebrew is installed, make kerl check for a homebrew OpenSSL library path (#161) 865 - If `--enable-native-libs` is active, make, clean and make again. (#163) 866 86720 July 2016 - 1.3.2 868 869 - Optionally enhance the activation prompt (#149) 870 - Do not permit installation into a location that's already installed (#150) 871 - Fix duplicate response from `kerl prompt` (fix #88) (#150) 872 - Do not run if $HOME is not set. (fix #22) (#151) 873 87416 July 2016 - 1.3.1 875 876 - Fix argument order in archive unpacking (#146) 877 - When building, show output of unmet dependencies or other build prerequisites (#148) 878 8791 July 2016 - 1.3.0 880 881 - basic fish shell support (#91) 882 88328 June 2016 - 1.2.0 884 885 - Make curl output more robust if using a .curlrc (#137) 886 - Apply patches to build older Erlangs (#138) 887 - Add a command to output a version string (#140) 888 - Do not assume success for metadata file writes (#142) 889 - Fix a grammar problem (#145) 890 89120 May 2016 - 1.1.1 892 893 - Remove valid directory check when doing a remote deployment. 894 - Various get_otp_version() regex cleanup/fixes 895 89614 May 2016 - 1.1.0 897 898 - Remove support for Mac OS X Lion. Stop setting CFLAGS for better compiler 899 optimizations. (#132) 900 90114 May 2016 - 1.0.1 902 903 - Be much more careful about installing into and removing directories. (#127) 904 - Make `OTP_GITHUB_URL` and `KERL_BUILD_BACKEND` controllable from .kerlrc (#130) 905 9062 May 2016 - 1.0 907 908 - Support builds from git tags (#122) 909 - Support documentation builds/installs from source code (#126) 910