One of the neatest aspects of erlang is the OTP release system, which allows you to do real-time upgrades of your application code. But before you can take advantage of it, you need to create a embedded first target system. Unfortunately, the documentation can be quite hard to follow, so this is my attempt at clearly explaining how to create your own first target system. At 12 steps, it’s definitely not simple, but you only have to get it right once 🙂
Assumptions
- You’re running linux/unix, probably Ubuntu.
- You already have the desired version of erlang installed. I’ll refer to the install dir as
$ERLDIR
, which should be the same ascode:root_dir().
The latest release, as of 6/1/2009, is R13B01, with erts-5.7.2. - You have your own application code that you want to include in the target system. These apps are located in
$REPODIR/lib/
, follow the OTP directory structure, and have app files inebin/
.
Steps
- Create the initial release resource file , which I’ll refer to as
FIRST.rel
. I’ll also assume the release version is1.0
. The rel file should include your own applications as well as any OTP applications your code depends on. PutFIRST.rel
in the directory you want to use for creating your target system, such as/tmp/build/
. Warning: do not put this file inÂ$REPODIR/releases/
. Otherwise step 5 will not work because systools will have issues creating the package. - Optional: Create sys.config in the same directory as
FIRST.rel
.sys.config
can be used to override the default application configuration for any application include in the release. - Open an erlang console in the same directory as
FIRST.rel
. This directory is where the target system will be created. - Call
systools:make_script("FIRST", [no_module_tests, {path, ["$REPODIR/lib/*/ebin"]}]).
This will create a boot script for the target system. The script file must be created for the next step to work. - Call
systools:make_tar("FIRST", [no_module_tests, {path, ["$REPODIR/lib/*/ebin"]}, {dirs, [include, src]}, {erts, "$ERLDIR"}])
. This will create a release package containing your code and include files, plus all the.beam
files for the included OTP applications. Note:Âno_module_tests
will ignore errors that don’t matter, such as missingsrc
code, which is common for OTP apps. - Exit the console. You should find
FIRST-1.0.tar.gz
in your current directory. Ideally, this would be the last step, but more likely, you’ll need to do the customizations covered below. Unpack the tarball into your target directory andcd
into it. For a different take on these first steps, check out An Introduction to Releases with Erlybank. - Copy
erts-5.7.2/bin/start
intobin/
(ifbin/
doesn’t exist, create it). Editbin/start
and set theROOTDIR
to your target directory (which should also be your current directory). This is the same$ROOTDIR
referred to below. Also copyerts-5.7.2/bin/run_erl
anderts-5.7.2/bin/start_erl
intobin/
, then domkdir log
(or change the paths at the bottom ofbin/start
). At this point, you may also want to add your own emulator flags, such asÂ-sname NODE -smp auto -setcookie MYCOOKIE +A 128.
- Copy
erts-5.7.2/bin/erl
intobin/
and set the sameROOTDIR
as you did inbin/start
. - Copy
$ERLDIR/bin/start_clean.boot
or$ERLDIR/bin/start_sasl.boot
tobin/start.boot
. I like usingstart_sasl.boot
since it provides more logging. But if you don’t want extra logging, usestart_clean.boot
. - Run
echo
"5.7.2
1.0"
>
releases/start_erl.data
. This tells erlang which version oferts
to run, and which release version to use at startup. - Run
bin/erl
and callrelease_handler:create_RELEASES("$ROOTDIR", "$ROOTDIR/releases/", "$ROOTDIR/releases/FIRST.rel", []).
Exit the console, and there should be a filereleases/RELEASES
containg a spec. - That’s it, you’re done! At this point you should be able to run
bin/start
, then usebin/to_erl
to get the console (Ctrl-D to exit). If you want to deploy to other nodes, you can repack the target system, distribute it to each node, then unpack it and runbin/start
. If you do distribute to other nodes, make sure to unpack in the same location on each node, otherwise you’ll have to go back to step 7 and modifyROOTDIR
.
Fin
At this point you should have customized, self-contained erlang target system that you can distribute and run on all your nodes. Now you can finally take advantage of release handling with hot code swapping. In an upcoming article, I’ll cover how to deploy release upgrades using reltools and fab.