Patching OTP Applications ========================= Introduction ------------ This document describes the process of patching an existing OTP installation with one or more Erlang/OTP applications of newer versions than already installed. The tool `otp_patch_apply` is available for this specific purpose. It resides in the top directory of the Erlang/OTP source tree. The `otp_patch_apply` tool utilizes the [runtime_dependencies][] tag in the [application resource file][]. This information is used to determine if the patch can be installed in the given Erlang/OTP installation directory. Read more about the [version handling][] introduced in Erlang/OTP release 17, which also describes how to determine if an installation includes one or more patched applications. If you want to apply patches of multiple OTP applications that resides in different OTP versions, you have to apply these patches in multiple steps. It is only possible to apply multiple OTP applications from the same OTP version at once. Prerequisites ------------- It's assumed that the reader is familiar with [building and installing Erlang/OTP][]. To be able to patch an application, the following must exist: * An Erlang/OTP installation. * An Erlang/OTP source tree containing the updated applications that you want to patch into the existing Erlang/OTP installation. Using otp\_patch\_apply ----------------------- > *WARNING*: Patching applications is a one-way process. > Create a backup of your OTP installation directory before > proceeding. First of all, build the OTP source tree at `$ERL_TOP` containing the updated applications. > *NOTE*: Before applying a patch you need to do a *full* build > of OTP in the source directory. If you are building in `git` you first need to generate the `configure` scripts: $ ./otp_build autoconf Configure and build all applications in OTP: $ configure $ make or $ ./otp_build configure $ ./otp_build boot -a If you have installed documentation in the OTP installation, also build the documentation: $ make docs After the successful build it's time to patch. The source tree directory, the directory of the installation and the applications to patch are given as arguments to `otp_patch_apply`. The dependencies of each application are validated against the applications in the installation and the other applications given as arguments. If a dependency error is detected, the script will be aborted. The `otp_patch_apply` syntax: $ otp_patch_apply -s <Dir> -i <Dir> [-l <Dir>] [-c] [-f] [-h] \ [-n] [-v] <App1> [... <AppN>] -s <Dir> -- OTP source directory that contains build results. -i <Dir> -- OTP installation directory to patch. -l <Dir> -- Alternative OTP source library directory path(s) containing build results of OTP applications. Multiple paths should be colon separated. -c -- Cleanup (remove) old versions of applications patched in the installation. -f -- Force patch of application(s) even though dependencies are not fulfilled (should only be considered in a test environment). -h -- Print help then exit. -n -- Do not install documentation. -v -- Print version then exit. <AppX> -- Application to patch. Environment Variable: ERL_LIBS -- Alternative OTP source library directory path(s) containing build results of OTP applications. Multiple paths should be colon separated. > *NOTE*: The complete build environment is required while running > `otp_patch_apply`. > *NOTE*: All source directories identified by `-s` and `-l` should > contain build results of OTP applications. For example, if the user wants to install patched versions of `mnesia` and `ssl` built in `/home/me/git/otp` into the OTP installation located in `/opt/erlang/my_otp` type $ otp_patch_apply -s /home/me/git/otp -i /opt/erlang/my_otp \ mnesia ssl > *NOTE*: If the list of applications contains core applications, > i.e `erts`, `kernel`, `stdlib` or `sasl`, the `Install` script in > the patched Erlang/OTP installation must be rerun. The patched applications are appended to the list of installed applications. Take a look at `<InstallDir>/releases/OTP-REL/installed_application_versions`. Sanity check ------------ The application dependencies can be checked using the Erlang shell. Application dependencies are verified among installed applications by `otp_patch_apply`, but these are not necessarily those actually loaded. By calling `system_information:sanity_check()` one can validate dependencies among applications actually loaded. 1> system_information:sanity_check(). ok Please take a look at the reference of [sanity_check()][] for more information. [application resource file]: kernel:app [runtime_dependencies]: kernel:app#runtime_dependencies [building and installing Erlang/OTP]: INSTALL.md [version handling]: ../system_principles/versions [sanity_check()]: runtime_tools:system_information#sanity_check-0