1  # Emergency patching of OTP modules
 2  
 3  The purpose of this directory is to hold patches for OTP modules.
 4  The patch files are generated using `git diff`, e.g.
 5  
 6  ## Usage
 7  
 8  ```
 9  git diff OTP-20.1 -- lib/mnesia/src/mnesia_index.erl > $OTP_PATCHES/20.1/mnesia_index.erl.patch
10  ```
11  
12  Patch files are stored in version-specific subdirectories. In each such
13  subdirectory, a `versions.eterm` file contains patterns identifying which
14  OTP application versions are compatible with the patches.
15  
16  The `versions.eterm` file is read with `file:consult/1`, and shall
17  contain `{AppName, BaseNameRegexp}` tuples. For example:
18  
19  ```erlang
20  {mnesia, "mnesia-4\\.15\\.[123]"}.
21  ```
22  
23  which matches mnesia versions `"4.15.1"`, `"4.15.2"` and `"4.15.3"`.
24  
25  The compile script will test each subdirectory, and pick the first one
26  for which all application patterns match. It will then copy the relevant
27  source files from the current OTP to the `otp_patches` directory, apply
28  the patches and compile the result into `otp_patches/ebin`. This directory
29  will then be copied into the release and pre-pended to the code path of
30  the system.
31  
32  ## rebar3 hook
33  
34  In the `rebar.config` file, the patch compilation can be specified as
35  a `pre_hook`, e.g.
36  
37  ```
38  {pre_hooks, [{compile, "escript ./otp_patches/compile.escript"},
39               ...]}.
40  ```
41  
42  ## Compile options
43  
44  Currently, files are compiled with `debug_info` and include paths to the
45  `src/` and `include/` directories of the source file's application.
46  More compile options, and support for specifying options per-application
47  or per-module may have to be added later.