Document workaround with relx semver value

1 files changed, 55 insertions, 0 deletions

diff --git a/doc/src/guide/releases.asciidoc b/doc/src/guide/releases.asciidoc
index 67abe87..e571992 100644
--- a/doc/src/guide/releases.asciidoc
+++ b/doc/src/guide/releases.asciidoc
@@ -118,3 +118,58 @@ Or on Windows:
 $ bin/example_release.cmd upgrade "2/example_release"
 
 Your release was upgraded!
+
+=== Getting relx semver value
+
+There is a *workaround* to get the semver version value which is
+generated by relx based on VCS history.
+
+Create `rel/version` file with only one line inside:
+
+[source,erlang]
+{{ release_version }}
+
+Add/Update  `overlay` section of your `relx.config`
+
+[source,erlang]
+{overlay, [
+ {template, rel/version, version}
+]}.
+
+So when you run `mare rel` it creates file like `_rel/app/version` which
+would contain 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 `rel` target
+
+[source,make]
+$(shell cat $(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)
+
+Here is an example of the `Makefile`:
+[source,make]
+include erlang.mk
+#--------------------------- Custom targets -----------------------------------
+APP_VERSION = $(shell cat $(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)
+myrecipe: all
+        echo APP_VERSION = $(APP_VERSION)
+
+The output would be like:
+[source,bash]
+$ make myrecipe
+...
+===> Starting relx build process ...
+===> Resolving OTP Applications from directories:
+          /home/username/myapp/apps
+          /home/username/myapp/deps
+          /usr/lib/erlang/lib
+          /home/username/myapp/_rel
+===> Resolved myapp-0.3.10+build.11.ref5612aa0
+===> Including Erts from /usr/lib/erlang
+===> release successfully created!
+===> tarball /home/username/myapp/_rel/myapp/myapp-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