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