appup(5)

okay bestie, this is appup(5) — the application upgrade file manual, and it's giving release-handler main character energy 💅✨. Part 1, so stay with me.

✨ NAME ✨

appup — Application upgrade file

💖 DESCRIPTION 💖

The application upgrade file defines how an application is upgraded or downgraded in a running system. No cap.

This file is used by the functions in systools when generating a release upgrade file relup.

🎀 FILE SYNTAX 🎀

The application upgrade file is to be called Application.appup, where Application is the application name. It is to be located in the ebin directory for the application.

The .appup file contains one single Erlang term, which defines the instructions used to upgrade or downgrade the application. The file has the following syntax:

{Vsn,
  [{UpFromVsn, Instructions}, ...],
  [{DownToVsn, Instructions}, ...]}.

• Vsn = string(): Current application version.
• UpFromVsn = string() | binary(): An earlier application version to upgrade from. If it is a string, it is interpreted as a specific version number. If it is a binary, it is interpreted as a regular expression that can match multiple version numbers.
• DownToVsn = string() | binary(): An earlier application version to downgrade to. If it is a string, it is interpreted as a specific version number. If it is a binary, it is interpreted as a regular expression that can match multiple version numbers.
• Instructions: A list of release upgrade instructions, see Release Upgrade Instructions. It is recommended to use high-level instructions only. These are automatically translated to low-level instructions by systools when creating the relup file.

To avoid duplication of upgrade instructions, it is allowed to use regular expressions to specify UpFromVsn and DownToVsn. To be considered a regular expression, the version identifier must be specified as a binary. For example, the following match all versions 2.1.x, where x is any number:

<<"2\\.1\\.[0-9]+">>

Notice that the regular expression must match the complete version string, so this example works for, for example, 2.1.1, but not for 2.1.1.1.

🔥 RELEASE UPGRADE INSTRUCTIONS 🔥

Release upgrade instructions are interpreted by the release handler when an upgrade or downgrade is made. For more information about release handling, see OTP Design Principles in System Documentation.

A process is said to use a module Mod if Mod is listed in the Modules part of the child specification used to start the process, see supervisor(3erl). In the case of gen_event, an event manager process is said to use Mod if Mod is an installed event handler.

🦋 High-Level Instructions 🦋

update — synchronized code replacement 💅

{update, Mod}
{update, Mod, supervisor}
{update, Mod, Change}
{update, Mod, DepMods}
{update, Mod, Change, DepMods}
{update, Mod, Change, PrePurge, PostPurge, DepMods}
{update, Mod, Timeout, Change, PrePurge, PostPurge, DepMods}
{update, Mod, ModType, Timeout, Change, PrePurge, PostPurge, DepMods}

  Mod = atom()
  ModType = static | dynamic
  Timeout = int()>0 | default | infinity
  Change = soft | {advanced,Extra}
    Extra = term()
  PrePurge = PostPurge = soft_purge | brutal_purge
  DepMods = [Mod]

Synchronized code replacement of processes using module Mod.

All those processes are suspended using sys:suspend, the new module version is loaded, and then the processes are resumed using sys:resume.

• Change: Defaults to soft and defines the type of code change. If it is set to {advanced,Extra}, implemented processes using gen_server, gen_fsm, gen_statem, or gen_event transform their internal state by calling the callback function code_change. Special processes call the callback function system_code_change/4. In both cases, the term Extra is passed as an argument to the callback function.
• PrePurge: Defaults to brutal_purge. It controls what action to take with processes executing old code before loading the new module version. If the value is brutal_purge, the processes are killed. If the value is soft_purge, release_handler:install_release/1 returns {error,{old_processes,Mod}}.
• PostPurge: Defaults to brutal_purge. It controls what action to take with processes that are executing old code when the new module version has been loaded. If the value is brutal_purge, the code is purged when the release is made permanent and the processes are killed. If the value is soft_purge, the release handler purges the old code when no remaining processes execute the code.
• DepMods: Defaults to [] and defines other modules that Mod is dependent on. In the relup file, instructions for suspending processes using Mod come before instructions for suspending processes using modules in DepMods when upgrading, and conversely when downgrading. In case of circular dependencies, the order of the instructions in the appup file is kept.
• Timeout: Defines the time-out when suspending processes. If no value or default is specified, the default value for sys:suspend is used.
• ModType: Defaults to dynamic. It specifies if the code is "dynamic", that is, if a process using the module spontaneously switches to new code, or if it is "static". When doing an advanced update and upgrade, the new version of a dynamic module is loaded before the process is asked to change code. When downgrading, the process is asked to change code before loading the new version. For static modules, the new version is loaded before the process is asked to change code, both in the case of upgrading and downgrading. Callback modules are dynamic.

