ElixirのライブラリをHexに公開する

人気のあるプログラミング言語には必ず良いライブラリがあります。
著名なLisp HackerでありY Combinatorの設立者であるポールグレアム氏は、エッセイ「人気の言語を作るには」で以下のように書いています。

型システムの設計みたいなことを考えるのが好きな 言語設計者は身震いするかもしれない。ライブラリの設計だなんて、アプリケーションを書くみたいなことじゃないか! 残念でした。言語はプログラマのためのもので、プログラマが必要としているのはライブラリなのだ。

過激な意見ですが確かに一理ありますね。そして良いライブラリのある言語にはそれを支える優秀なパッケージマネージャが必ずあります。RubyのRubyGems, PealのCPAN, NodeJSのnpmなどです。
Elixir/ErlangにもHexというパッケージマネージャーがあります。

Hex

今回は自作のライブラリをHexにリリースしてみます。

Hexのインストール

Hexをローカル環境にインストールします。
(Elixirのインストール方法はこのページを参考にしてください)

$ mix local.hex

ユーザー登録

以下コマンドでユーザー情報(ユーザー名、メールアドレス、パスワード)を登録します。

$ mix hex.user register

作成されたAPI keyは~/.hex/hex.configに保存されます

プロジェクト作成

登録するライブラリのプロジェクトを作成します。

mix new プロジェクト名

コードを書く

ここは好きなコードを皆さん書いてください。

メタデータの追加

ライブラリを公開する前に、説明とメタ情報を追加しましょう。mix.exsに追加します

defmodule Ehee.Mixfile do
  use Mix.Project  

  # ライブラリの説明を追加
  @description """
    Unofficial Elixir client for the Github API
  """
  
  def project do
    [app: :application_name, # ここは作成したプロジェクト名が設定されます
     version: "0.0.1",
     elixir: "~> 1.3",
     name: "Library Name", # この行にライブラリ名（プロジェクト名）を追加
     description: @description, # この行を追加
     package: package, # この行を追加
     build_embedded: Mix.env == :prod,
     start_permanent: Mix.env == :prod,
     deps: deps()]
  end

  # ライブラリのメタ情報を追加する
  defp package do
    [ maintainers: ["youraccountname"], # 先ほど登録したアカウント名
      licenses: ["MIT"], # 選択したライセンス
      links: %{ "Github" => "https://github.com/username/projectname" } # GitHubのリポジトリURL ]
  end

ライブラリを公開する

以下のコマンドでリリースしましょう

$ mix hex.publish

リリースはできたようですが、以下のメッセージが出力されドキュメントのリリースを促されます。

Don't forget to upload your documentation with `mix hex.docs`

ドキュメント

ライブラリのダウンロード

ex_docというドキュメント作成のためのライブラリと、earmarkというmarkdownからHTMLへ変換するライブラリをプロジェクトの依存ライブラリに追加しましょう。

  defp deps do
    [
      {:ex_doc, "~> 0.11"}, # この行を追加
      {:earmark, ">= 0.0.0"}, # この行を追加
    ]
  end

ダウンロードします。

$ mix deps.get

ドキュメントの追加

作成したライブラリのモジュールにドキュメントを追加しましょう。
モジュールの先頭には@moduledocでモジュールの説明を、メソッドには@doc でメソッドの説明を書きます。
以下のように追加します(既存のライブラリのソースで説明します)。

defmodule Ehee.Gists do
  import Ehee
  alias Ehee.Credential

  @moduledoc """  # ここにモジュールのドキュメントを追加する
  The Gist Webhooks API
  """

  @doc """  # ここにメソッドのドキュメントを追加する
  List authenticated users gists

  ## Example
      Ehee.Gists.list(credential)

  More info at: https://developer.github.com/v3/gists/#list-a-users-gists
  """
  @spec list(Credential.t) :: Ehee.response
  def list(credential) do
    get("/gists", credential)
  end
end

ドキュメントの公開

準備ができました。以下のコマンドでドキュメントをHexに公開します。

mix hex.docs

公開したドキュメントはHexのライブラリのオンラインドキュメントとして以下のように表示されます。

まとめ

作ったライブラリを他のプログラマに簡単に公開できる仕組みが用意されていることは、言語が発展する上で非常に重要な要素です。
ElixirはRailsコミッタが作成した言語ということもあり、若い言語でありながらこの辺りの仕組みが良くできていると思いました。

参考情報

ハッカーと画家 コンピュータ時代の創造者たち