OTP Release Handling Tutorial.

Introduction

This tutorial attempts to show by example how to build a proper OTP-based system.

A quick way to get started might be to copy this example system, and modify the configuration files. I will try to explain the purpose of each file and suggest how they may be modified.

The Example System

The example system (called "example") runs on two processors (note that the two processors can easily be two Erlang nodes on the same physical machine), and contains two applications:

base, which runs on both processors. This program doesn't do much interesting.

dist, which runs on only one processor at a time. This program does one interesting thing: smooth takeover of state. This involves start phases, the global name server, and some other exciting concepts.

Basic File Structure

Note:

The code is riddled with comments. If you view it with e.g.
Emacs using fontification, it may be easier to read.

The file
example.rel contains hard-coded versions of kernel, stdlib
and sasl. Depending on your version of OTP, the building of the
boot script may fail. Fortunately, the error message is quite
helpful in showing what needs to be changed.

Now, you should be able to see an example.script file in releases/1.0/. It contains instructions for the Erlang/OTP boot loader. The .script file is converted into an Erlang binary which is stored in example.boot in the same directory.

Now, you should be able to see an
example.script file
in releases/1.0/. It contains instructions for the Erlang/OTP
boot loader. The .script file is converted into an Erlang binary
which is stored in example.boot in the same directory.

Making a tar file.

Using systools:make_tar("example", Options) (where Options is the same list of options as for make_script/2, you can pack your release into a tar file, and unpack it on a target system. The -boot_var option makes the code re-locatable. See erl -man systools for more detailed instructions.

Running the example.

There are tricks for starting an embedded system and being able
to attach a shell to a node, but that's another tutorial.
</p>

I will show how one could easily get something up and running
on a Unix workstation. Windows users will have to translate.

Place yourself in $DIR/releases/1.0(for convenience -- you could of course do this from any directory.)

Start two shell windows (e.g. xterm)

In one xterm, write:

Code listing .3

erl -boot ./example -config ./sys -boot_var MYAPPS $DIR -sname n1

In the other xterm, write:

Code listing .4

erl -boot ./example -config ./sys -boot_var MYAPPS $DIR -sname n2

It doesn't really matter if you start both nodes at once, or one
at a time. In the sys.config
file, a node synchronization timeout of 10 seconds was
specified. After that, the first node will continue alone if the
other node has not yet appeared.

Note:

The sys.config file contains hard-coded node names.
You need to make sure that the node
names are correct in your environment for the example to work.

This is of course an interesting thing to try. If you start n1 first, you may see the following output: