releases.asciidoc 3.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120
  1. [[relx]]
  2. == Releases
  3. Erlang.mk relies on _Relx_ for generating releases. This
  4. chapter covers the Erlang.mk-specific bits. Consult the
  5. https://erlware.github.io/relx/[Relx website] for more information.
  6. === Setup
  7. Erlang.mk will create a release if it detects a Relx configuration
  8. file in the '$(RELX_CONFIG)' location. This defaults to
  9. '$(CURDIR)/relx.config'. You can override it by defining
  10. the variable before including Erlang.mk:
  11. [source,make]
  12. RELX_CONFIG = $(CURDIR)/webchat.config
  13. Relx does not need to be installed. Erlang.mk will download
  14. and build it automatically.
  15. The Relx executable will be saved in the '$(RELX)' file. This
  16. location defaults to '$(CURDIR)/relx' and can be overriden.
  17. // @todo You can use a custom location by ???
  18. === Configuration
  19. You can specify additional Relx options using the `RELX_OPTS`
  20. variable. For example, to enable `dev_mode`:
  21. [source,make]
  22. RELX_OPTS = -d true
  23. While you can specify the output directory for the release
  24. in the Relx options directly, Erlang.mk provides a specific
  25. variable for it: `RELX_OUTPUT_DIR`. It defaults to the '_rel'
  26. directory. You can also override it:
  27. [source,make]
  28. RELX_OUTPUT_DIR = /path/to/staging/directory
  29. === Generating the release
  30. Now that you're all set, all you need to do is generate the
  31. release. As mentioned before, Erlang.mk will automatically
  32. generate it when it detects the '$(RELX_CONFIG)' file. This
  33. means the following command will also build the release:
  34. [source,bash]
  35. $ make
  36. If you need to generate the release, and only the release,
  37. the `rel` target can be used:
  38. [source,bash]
  39. $ make rel
  40. Erlang.mk always generates a tarball alongside the release,
  41. which can be directly uploaded to a server. The tarball is
  42. located at `$(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz`.
  43. === Running the release
  44. Erlang.mk provides a convenience function for running the
  45. release with one simple command:
  46. [source,bash]
  47. $ make run
  48. This command will also build the project and generate the
  49. release if they weren't already. It starts the release in
  50. _console mode_, meaning you will also have a shell ready to
  51. use to check things as needed.
  52. === Upgrading a release
  53. Erlang.mk provides a `relup` target for generating release
  54. upgrades. Release upgrades allow updating the code and the
  55. state of a running release without restarting it.
  56. Once your changes are done, you need to update the version
  57. of the application(s) that will be updated. You also need
  58. to update the version of the release.
  59. For each application that needs to be updated, an
  60. http://erlang.org/doc/man/appup.html[appup file]
  61. must be written. Refer to the Erlang/OTP documentation
  62. for more details.
  63. For the purpose of this section, assume the initial release
  64. version was `1`, and the new version is `2`. The name of the
  65. release will be `example`.
  66. Once all this is done, you can build the tarball for the
  67. release upgrade:
  68. [source,bash]
  69. $ make relup
  70. This will create an archive at the root directory of the
  71. release, `$RELX_OUTPUT_DIR/example/example-2.tar.gz`.
  72. Move the archive to the correct location on the running
  73. node. From the release's root directory:
  74. [source,bash]
  75. $ mkdir releases/2/
  76. $ mv path/to/example-2.tar.gz releases/2/
  77. Finally, upgrade the release:
  78. [source,bash]
  79. $ bin/example_release upgrade "2/example_release"
  80. Or on Windows:
  81. [source,bash]
  82. $ bin/example_release.cmd upgrade "2/example_release"
  83. Your release was upgraded!