• Mix
• 用法
• 發佈套件
• 私人套件
• 任務
• Rebar
• 用法
• 發佈套件
• 私人套件
• 任務
• Hex
• 常見問題
• 自我託管
• 鏡像
• 公開金鑰

發佈套件

將套件發佈到 Hex 包括註冊 Hex 使用者、將元資料新增至專案的 mix.exs 檔案，最後利用 mix 任務提交套件。

註冊 Hex 使用者

註冊使用者時，系統會提示您輸入使用者名稱、電子郵件和密碼。電子郵件用於註冊期間確認您的身分，以及在您的一個套件發生問題時與您聯絡。電子郵件絕不會與第三方共用。

$ mix hex.user register
Username: johndoe
Email: john.doe@example.com
Password:
Password (confirm):
Registering...
Generating API key...
You are required to confirm your email to access your account, a confirmation email has been sent to john.doe@example.com

完成此步驟後，請查看您的電子郵件信箱中的確認電子郵件。在您追蹤連結後，您的帳戶即可使用。

套件命名

在發布之前，您必須選擇套件名稱。請記住，發布到 Hex 的套件是公開的，且社群中的任何人都可以存取。社群也負責選擇並鼓勵使用良好的套件名稱。以下提供一些提示

• 避免使用冒犯性或騷擾性的套件名稱、暱稱或其他識別字號，以維持友善、安全，並歡迎所有人的環境。
• 如果你在現有套件之上提供功能，請考慮使用該套件名稱作為前綴。例如，如果你要將驗證功能新增到 Plug，請考慮稱呼你的套件為 plug_auth（或 plug_somename），而非 auth（或 somename）。
• 避免與現有套件產生命名空間衝突。Plug 擁有 Plug 命名空間，如果你有 Plug 的驗證套件，請使用 PlugAuth，而非 Plug.Auth。
  • 此準則適用於你所有模組，因此，如果你的套件是 plug_auth，則你所有模組（除了 mix 任務等特殊模組之外）都應以 PlugAuth. 開頭（例如 PlugAuth.Utils、PlugAuth.User）。此舉很重要，因為在一個 BEAM 系統中，只能有一個具有指定名稱的模組在執行，如果多個套件定義了相同模組，則你無法同時使用這兩個套件，因為只會使用模組的一個版本。

擁有名稱後，就可以將適當的元資料新增到你的 mix.exs 檔案中。

將元資料新增到 mix.exs

套件是在專案的 mix.exs 檔案中，使用 project 函數進行設定。請參閱下方的範例檔案。

首先，請確認 :version 屬性正確無誤。所有 Hex 套件都必須遵循 語意化版本控制。當你的套件版本處於主版本 “0” 時，任何重大變更都應透過增加次要版本來表示。例如，0.1.0 -> 0.2.0。

填寫 :description 屬性。它可以是一或數個句子，用來描述套件。

在 :package 屬性下方有一些額外的設定選項

:name

套件名稱，如果要使用與應用程式名稱不同的名稱來發布套件時。預設值設定為與你的 OTP 應用程式的名稱相同（與 `project.app` 的值相同），以 snake_case（小寫，字詞之間以底線分隔）書寫。

:organization

套件所屬的組織。套件會發布到該組織的儲存庫中，預設為全域的 "hexpm" 儲存庫。

:licenses

專案授權的名單。此屬性是必需的。建議使用 SPDX 授權識別碼。

:links

其中按鍵為連結名稱，數值為連結 URL 的對應。此屬性是選擇性的，但強烈建議使用。

:files

包含在套件內之檔案及目錄清單。預設值為標準專案目錄，因此通常不需要設定此屬性。

:build_tools

可以建置套件的建置工具清單。您需要設定此項的機會相當罕見，因為 Hex 會嘗試根據套件中的檔案自動偵測建置工具。如果存在 rebar 或 rebar.config 檔案，Hex 將標示為可以使用 rebar 建置。可以透過設定此欄位來覆寫此偵測。

為了改善 ExDoc 生成的文件，以下欄位也可以作為 project 函式的部份提供

:source_url

您公開的原始碼所在的 URL。在文件中的不同模組函式將使用這個 URL 來連結到程式碼。

:homepage_url

應用程式首頁的 URL。這個 URL 會用於從產生的文件連結回首頁。

參閱 ExDoc 文件 以取得改善產製文件的更多資訊。

相依性

未定義版本控制（:git 或 :path）的相依性將自動視為 Hex 的相依性。如需更多詳細資料，請參閱 使用指南。

只有 Hex 套件可以使用做為套件的相依性。無法上傳具有 Git 相依性的套件。另外，只會包括製作相依性，就像 Mix 只會在提取相依性的相依性時提取製作相依性一樣。當相依性未定義 :only 屬性，或定義為 only: :prod 時，相依性將視為製作相依性。

