3 The Release Structure
Erlang programs are organized into modules. Each module in a release must have a unique name.
Collections of modules which cooperate to solve a particular problem are organized into applications. Applications are described in an application resource file.
Collections of applications are organized into a release. Releases are described in a release resource file.
3.1 Naming of Modules, Applications and Releases
Each module in the system has a version number. An Erlang module should start with
-module(Mod). -vsn(Vsn). ...and should be stored in a file named as
Mod.erl.The name of the module is
Modand the version of the module isVsn.Modmust be an atom whileVsncan be any valid Erlang term. For example, the version can be an integer or a string, which represents an Ericsson product number.Also the applications have versions, but the version must be a string. For example, the application resource file for the application named
snmpmust be stored in a file namedsnmp.appand must start:{application, snmp, [{vsn, Va}, {modules, [{lists, V1}, {ordsets, V2} ...Here,
Vais the version of the application (a string). The application uses the Erlang module versionsV1, V2, ..., whereV1, V2, ...can be any valid Erlang terms. The only requirement is that the module version types (integers, strings, etc.) agrees with the convention used in the module declarations.
In the application resource file, the name of a module must be specified in
modules, but the version number is not a mandatory requirement. Hence the following is also valid contents for an application resource file:{application, snmp, [{vsn, Va}, {modules, [lists, ordsets, ...Applications can be upgraded and the instructions to do this are placed in the
.appupfile for the application. For example, for thesnmpapplication these instructions are placed in thesnmp.appupfile. An.appupfile contains the following:{Vsn, [{UpFromVsn, UpFromScript}, ...], [{DownToVsn, DownToScript}, ...] }.
Vsnis the version of the application
UpFromVsnis a version we can upgrade from
UpFromScriptis the script which describes the sequence of release upgrade instructions. Refer to the section Release Handling Instructions
DownToVsnis a version to which we can downgrade
DownToScriptis the script which describes the sequence of downgrade instructions.
In the case of
UpFromScriptandDownFromScript, the scripts typically contain one line for each module in the application.A release resource file has a structure similar to an application resource file. The file
ReleaseFileName.rel, which describes the release contains the following:{release, {Name,Vsn}, {erts, EVsn}, [{AppName, AppVsn}, {AppName, AppVsn, AppType}, {AppName, AppVsn, IncApps}, {AppName, AppVsn, AppType, IncApps} ...]}.
Nameis the name of the release (a string).Nameneeds not to be the same asReleaseFileNameabove.
Vsnis the version of the release (a string).
{erts, EVsn}indicates which Erlang runtime system versionEVsnthe release is intended for, for example "4.4".EVsnmust be a string.
AppNameis the name of an application included in the release (an atom).
AppVsnis the version of theAppNameapplication (a string).
- The application is started by a call to
application:start(AppName, AppType), if theAppTypeispermanent,transientortemporary. IfAppTypeisloadthe application is loaded but not started, and if it isnonethe application is neither loaded or started.
IncAppsis a list of applications that are included by an application, for example[AppName, ...]. This list overrides theincluded_applicationskey in the application resource file.app. It must be a subset of the list of included applications which are specified in the.appfile.
The list of applications must contain the
kerneland thestdlibapplications.Releases can also be upgraded and instructions for this should be written in the
relupfile (see the definition of the relup file). The tedious work of writing therelupfile is automated and in most cases, the file will be automatically generated from the.appupfiles for the applications in the release.3.2 Release Tools
There are tools available to build and check release packages. These tools read the release resource file, the application resource files and upgrade files, and they generate a boot script, a release upgrade script, and also build a release package.
The following functions are in the
systoolsmodule:
make_scriptgenerates a boot script
make_relupgenerates a release upgrade script
make_targenerates a release package.tarfile .
These functions read the
.relrelease resource file from the current directory and perform syntax and dependency checks before the output is generated.
The generated files are written to the current directory as well.
Refer to the Reference Manual for more information about these functions.
3.3 Release Directories
A release should be divided into the following directories:
$ROOTDIR/lib/App1-AVsn1/ebin /priv /App2-AVsn2/ebin /priv ... /AppN-AVsnN/ebin /priv /erts-EVsn/bin /releases/Vsn /binThe release resource file includes one
AppN-AVsnNdirectory per application.AppNis the name andAVsnNis the version of the application.
- The
ebindirectory contains the Erlang object code and the application resource file.
- The
privdirectory contains any application private data. Specifically, port programs should be located in theprivdirectory. Theprivdirectory of an application is found by a call tocode:priv_dir(AppName).
- The boot script and relup files should be located in the
releases/Vsndirectory.Vsnis the release version found in the release resource file.
- The Erlang runtime system executables are located in the
erts-EVsn/bindirectory.
- The
releasesdirectory should also contain theReleaseFileName.relfiles, and new release packages are installed here.
- The
bindirectory contains the top level Erlang executable programerl.
Applications are not required to be located under the
$ROOTDIR/libdirectory. Accordingly, several installation directories may exist which contain different parts of a system. For example, the previous example could be extended as follows:$SECOND_ROOT/.../SApp1-SAVsn1/ebin /priv /SApp2-SAVsn2/ebin /priv ... /SAppN-SAVsnN/ebin /priv $THIRD_ROOT/TApp1-TAVsn1/ebin /priv /TApp2-TAVsn2/ebin /priv ... /TAppN-TAVsnN/ebin /privThe
$SECOND_ROOTand$THIRD_ROOTare introduced asvariablesin the call to thesystools:make_script/2function.3.3.1 Disk-less and/or Read-Only Clients
If a complete system consists of some disk-less and/or read-only client nodes, a
clientsdirectory should be added to the$ROOTDIRdirectory. By a read-only node we mean a node with a read-only file system.The
clientsdirectory should have one sub-directory per supported client node. The name of each client directory should be the name of the corresponding client node. As a minimum, each client directory should contain thebinandreleasessub-directories. These directories are used to store information about installed releases and to appoint the current release to the client. Accordingly, the$ROOTDIRdirectory contains the following:$ROOTDIR/... /clients/ClientName1/bin /releases/Vsn /ClientName2/bin /releases/Vsn ... /ClientNameN/bin /releases/VsnThis structure should be used if all clients are running the same type of Erlang machine. If there are clients running different types of Erlang machines, or on different operating systems, the
clientsdirectory could be divided into one sub-directory per type of Erlang machine. Alternatively, you can set up oneROOTDIRper type of machine. For each type, some of the directories specified for theROOTDIRdirectory should be included:$ROOTDIR/... /clients/Type1/lib /erts-EVsn /bin /ClientName1/bin /releases/Vsn /ClientName2/bin /releases/Vsn ... /ClientNameN/bin /releases/Vsn ... /TypeN/lib /erts-EVsn /bin ...With this structure, the root directory for clients of
Type1is$ROOTDIR/clients/Type1.3.4 Example
Suppose we have a system called "test", which consists of the three applications:
snmp,kernelandstdlib. Thesnmpapplication is described in the application resource filesnmp.appas follows:{application, snmp, [{vsn, "10"}, {modules, [{snmp_table, 2}, {snmp_map, 3}, {snmp_stuff,5}]}, {applications, [stdlib, kernel]}, {mod, {snmp_stuff, [12,34]}} ]}.
The resource file shown contains only a sub-set of the information available in the actual resource files. Refer to the Design Principles chapter, section Applications for a more detailed description of the contents of an application resource file.
In the example shown, version "10" of
snmpuses version 2 ofsnmp_table, version 3 ofsnmp_mapan so on. It requires thatstdlibandkernelare started before this application is started. It is started by evaluating the functionsnmp_stuff:start(normal, [12,34]).snmp_stuffis the SNMP application call-back module for the application complying with the behaviorapplication.
We have used integer version numbers written as strings for the application version. In our further discussion we will simplify things by using integer version numbers. We will also assume that version N+1 is the successor of version N of a system component.
The application resource file
stdlib.appforstdlibversion "6" contains the following:{application, stdlib, [{vsn, "6"}, {modules, [{lists,2}, {dict,4}, {ordsets, 7}]}, {applications, []}, ]}.
stdlibis a "code only" application and has no call-back module.Finally, the
kernel.appfile of thekernelapplication version "2" contains the following:{application, kernel, [{vsn, "2"}, {modules, [{net_kernel, 3}, {auth, 3}, {rcp, 5}]}, {applications, [stdlib]}, {mod, {net_kernel,[]}} ]}.We can now in the
test1.relfile define release "5" of the "test" release in terms of these applications:{release, {"test", "5"}, {erts, "4.4"}, [{kernel, "2"}, {stdlib, "6"}, {snmp, "10"} ]}.
This means that release "5" of the "test" system is built from
kernelversion "2",stdlibversion "6". The release requires the Erlang runtime system "4.4".3.4.1 Making the Start Script
In the example shown, we have defined enough to be able to generate a system. We now have to generate a start script off-line which will be used when the system is loaded. We evaluate:
systools:make_script("test1")where
test1refers to thetest1.relfile.This command reads the
test1.relfile and checks that all applications required for the release can be found and that all the modules which are required can be located and have the correct version numbers.All required application resource files and all required Erlang files must be located somewhere within the current code path,
{path, Path}.If there were no errors, a start script called
test1.scriptand a boot file calledtest1.bootare created. The latter is a binary version of the former, and is used when starting the system (e.g. by issuing the commanderl -boot test1).3.4.2 Changing an Application
Suppose now that we make a change to
snmpwhich results in new versions of the modulessnmp_mapandsnmp_stuff. This is specified as follows in a new version ofsnmp.app:{application, snmp, [{vsn,"11"}, {modules, [{snmp_table, 2}, {snmp_map, 4}, {snmp_stuff,6}]}, {applications, [stdlib, kernel]}, {mod, {snmp_stuff, [12,34]}} ]}.
We have changed the two modules
snmp_mapandsnmp_stuff. Everything else remains the same.We can now define a new release of the system in the file
test2.relas follows:{release, {"test","6"}, {erts, "4.4"}, [{kernel, "2"}, {stdlib, "6"}, {snmp, "11"} ]}.As before we generate the
test2.scriptandtest2.bootfile by callingsystools:make_script("test2").So far we have version "5" and "6" of the "test" release defined in the
test1.relandtest2.relfiles, and the generated script and boot filestest1.script,test1.boot,test2.script, andtest2.boot. In our example two versions of the "test" release only differ in the contents of thesnmpapplication. In order to be able to update from version "5" to version "6" of the "test" release, we have to provide a specification of the upgrade of thesnmpapplication in the form of an application upgrade filesnmp.appup.The contents of the
snmp.appupfile is as follows:{"11", [{"10", [{update, snmp_map, soft, soft_purge, soft_purge, []}, {update, snmp_stuff, soft, soft_purge, soft_purge, []}]}], [{"10", [{update, snmp_map, soft, soft_purge, soft_purge, []}, {update, snmp_stuff, soft, soft_purge, soft_purge, []}]}] }.The
snmpapplication is upgraded by changing code for thesnmp_mapandsnmp_stuffmodules. It is downgraded by changing code for the same two modules.Since only the
snmpapplication was changed between version "5" and version "6" of the "test" release, no.appupfiles are needed for the other applications.In order to finish the specification of the upgrade of the complete "test" release, a release upgrade file,
relup, has to be created (relupis not a file suffix; the complete name of the file isrelup). Therelupfile is created by evaluating:systools:make_relup("test2", ["test1"], ["test1"]).Here the first argument is name of the
.relfile we upgrade to or downgrade from. The second and third arguments are lists of.relfiles, specifying releases to upgrade from, and downgrade to, respectively.A
relupfile contains low-level code change instructions for the whole release, based on all application.appupfiles.3.4.3 Making a Release Package
Next, we want to generate a release package which can be installed in the target system. After evaluating
make_script/1andmake_relup/3as described above, we do it by evaluatingsystools:make_tar("test2").A release package file, named
test2.tar.gzis generated. The release package file may be installed in a target system by using the release_handler.In this example, the release package file will contain all applications of version "6" of the "test" release, and also a
releasesdirectory with the following contents:$ROOTDIR/releases/test2.rel /6/relup /start.bootwhere
start.bootis a copy of the originaltest2.boot.