1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
[[relx]]
== Releases
Erlang.mk relies on _Relx_ for generating releases. This
chapter covers the Erlang.mk-specific bits. Consult the
https://erlware.github.io/relx/[Relx website] for more information.
=== Setup
Erlang.mk will create a release if it detects a Relx configuration
file in the '$(RELX_CONFIG)' location. This defaults to
'$(CURDIR)/relx.config'. You can override it by defining
the variable before including Erlang.mk:
[source,make]
RELX_CONFIG = $(CURDIR)/webchat.config
It is also possible to have multiple 'relx.config' files.
For example you might have one for development and one for
production. You can use conditionals to decide which one
should be used:
[source,make]
----
ifdef PROD
RELX_CONFIG = $(CURDIR)/relx.prod.config
else
RELX_CONFIG = $(CURDIR)/relx.dev.config
endif
----
Relx does not need to be installed. Erlang.mk will download
and build it automatically.
The Relx executable will be saved in the '$(RELX)' file. This
location defaults to '$(CURDIR)/relx' and can be overriden.
// @todo You can use a custom location by ???
=== Configuration
You can specify additional Relx options using the `RELX_OPTS`
variable. For example, to enable `dev_mode`:
[source,make]
RELX_OPTS = -d true
While you can specify the output directory for the release
in the Relx options directly, Erlang.mk provides a specific
variable for it: `RELX_OUTPUT_DIR`. It defaults to the '_rel'
directory. You can also override it:
[source,make]
RELX_OUTPUT_DIR = /path/to/staging/directory
=== Generating the release
Now that you're all set, all you need to do is generate the
release. As mentioned before, Erlang.mk will automatically
generate it when it detects the '$(RELX_CONFIG)' file. This
means the following command will also build the release:
[source,bash]
$ make
If you need to generate the release, and only the release,
the `rel` target can be used:
[source,bash]
$ make rel
Erlang.mk always generates a tarball alongside the release,
which can be directly uploaded to a server. The tarball is
located at `$(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz`.
=== Running the release
Erlang.mk provides a convenience function for running the
release with one simple command:
[source,bash]
$ make run
This command will also build the project and generate the
release if they weren't already. It starts the release in
_console mode_, meaning you will also have a shell ready to
use to check things as needed.
=== Upgrading a release
Erlang.mk provides a `relup` target for generating release
upgrades. Release upgrades allow updating the code and the
state of a running release without restarting it.
Once your changes are done, you need to update the version
of the application(s) that will be updated. You also need
to update the version of the release.
For each application that needs to be updated, an
http://erlang.org/doc/man/appup.html[appup file]
must be written. Refer to the Erlang/OTP documentation
for more details.
For the purpose of this section, assume the initial release
version was `1`, and the new version is `2`. The name of the
release will be `example`.
Once all this is done, you can build the tarball for the
release upgrade:
[source,bash]
$ make relup
This will create an archive at the root directory of the
release, `$RELX_OUTPUT_DIR/example/example-2.tar.gz`.
Move the archive to the correct location on the running
node. From the release's root directory:
[source,bash]
$ mkdir releases/2/
$ mv path/to/example-2.tar.gz releases/2/
Finally, upgrade the release:
[source,bash]
$ bin/example_release upgrade "2/example_release"
Or on Windows:
[source,bash]
$ bin/example_release.cmd upgrade "2/example_release"
Your release was upgraded!
=== Getting Relx semver value
There is a *workaround* to get the semver value which is
generated by Relx based on VCS history.
Create a file 'config/version' with only one line inside:
[source,erlang]
{{ release_version }}
Add/Update the `overlay` section of your `relx.config`:
[source,erlang]
{overlay, [
{template, "config/version", "version"}
]}.
When you run `make rel` it creates the file '$(RELX_OUTPUT_DIR)/example/version'
which contains the version value generated by Relx.
[source,bash]
$ cat _rel/app/release
1.0.0+build.11.ref5612aa0
In your `Makefile` you can use this simple snippet to get the version,
but please keep in mind that this should depend on the `rel` target:
[source,make]
$(shell cat $(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)
For example:
[source,make]
----
include erlang.mk
APP_VERSION = $(shell cat $(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)
myrecipe: all
echo APP_VERSION = $(APP_VERSION)
----
Would output:
[source,bash]
----
$ make myrecipe
...
===> Starting relx build process ...
===> Resolving OTP Applications from directories:
/home/username/example/apps
/home/username/example/deps
/usr/lib/erlang/lib
/home/username/example/_rel
===> Resolved example-0.3.10+build.11.ref5612aa0
===> Including Erts from /usr/lib/erlang
===> release successfully created!
===> tarball /home/username/example/_rel/example/example-0.3.10+build.11.ref5612aa0.tar.gz successfully created!
echo APP_VERSION = 0.3.10+build.11.ref5612aa0
APP_VERSION = 0.3.10+build.11.ref5612aa0
----
|
