User's Guide
PDF
Top

System Principles
User's Guide
Version 6.1

Expand All
Contract All

Chapters

• System Principles
  • Top of chapter
  • Starting the System
  • Restarting and Stopping the System
  • Boot Scripts
  • Code Loading Strategy
  • File Types
• Error Logging
  • Top of chapter
  • Error Information From the Runtime System
  • SASL Error Logging
• Creating and Upgrading a Target System
  • Top of chapter
  • Introduction
  • Creating a Target System
  • Installing a Target System
  • Starting a Target System
  • System Configuration Parameters
  • Differences from the Install Script
  • Creating the Next Version
  • Upgrading the Target System
  • Listing of target_system.erl
• Upgrade when Erlang/OTP has Changed
  • Top of chapter
  • Introduction
  • Upgrade of core applications
  • Applications that still do not allow code upgrade
• Versions
  • Top of chapter
  • OTP Version
  • Application Version
  • Version Scheme
  • OTP 17.0 Application Versions

4 Upgrade when Erlang/OTP has Changed

4.1  Introduction

As of Erlang/OTP 17, most applications deliver a valid application upgrade (appup) file. In earlier releases, a majority of the applications in Erlang/OTP did not support upgrade at all. Many of the applications use the restart_application instruction. These are applications for which it is not crucial to support real soft upgrade, for instance tools and library applications. The restart_application instruction ensures that all modules in the application are reloaded and thereby running the new code.

4.2  Upgrade of core applications

The core applications ERTS, Kernel, STDLIB and SASL never allow real soft upgrade, but require the Erlang emulator to be restarted. This is indicated to the release_handler by the upgrade instruction restart_new_emulator. This instruction will always be the very first instruction executed, and it will restart the emulator with the new versions of the above mentioned core applications and the old versions of all other applications. When the node is back up all other upgrade instructions are executed, making sure each application is finally running its new version.

It might seem strange to do a two-step upgrade instead of just restarting the emulator with the new version of all applications. The reason for this design decision is to allow code_change functions to have side effects, for example changing data on disk. It also makes sure that the upgrade mechanism for non-core applications does not differ depending on whether or not core applications are changed at the same time.

If, however, the more brutal variant is preferred, it is possible to handwrite the release upgrade file using only the single upgrade instruction restart_emulator. This instruction, in contrast to restart_new_emulator, will cause the emulator to restart with the new versions of all applications.

Note that if other instructions are included before restart_emulator in the handwritten relup file, they will be executed in the old emulator. This is a big risk since there is no guarantee that new beam code can be loaded into the old emulator. Adding instructions after restart_emulator has no effect as the release_handler will not do any attempt at executing them.

See relup(4) for information about the release upgrade file, and appup(4) for further information about upgrade instructions.

4.3  Applications that still do not allow code upgrade

A few applications, for instance HiPE do not support upgrade at all. This is indicated by an application upgrade file containing only {Vsn,[],[]}. Any attempt at creating a release upgrade file with such input will fail. The only way to force an upgrade involving applications like this is to handwrite the relup file, preferably as described above with only the restart_emulator instruction.