update with argument supervisor is used when changing the start specification of a supervisor.

load_module — simple code replacement ✨

{load_module, Mod}
{load_module, Mod, DepMods}
{load_module, Mod, PrePurge, PostPurge, DepMods}

  Mod = atom()
  PrePurge = PostPurge = soft_purge | brutal_purge
  DepMods = [Mod]

Simple code replacement of the module Mod.

For a description of PrePurge and PostPurge, see update above.

DepMods defaults to [] and defines which other modules Mod is dependent on. In the relup file, instructions for loading these modules come before the instruction for loading Mod when upgrading, and conversely when downgrading.

add_module — load a new module 🦋

{add_module, Mod}
{add_module, Mod, DepMods}

  Mod = atom()
  DepMods = [Mod]

Loads a new module Mod.

DepMods defaults to [] and defines which other modules Mod is dependent on. In the relup file, instructions related to these modules come before the instruction for loading Mod when upgrading, and conversely when downgrading.

delete_module — delete a module 💀

{delete_module, Mod}
{delete_module, Mod, DepMods}

  Mod = atom()

Deletes a module Mod using the low-level instructions remove and purge.

DepMods defaults to [] and defines which other modules Mod is dependent on. In the relup file, instructions related to these modules come before the instruction for removing Mod when upgrading, and conversely when downgrading.

add_application — add an app 💖

{add_application, Application}
{add_application, Application, Type}

  Application = atom()
  Type = permanent | transient | temporary | load | none

Adding an application means that the modules defined by the modules key in the .app file are loaded using add_module.

Type defaults to permanent and specifies the start type of the application. If Type = permanent | transient | temporary, the application is loaded and started in the corresponding way, see application(3erl). If Type = load, the application is only loaded. If Type = none, the application is not loaded and not started, although the code for its modules is loaded.

remove_application — remove an app 🫶

{remove_application, Application}

  Application = atom()

Removing an application means that the application is stopped, the modules are unloaded using delete_module, and then the application specification is unloaded from the application controller.

restart_application — restart an app 🔄

{restart_application, Application}

  Application = atom()

Restarting an application means that the application is stopped and then started again, similar to using the instructions remove_application and add_application in sequence. Note that, even if the application has been started before the release upgrade is performed, restart_application may only load it rather than start it, depending on the application's start type: If Type = load, the application is only loaded. If Type = none, the application is not loaded and not started, although the code for its modules is loaded.

🌈 Low-Level Instructions 🌈

load_object_code — preload the code 📦

{load_object_code, {App, Vsn, [Mod]}}

  App = Mod = atom()
  Vsn = string()

Reads each Mod from directory App-Vsn/ebin as a binary. It does not load the modules. The instruction is to be placed first in the script to read all new code from the file to make the suspend-load-resume cycle less time-consuming.

point_of_no_return — the point of no return 🚨

point_of_no_return

If a crash occurs after this instruction, the system cannot recover and is restarted from the old release version. The instruction must only occur once in a script. It is to be placed after all load_object_code instructions.

load — load a module 📥

{load, {Mod, PrePurge, PostPurge}}

  Mod = atom()
  PrePurge = PostPurge = soft_purge | brutal_purge

Before this instruction occurs, Mod must have been loaded using load_object_code. This instruction loads the module. PrePurge is ignored. For a description of PostPurge, see the high-level instruction update earlier.

remove — make current version old 🗑️

{remove, {Mod, PrePurge, PostPurge}}

  Mod = atom()
  PrePurge = PostPurge = soft_purge | brutal_purge

Makes the current version of Mod old. PrePurge is ignored. For a description of PostPurge, see the high-level instruction update earlier.

purge — purge old code 💀

{purge, [Mod]}

  Mod = atom()

Purges each module Mod, that is, removes the old code. Notice that any process executing purged code is killed.

suspend — suspend processes ⏸️

{suspend, [Mod | {Mod, Timeout}]}

  Mod = atom()
  Timeout = int()>0 | default | infinity

Tries to suspend all processes using a module Mod. If a process does not respond, it is ignored. This can cause the process to die, either because it crashes when it spontaneously switches to new code, or as a result of a purge operation. If no Timeout is specified or default is specified, the default value for sys:suspend is used.

