1Patching OTP Applications 2========================= 3 4Introduction 5------------ 6 7This document describes the process of patching an existing OTP 8installation with one or more Erlang/OTP applications of newer versions 9than already installed. The tool `otp_patch_apply` is available for this 10specific purpose. It resides in the top directory of the Erlang/OTP 11source tree. 12 13The `otp_patch_apply` tool utilizes the [runtime_dependencies][] tag in 14the [application resource file][]. This information is used to determine 15if the patch can be installed in the given Erlang/OTP installation 16directory. 17 18Read more about the [version handling][] introduced in Erlang/OTP release 1917, which also describes how to determine if an installation includes one 20or more patched applications. 21 22If you want to apply patches of multiple OTP applications that resides 23in different OTP versions, you have to apply these patches in multiple 24steps. It is only possible to apply multiple OTP applications from the 25same OTP version at once. 26 27Prerequisites 28------------- 29 30It's assumed that the reader is familiar with 31[building and installing Erlang/OTP][]. To be able to patch an 32application, the following must exist: 33 34* An Erlang/OTP installation. 35 36* An Erlang/OTP source tree containing the updated applications that 37 you want to patch into the existing Erlang/OTP installation. 38 39Using otp\_patch\_apply 40----------------------- 41 42> *WARNING*: Patching applications is a one-way process. 43> Create a backup of your OTP installation directory before 44> proceeding. 45 46First of all, build the OTP source tree at `$ERL_TOP` containing 47the updated applications. 48 49> *NOTE*: Before applying a patch you need to do a *full* build 50> of OTP in the source directory. 51 52If you are building in `git` you first need to generate the 53`configure` scripts: 54 55 $ ./otp_build autoconf 56 57Configure and build all applications in OTP: 58 59 $ configure 60 $ make 61 62or 63 64 $ ./otp_build configure 65 $ ./otp_build boot -a 66 67If you have installed documentation in the OTP installation, also 68build the documentation: 69 70 $ make docs 71 72After the successful build it's time to patch. The source tree directory, 73the directory of the installation and the applications to patch are given 74as arguments to `otp_patch_apply`. The dependencies of each application 75are validated against the applications in the installation and the other 76applications given as arguments. If a dependency error is detected, the 77script will be aborted. 78 79The `otp_patch_apply` syntax: 80 81 $ otp_patch_apply -s <Dir> -i <Dir> [-l <Dir>] [-c] [-f] [-h] \ 82 [-n] [-v] <App1> [... <AppN>] 83 84 -s <Dir> -- OTP source directory that contains build results. 85 -i <Dir> -- OTP installation directory to patch. 86 -l <Dir> -- Alternative OTP source library directory path(s) 87 containing build results of OTP applications. 88 Multiple paths should be colon separated. 89 -c -- Cleanup (remove) old versions of applications 90 patched in the installation. 91 -f -- Force patch of application(s) even though 92 dependencies are not fulfilled (should only be 93 considered in a test environment). 94 -h -- Print help then exit. 95 -n -- Do not install documentation. 96 -v -- Print version then exit. 97 <AppX> -- Application to patch. 98 99 Environment Variable: 100 ERL_LIBS -- Alternative OTP source library directory path(s) 101 containing build results of OTP applications. 102 Multiple paths should be colon separated. 103 104> *NOTE*: The complete build environment is required while running 105> `otp_patch_apply`. 106 107> *NOTE*: All source directories identified by `-s` and `-l` should 108> contain build results of OTP applications. 109 110For example, if the user wants to install patched versions of `mnesia` 111and `ssl` built in `/home/me/git/otp` into the OTP installation 112located in `/opt/erlang/my_otp` type 113 114 $ otp_patch_apply -s /home/me/git/otp -i /opt/erlang/my_otp \ 115 mnesia ssl 116 117> *NOTE*: If the list of applications contains core applications, 118> i.e `erts`, `kernel`, `stdlib` or `sasl`, the `Install` script in 119> the patched Erlang/OTP installation must be rerun. 120 121The patched applications are appended to the list of installed 122applications. Take a look at 123`<InstallDir>/releases/OTP-REL/installed_application_versions`. 124 125Sanity check 126------------ 127 128The application dependencies can be checked using the Erlang shell. 129Application dependencies are verified among installed applications by 130`otp_patch_apply`, but these are not necessarily those actually loaded. 131By calling `system_information:sanity_check()` one can validate 132dependencies among applications actually loaded. 133 134 1> system_information:sanity_check(). 135 ok 136 137Please take a look at the reference of [sanity_check()][] for more 138information. 139 140[application resource file]: kernel:app 141[runtime_dependencies]: kernel:app#runtime_dependencies 142[building and installing Erlang/OTP]: INSTALL.md 143[version handling]: ../system_principles/versions 144[sanity_check()]: runtime_tools:system_information#sanity_check-0 145