In order to publish on Hex you need an account and an API key with publishing rights. Erlang.mk does not provide other authentication methods.

The API key can be provided one of two ways.

Erlang.mk will prompt for the key automatically by default:

$ make hex-release-publish
Secret:

The HEX_SECRET environment variable can also be defined to contain the API key. In that case Erlang.mk will not prompt for the key.

$ export HEX_SECRET=your-api-key

Note: DO NOT provide the API key as a Make variable as that variable will be visible in tools like ps:

# DO:
$ HEX_SECRET=your-api-key make hex-release-publish

# DO NOT:
$ make hex-release-publish HEX_SECRET=your-api-key

PROJECT is the package name. PROJECT_VERSION is the version. PROJECT_DESCRIPTION is the description sent to Hex.

Hex requires a license in the package metadata. Set it with HEX_TARBALL_EXTRA_METADATA. The value is Erlang map syntax appended to the metadata:

define HEX_TARBALL_EXTRA_METADATA
#{licenses => [<<"ISC">>]}
endef

The same variable can add the other metadata Hex accepts, such as links:

define HEX_TARBALL_EXTRA_METADATA
#{licenses => [<<"ISC">>],
  links => #{<<"GitHub">> => <<"https://github.com/ninenines/cowboy">>}}
endef

Dependencies listed in DEPS are written as package requirements. The requirement defaults to the version that was fetched. hex_req_NAME publishes a different requirement for that dependency:

DEPS = cowlib
dep_cowlib_commit = 2.13.0
hex_req_cowlib = ~> 2.13

By default the package will contain the Hex metadata as well as the following files (if they exist):

Additional files can be included in the package, by appending to HEX_TARBALL_FILES after include erlang.mk.

make hex-release-publish publishes PROJECT_VERSION. The version must be new on Hex.

$ make hex-release-publish

make hex-release-replace publishes over the version that is already on Hex.

$ make hex-release-replace

make hex-release-delete removes PROJECT_VERSION.

$ make hex-release-delete

make hex-release-retire retires a version. HEX_VERSION selects the version and defaults to PROJECT_VERSION. HEX_REASON defaults to invalid. Hex also accepts other, security, deprecated and renamed. HEX_MESSAGE is the text sent with the retirement.

$ make hex-release-retire HEX_REASON=security \
    HEX_MESSAGE="See the advisory"

make hex-release-unretire restores a retired version. HEX_VERSION again defaults to PROJECT_VERSION.

$ make hex-release-unretire HEX_VERSION=0.1.0

The tarball is created automatically when publishing, but it can also be created manually.

make hex-tarball-create writes the package tarball to $(ERLANG_MK_TMP)/$(PROJECT).tar.

$ make hex-tarball-create

HEX_TARBALL_OUTPUT_FILE changes that path.

make hex-docs-publish builds the project documentation, packs the files under doc/, and uploads that archive for PROJECT_VERSION.

$ make hex-docs-publish

HEX_DOCS_DOC_DIR changes the directory that is packed. It defaults to doc/.

HEX_DOCS_DOC_DIR = documentation/

make hex-docs-tarball-create writes the docs tarball to $(ERLANG_MK_TMP)/$(PROJECT)-docs.tar.gz.

$ make hex-docs-tarball-create

make hex-docs-delete removes the documentation for HEX_VERSION, or for PROJECT_VERSION when HEX_VERSION is not set.

$ make hex-docs-delete HEX_VERSION=0.1.0

The targets publish to Hex.pm unless HEX_CONFIG says otherwise. The value is Erlang map syntax appended to hex_core:default_config():

define HEX_CONFIG
#{api_url => <<"https://hex.example/api">>}
endef