Elixir: 開發和發佈Elixir庫

建立 Elixir 項目

$ mix new simple_statistics
$ cd simple_statistics
$ mix test

Mix 生成了以下目錄結構

|-- _build
|-- config/
  |-- config.exs
|-- lib/
  |-- simple_statistics.ex
|-- test/
  |-- simple_statistics_test.exs
  |-- test_helper.exs
|-- mix.exs
|-- mix.lock
|-- README.md
|-- .gitignore

開發代碼

在 lib 下建立 simple_statistics 子目錄, 和包名稱同樣, 用於存放其餘模塊.

|-- lib/
  |-- simple_statistics/
    |-- mean.ex
  |-- simple_statistics.ex

# lib/simple_statistics/mean.ex
defmodule SimpleStatistics.Mean do
  def mean([]), do: nil
  def mean(list) do
    Enum.sum(list) / Kernel.length(list)
  end
end

編寫文檔

使用 @moduledoc 和 @doc 編寫函數和模塊的文檔. 應該在模塊中編寫每個主要函數的文檔.

# lib/simple_statistics/mean.ex
defmodule SimpleStatistics.Mean do
  @moduledoc false

  @doc ~S"""
  The mean is the sum of all values over the number of values.
  """
  def mean([]), do: nil
  def mean(list) do
    Enum.sum(list) / Kernel.length(list)
  end
end

添加文檔測試

# lib/simple_statistics/mean.ex
defmodule SimpleStatistics.Mean do
  @moduledoc false

  @doc ~S"""
  The mean is the sum of all values over the number of values.

  ## Examples

      iex> SimpleStatistics.Mean.mean([])
      nil
      iex> SimpleStatistics.Mean.mean([1,2,3,4,5])
      3.0
      iex> SimpleStatistics.Mean.mean([1.5,-2.1,3,4.5,5])
      2.38

  """
  def mean([]), do: nil
  def mean(list) do
    Enum.sum(list) / Kernel.length(list)
  end
end

把 doctest 添加到測試集

# test/simple_statistics_test.ex
defmodule SimpleStatisticsTest do
  use ExUnit.Case
  doctest SimpleStatistics.Mean
end

運行測試 mix test

$ mix test
.

Finished in 0.07 seconds (0.07s on load, 0.00s on tests)
1 test, 0 failures

添加類型註解

類型註解可使用 dialyzer 進行靜態分析.

@spec mean(nonempty_list(number)) :: float()
def mean(list) do
  Enum.sum(list) / Kernel.length(list)
end

更新 mix.exs 文件, 添加依賴:

defp deps do
  [{:ex_doc, "~> 0.11", only: :dev},
   {:earmark, "~> 0.1", only: :dev},
   {:dialyxir, "~> 0.3", only: [:dev]}]
end

運行 dialyzer 靜態分析工具:

$ mix dialyzer
Starting Dialyzer
dialyzer --no_check_plt --plt /Users/yosriady/.dialyxir_core_18_1.2.0.plt -Wunmatched_returns -Werror_handling -Wrace_conditions -Wunderspecs /Users/yosriady/simple_statistics/_build/dev/lib/simple_statistics/ebin
  Proceeding with analysis... done in 0m1.68s
done (passed successfully)

生成文檔

添加以下依賴到 mix.exs 文件

defp deps do
  [{:ex_doc, "~> 0.11", only: :dev},
   {:earmark, "~> 0.1", only: :dev}]
end

運行 mix deps.get 和 mix deps.compile 獲取和安裝這些依賴, 最後用 mix docs 生成文檔:

$ mix docs
$ cd docs
$ open index.html

發佈庫

如今這邊把開發好的庫發佈到Hex, 以方便本身和別人使用.

註冊Hex用戶帳號

$ mix hex.user register

更具提示註冊便可. 稍後會受到激活連接, 點擊激活, 就能夠登錄了.

設置項目元數據

# mix.exs
def project do
  [app: :decision_tree,
   version: "0.0.1",
   elixir: "~> 1.2",
   build_embedded: Mix.env == :prod,
   start_permanent: Mix.env == :prod,
   description: description,
   package: package,
   deps: deps]
end

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

defp package do
  [
   files: ["lib", "mix.exs", "README.md"],
   maintainers: ["Yos Riady"],
   licenses: ["Apache 2.0"],
   links: %{"GitHub" => "https://github.com/Leventhan/simple_statistics",
            "Docs" => "http://hexdocs.pm/simple_statistics/"}
   ]
end

元數據和依賴添加到 mix.exs 文件後, 咱們就準備好發佈這個包了, 使用 mix hex.publish 發佈:

$ mix hex.publish
Publishing simple_statistics 0.0.1
  Dependencies:
  Files:
    lib/simple_statistics.ex
    lib/simple_statistics/mean.ex
    mix.exs
    README.md
  App: simple_statistics
  Name: simple_statistics
  Description: Statistics toolkit for Elixir.
  Version: 0.0.1
  Build tools: mix
  Licenses: Apache 2.0
  Maintainers: Yos Riady
  Links:
    Docs: http://hexdocs.pm/simple_statistics/
    GitHub: https://github.com/Leventhan/simple_statistics
  Elixir: ~> 1.2
  WARNING! Excluded dependencies (not part of the Hex package):
    ex_doc
    earmark
    dialyxir
Before publishing, please read Hex Code of Conduct: https://hex.pm/docs/codeofconduct
[#########################] 100%
Published at https://hex.pm/packages/simple_statistics/0.0.1
Don't forget to upload your documentation with `mix hex.docs`

如今咱們的庫就已經發布爲 mix.exs 中指定的版本了.

在一個小時內, 一個發佈版本能夠經過 --revert 參數進行修改或退回(取消這個版本的發佈).
若是你想回退(revert)超過一小時的發佈, 須要聯繫管理員

發佈文檔

能夠把文檔發佈到 Hex Docs, 文檔能夠用任務 mix docs 生成.

$ mix hex.docs
Docs successfully generated.
View them at "doc/index.html".
[#########################] 100%
Published docs for simple_statistics 0.0.1
Hosted at https://hexdocs.pm/simple_statistics/0.0.1

文檔能夠經過 https://hexdocs.pm/simple_statistics/0.0.1 查看, https://hexdocs.pm/simple_statistics 老是重定向到最新的發佈版本.

版本化

能夠經過修改 mix.exs 文件的 version 值, 並運行 mix hex.publish 發佈一個新的版本.

注意, 使用 Git tags 標註版本變動!

$ git tag -a v0.0.1 -m "Version 0.0.1"
$ git push origin v0.0.1

結語

如今已經成功開發和發佈了一個版本! 開發和發佈Elixir庫是簡單和直接的. 如今其餘開發者就能夠把你的庫添加到他們本身項目的依賴了.