Add "make relup"

The initial documentation is a bit rough. It's getting late and
I'd like to have this in sooner rather than later. :-)

4 files changed, 65 insertions, 8 deletions

diff --git a/core/core.mk b/core/core.mk
index 0331489..10fe0a0 100644
--- a/core/core.mk
+++ b/core/core.mk
@@ -12,7 +12,7 @@
 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-.PHONY: all app apps deps search rel docs install-docs check tests clean distclean help erlang-mk
+.PHONY: all app apps deps search rel relup docs install-docs check tests clean distclean help erlang-mk
 
 ERLANG_MK_FILENAME := $(realpath $(lastword $(MAKEFILE_LIST)))
 
@@ -96,6 +96,8 @@ all:: deps app rel
 rel::
 	$(verbose) :
 
+relup:: deps app
+
 check:: tests
 
 clean:: clean-crashdump
diff --git a/doc/src/guide/releases.asciidoc b/doc/src/guide/releases.asciidoc
index 46183e6..79cd123 100644
--- a/doc/src/guide/releases.asciidoc
+++ b/doc/src/guide/releases.asciidoc
@@ -17,12 +17,11 @@ RELX_CONFIG = $(CURDIR)/webchat.config
 
 Relx does not need to be installed. Erlang.mk will download
 and build it automatically.
-// @todo We are going to fetch relx from repository in the future.
 
 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 repository by ???
+// @todo You can use a custom location by ???
 
 === Configuration
 
@@ -56,6 +55,10 @@ 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
@@ -68,3 +71,50 @@ 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!
diff --git a/plugins/relx.mk b/plugins/relx.mk
index 25e8509..9a15f4a 100644
--- a/plugins/relx.mk
+++ b/plugins/relx.mk
@@ -1,7 +1,7 @@
 # Copyright (c) 2013-2016, Loïc Hoguin <[email protected]>
 # This file is part of erlang.mk and subject to the terms of the ISC License.
 
-.PHONY: relx-rel distclean-relx-rel run
+.PHONY: relx-rel relx-relup distclean-relx-rel run
 
 # Configuration.
 
@@ -23,6 +23,8 @@ endif
 ifeq ($(IS_DEP),)
 ifneq ($(wildcard $(RELX_CONFIG)),)
 rel:: relx-rel
+
+relup:: relx-relup
 endif
 endif
 
@@ -35,7 +37,10 @@ $(RELX):
 	$(verbose) chmod +x $(RELX)
 
 relx-rel: $(RELX) rel-deps app
-	$(verbose) $(RELX) -c $(RELX_CONFIG) $(RELX_OPTS)
+	$(verbose) $(RELX) -c $(RELX_CONFIG) $(RELX_OPTS) release tar
+
+relx-relup: $(RELX) rel-deps app
+	$(verbose) $(RELX) -c $(RELX_CONFIG) $(RELX_OPTS) release relup tar
 
 distclean-relx-rel:
 	$(gen_verbose) rm -rf $(RELX_OUTPUT_DIR)
diff --git a/test/plugin_relx.mk b/test/plugin_relx.mk
index 3cd1392..0afdce1 100644
--- a/test/plugin_relx.mk
+++ b/test/plugin_relx.mk
@@ -69,7 +69,7 @@ endif
 		"test() -> old." > $(APP)/src/test.erl
 
 	$i "Build the initial release as a tarball"
-	$t $(MAKE) -C $(APP) RELX_OPTS="release tar" $v
+	$t $(MAKE) -C $(APP) $v
 
 	$i "Update the test module"
 	$t sed -i s/"test() -> old."/"test() -> new."/ $(APP)/src/test.erl
@@ -92,7 +92,7 @@ endif
 	$t sed -i s/"1"/"2"/ $(APP)/relx.config
 
 	$i "Build a new release with a relup as a tarball"
-	$t $(MAKE) -C $(APP) RELX_OPTS="release relup tar" $v
+	$t $(MAKE) -C $(APP) relup $v
 
 	$i "Test that both releases are available"
 	$t test -f $(APP)/_rel/$(APP)_release/$(APP)_release-1.tar.gz
@@ -185,7 +185,7 @@ relx-tar: build clean
 	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap bootstrap-rel $v
 
 	$i "Build the release as a tarball"
-	$t $(MAKE) RELX_OPTS="release tar" -C $(APP) $v
+	$t $(MAKE) -C $(APP) $v
 
 	$i "Check that tarball exists"
 	$t test -f $(APP)/_rel/$(APP)_release/$(APP)_release-1.tar.gz