From 20f480531e0caafcb1f988eaadea1b3b6a3caf72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Fri, 28 Oct 2016 19:22:49 +0300 Subject: 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. :-) --- core/core.mk | 4 ++- doc/src/guide/releases.asciidoc | 54 +++++++++++++++++++++++++++++++++++++++-- plugins/relx.mk | 9 +++++-- test/plugin_relx.mk | 6 ++--- 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)//-.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 # 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 -- cgit v1.2.3