resume — resume processes ▶️

{resume, [Mod]}

  Mod = atom()

Resumes all suspended processes using a module Mod.

code_change — send a code_change message 🧬

{code_change, [{Mod, Extra}]}
{code_change, Mode, [{Mod, Extra}]}

  Mod = atom()
  Mode = up | down
  Extra = term()

Mode defaults to up and specifies if it is an upgrade or downgrade. This instruction sends a code_change system message to all processes using a module Mod by calling function sys:change_code, passing term Extra as argument.

✋ {stop, [Mod]}

Mod = atom()

Okay bestie, this one stops every single process that's using module Mod by calling supervisor:terminate_child/2. 🛑 Why would you want that? Because sometimes the easiest way to swap out code is literally just to stop the processes running it and boot them back up. Lowkey genius, no cap.

🎬 {start, [Mod]}

Mod = atom()

The glow-up twin of the one above ✨ — it starts all the stopped processes that use module Mod by calling supervisor:restart_child/2. The way that stop/start combo just works? Obsessed. 💅

---

🫂 {sync_nodes, Id, [Node]} and {sync_nodes, Id, {M, F, A}}

Id = term()
Node = node()
M = F = atom()
A = [term()]

apply(M, F, A) must return a list of nodes.

This instruction gets your release installation all in sync with the other nodes, like a group chat where everyone has to react before the convo moves on. 💬 Every Node has to run this command with the same Id. Your local node just sits there waiting for all the other nodes to finish evaluating the instruction before it keeps going. And if a node goes down? 🫠 That's an unrecoverable error, and your local node gets restarted from the old release. Also — there is no time-out for this instruction, which means it can hang forever. Not dramatic, just true. 😭

🪄 {apply, {M, F, A}}

M = F = atom()
A = [term()]

It evaluates apply(M, F, A). Simple as that. ✨

But here's the tea ☕ — if this instruction shows up before the instruction point_of_no_return, a failure gets caught. Then release_handler:install_release/1 returns {error,{'EXIT',Reason}} — unless {error,Error} is thrown or returned, in which case it returns {error,Error} instead.

If it shows up after point_of_no_return and the function call fails? 💀 The system gets restarted. Periodt.

---

🔄 restart_new_emulator

This instruction is the main character when you're upgrading the application ERTS, Kernel, STDLIB, or SASL. It shuts down the current emulator and starts a brand new one. 🦋 All processes are terminated gracefully (no messy exits, we're classy here), and the new versions of ERTS, Kernel, STDLIB, and SASL get used when the emulator restarts.

Rules, bestie, and they're firm 📋:

• Only one restart_new_emulator instruction is allowed in the relup file, and it must be placed first.
• systools:make_relup/3,4 makes sure that's the case when the relup file gets generated.
• The rest of the instructions in the relup file get executed after the restart, as a part of the boot script.

An info report gets written when the upgrade is completed. 📝 Wanna check it programmatically instead of vibing? Call release_handler:which_releases/0,1 and see if the expected release has status current.

And like — the new release must still be made permanent after the upgrade is completed. If you don't, the old emulator starts up if there's an emulator restart. Don't do that to yourself. 🙈

Warning: ⚠️ As stated earlier, the instruction restart_new_emulator causes the emulator to be restarted with new versions of ERTS, Kernel, STDLIB, and SASL. However, all other applications do at startup run their old versions in this new emulator. Usually that's no problem at all, but every now and then incompatible changes happen to the core applications, and that can cause trouble in this setting. Such incompatible changes (when functions are removed) are normally preceded by a deprecation over two major releases. So to make sure your application doesn't get crashed by an incompatible change, always remove any call to deprecated functions as soon as possible. 🧚

---

♻️ restart_emulator

Basically restart_new_emulator's cousin, except this one must be placed at the end of the relup file. It's not tied to an upgrade of the emulator or the core applications — any application can use it when a complete reboot of the system is required. Full send. 🔥

When generating the relup file, systools:make_relup/3,4 makes sure there's only one restart_emulator instruction and that it's the last instruction in the relup file.

---

👀 SEE ALSO

• release_handler(3erl)
• relup(5)
• supervisor(3erl)
• systools(3erl)

---

And that's the whole page, bestie, we ate and left zero crumbs 💖 This one's brought to you by Ericsson AB and it's from sasl 4.2, page appup(5). Go forth and upgrade responsibly. 🎀🌈👑