第9章 發行版

原文連接  https://erlang.mk/guide/relx.html

 

Chapter 9. Releases

 

Erlang.mk relies on Relx for generating releases. This chapter covers the Erlang.mk-specific bits. Consult the Relx website for more information.

Erlang.mk依靠Relx來生成發行版。 本章只介紹與Erlang.mk相關的Relx知識。 更多信息請訪問Relx網站。

 

9.1. Setup

9.1. 設置

 

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:

若是Erlang.mk檢測到 $(RELX_CONFIG) 處的Relx配置文件，它將建立一個發行版。$(RELX_CONFIG) 默認是 $(CURDIR)/relx.config，你能夠在包含 Erlang.mk 前經過RELX_CONFIG變量來更改它。

RELX_CONFIG = $(CURDIR)/webchat.config

 

Relx does not need to be installed. Erlang.mk will download and build it automatically.

Relx不須要安裝，Erlang.mk會自動下載並構建它。

 

The Relx executable will be saved in the $(RELX) file. This location defaults to $(CURDIR)/relx and can be overriden.

Relx執行文件被保存在 $(RELX) ，這個位置默認是 $(CURDIR)/relx，但能夠被重寫。

 

9.2. Configuration

9.2. 配置

 

You can specify additional Relx options using the RELX_OPTS variable. For example, to enable dev_mode:

你能夠使用 RELX_OPTS 變量來指定其餘的Relx選項。例如，要啓用 dev_mode：

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 _reldirectory. You can also override it:

你能夠直接在Relx選項中指定發行版的輸出目錄，Erlang.mk 爲此專門提供了 RELX_OUTPUT_DIR 變量，它的默認值是_reldirectory，你也能夠覆蓋它。

RELX_OUTPUT_DIR = /path/to/staging/directory

 

9.3. Generating the release

9.3. 生成發行版

 

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:

如今全部設置都已完成，你只須要生成版本。就像前面講的，Erlang.mk會在檢測到$(RELX_CONFIG)文件時自動生成，這意味着下面的命令也能構建版本。

$ make

 

If you need to generate the release, and only the release, the rel target can be used:

若是你僅僅只須要生成版本，則能夠使用 rel 目標。

$ 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.

Erlang.mk老是在生成版本時生成一個tarball，以供直接上傳到服務器。tarball的路徑爲$(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz。

 

9.4. Running the release

9.4. 運行發行版

 

Erlang.mk provides a convenience function for running the release with one simple command:

Erlang.mk經過一個簡單的命令提供了運行發行版的便捷功能：

$ 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.

若是尚未發行版，那麼這個命令會先構建這個項目並生成發行版。這個命令以控制檯模式啓動版本，這意味着你也能夠準備一個shell腳原本做必要的檢查。

 

9.5. Upgrading a release

9.5. 升級發行版

 

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.

Erlang.mk爲生成發行版的升級提供了一個叫 relup 的標記。這種發行版升級的方式，容許在不重啓的狀況下更新代碼和正在運行的發行版的狀態。

 

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 appup file must be written. Refer to the Erlang/OTP documentation for more details.

對於你須要更新的每個應用程序，都必須寫一個 appup文件。更多詳細信息，請參閱 Erlang/OTP文檔。

 

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.

就本節而言，假設初始版本爲1，新版本爲2。版本的名字叫 example 。

 

Once all this is done, you can build the tarball for the release upgrade:

一旦完成了這一切，你就能夠構建一個用於版本升級的tarball：

$ make relup

 

This will create an archive at the root directory of the release, $RELX_OUTPUT_DIR/example/example-2.tar.gz.

這將在版本的根目錄下建立一個存檔（壓縮文件），$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:

從版本的根目錄中，將該存檔移動到正在運行的節點上的正確位置。

$ mkdir releases/2/
$ mv path/to/example-2.tar.gz releases/2/

 

Finally, upgrade the release:

最後，升級版本：

$ bin/example_release upgrade "2/example_release"

 

Or on Windows:

對於windwos系統：

$ bin/example_release.cmd upgrade "2/example_release"

 

Your release was upgraded!

你的版本已經升級！

 

9.6. Getting Relx semver value

9.6. 獲取Relx語義化版本值

 

There is a workaround to get the semver value which is generated by Relx based on VCS history. 

有一種變通的方法能夠獲取由Relx基於VCS歷史生成的語義化版本值。

 

Create a file rel/version with only one line inside:

建立一個裏面只有一行內容的文件rel/version：

{{ release_version }}

 

Add/Update the overlay section of your relx.config:

添加或者更新 relx.config 文件中的 overlay 部分：

{overlay, [
    {template, "rel/version", "version"}
]}.

 

When you run make rel it creates the file $(RELX_OUTPUT_DIR)/example/version which contains the version value generated by Relx.

當你運行 make rel 時，會建立一個文件 $(RELX_OUTPUT_DIR)/example/version，其中包含Relx生成的版本值。

$ 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:

在你的 Makefile 中，你能夠使用這個簡單的代碼段來獲取版本號，但請記住，這取決於 rel 目標：

$(shell cat $(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)

 

For example:

例如：

include erlang.mk

APP_VERSION = $(shell cat $(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)
myrecipe: all
        echo APP_VERSION = $(APP_VERSION)

 

Would output:

會輸出：

$ 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