文件說明

文件說明會在您發布套件時自動發布到 hexdocs.pm。如果您只想發布套件本身，則您可以執行 mix hex.publish package，與之類似，如果您想要（重新）發布現有套件版本的說明文件，則您可以執行 mix hex.publish docs。

在發布說明文件之前，Hex 會執行 mix docs 任務，以建立說明文件並確保其是最新的。Elixir 的主要說明文件工具 ex_doc 提供了此任務，因此如果您將其新增為相依項，則您在發布套件時無需做任何事即可自動建立說明文件。查看 ex_doc 的說明文件，以了解如何設定說明文件，我們建議在將說明文件發布到 Hex 之前，使用 mix docs 在本地建立說明文件。最後，請務必查看 Elixir 的說明文件撰寫指南 以取得建議和最佳實務。

如果您想使用其他說明文件工具或處理來自 ex_doc 建立的後處理，則可以別名化 docs 任務，請查看 任務別名 docs 以取得更多資訊。建立的說明文件應放在 doc/ 目錄中，至少包含一個 index.html 檔案。

mix.exs 檔案範例

defmodule Postgrex.MixProject do
  use Mix.Project

  def project() do
    [
      app: :postgrex,
      version: "0.1.0",
      elixir: "~> 1.0",
      build_embedded: Mix.env == :prod,
      start_permanent: Mix.env == :prod,
      description: description(),
      package: package(),
      deps: deps(),
      name: "Postgrex",
      source_url: "https://github.com/elixir-ecto/postgrex"
    ]
  end

  def application() do
    []
  end

  defp deps() do
    [
      {:decimal, "~> 1.0"},
      {:ex_doc, "~> 0.14", only: :dev, runtime: false}
    ]
  end

  defp description() do
    "A few sentences (a paragraph) describing the project."
  end

  defp package() do
    [
      # This option is only needed when you don't want to use the OTP application name
      name: "postgrex",
      # These are the default files included in the package
      files: ~w(lib priv .formatter.exs mix.exs README* readme* LICENSE*
                license* CHANGELOG* changelog* src),
      licenses: ["Apache-2.0"],
      links: %{"GitHub" => "https://github.com/elixir-ecto/postgrex"}
    ]
  end
end

提交套件

套件的概資料與依賴關係加入到 mix.exs 後，就可以使用 mix hex.publish 指令發布套件

$ mix hex.publish
Publishing postgrex v0.4.0
  Dependencies:
    decimal ~> 0.1.0
  Excluded dependencies (not part of the Hex package):
    ex_doc
  Included files:
    lib/postgrex
    lib/postgrex/binary_utils.ex
    lib/postgrex/connection.ex
    lib/postgrex/protocol.ex
    lib/postgrex/records.ex
    lib/postgrex/types.ex
    mix.exs
Proceed? [Yn] Y
Published postgrex v0.4.0

恭喜你，你的套件已發布！它會顯示在 hex.pm 網站中，而且可以新增為其他 Mix 專案中的依賴關係。

在發布後，請透過新增它為 Mix 專案中的依賴關係並擷取與編譯它來測試你的套件。如果有任何問題，你可以在第一次發布後的一個小時內，再次發布套件。也可以使用 mix hex.publish --revert VERSION 來回復發布。

在執行發布套件的指令時，Hex 會針對在 :files 屬性中所列的所有檔案與目錄建立一個 tar 檔。將 tarball 發佈到 Hex 伺服器後，會上傳到內容傳遞網路 (CDN) 中，以提供使用者快速且穩定的存取。Hex 也會重新編譯所有用戶端在擷取依賴關係時會自動更新的登錄檔。

從 CI 發布

你可以自動化透過 CI 等工具來發布套件。你需要一把具有發布套件權限的密鑰

$ mix hex.user key generate --key-name publish-ci --permission api:write
Username:
Account password:
Generating key...
f48ac236bca15c3271e077c15c5320c4

如果你要發布一個屬於你的組織的套件，建議使用組織的密鑰，而不是個人的密鑰

$ mix hex.organization key acme generate --key-name publish-ci --permission api:write
Local password:
f48ac236bca15c3271e077c15c5320c4

在 HEX_API_KEY 系統環境變數中設定密鑰。在不用提示的情況下發布套件，傳遞 --yes 旗標

$ HEX_API_KEY=f48ac236bca15c3271e077c15c5320c4 mix hex.publish --yes

請注意，在自動化發布時應小心使用，因為 Hex 會輸出重要的警告，甚至建議如何改善您的套件，這些建議在自動化的過程中很容易被忽略。另外請注意，Hex 仍未達到 1.0 版，因此各次版本之間可能會發生重大變更，而 CI 通常會安裝最新版本。