Gleam を書きはじめる

原文: Getting started writing Gleam ── © Louis Pilfold and the Gleam contributors, Apache-2.0。日本語訳 © 2026 Canonical。

このガイドでは、Gleam プロジェクトを作成して開発を進める方法を説明します。

ここでは Gleam 言語自体の解説は行いません。まだの方は、先に言語ツアーに目を通してください。また、Gleam と Erlang がすでにインストールされていることを前提としています。Gleam がインストールされていない場合は、インストールガイドを参照してください。

準備はよろしいですか？それでは始めましょう！

プロジェクト

このガイドでは、環境変数を表示する小さなコマンドラインプログラムを作成します。

実行すると次のようになります。

gleam run get USER
# USER=lucy

プロジェクトを作る

Gleam のビルドツールは、先ほどインストールした gleam プログラムに組み込まれています。新しいプロジェクトの作成、ビルド、テスト、実行に対応しているほか、Hex パッケージマネージャからの依存の管理も行えます。

まず、ターミナルで gleam new コマンドを実行して、新しい Gleam プロジェクトを作成します。ここでは vars という名前にします。

# プロジェクトを作る
gleam new vars

# プロジェクトのディレクトリへ移動する
cd vars

これにより、次のような構成のプロジェクトが作成されます。

.
├── .github/workflows/test.yml
├── .gitignore
├── README.md
├── gleam.toml
├── src/vars.gleam
└── test/vars_test.gleam

README.md ファイルは、プロジェクトの導入となるドキュメントを markdown 形式で記述する場所です。
gleam.toml ファイルには、プロジェクトの設定が含まれています。
src/ には、プログラムのソースコードを配置します。
test/ には、プロジェクトをテストするための追加コードを配置します。
.gitignore には、バージョン管理システム git の設定が含まれています。
.github/workflows/test.yml は、GitHub のリポジトリに push した際にプロジェクトのテストを実行する、GitHub Actions のワークフローを定義しています。

ライブラリであっても直接実行できるプログラムであっても、これら一式を Gleam パッケージと呼びます。

プロジェクトを実行する

プログラムの入口(エントリポイント)は、パッケージ自身と同じ名前のモジュールにある main 関数です。gleam new コマンドによって、次のようなコードが生成されているはずです。

// src/vars.gleam にて
import gleam/io

pub fn main() {
  io.println("Hello from vars!")
}

ターミナルで次のコマンドを実行し、プロジェクトを動かしてみましょう。

gleam run

これを実行すると、Gleam のビルドツールが依存(ここでは標準ライブラリとテストランナー)をダウンロードし、すべてのコードをコンパイルしたうえで main 関数を実行し、ターミナルに「Hello from vars!」と出力します。

パッケージ内の別のモジュールや、依存先のモジュールを実行したい場合は、gleam run -m modulename を実行します。

gleam run --target javascript を実行すると、Erlang ではなく JavaScript のランタイム上でプロジェクトを実行できますが、このガイドの以降の作業では引き続き Erlang を使用します。

依存を追加する

Gleam は組み込みシステムやブラウザといった制約のある環境でも動作するため、コマンドライン引数の受け取りや環境変数の読み取りなど、一部の機能は標準ライブラリに含まれていません。今回のプログラムでこれらを処理するには、必要な機能を提供する依存をいくつか追加する必要があります。

パッケージを探す際は Gleam のパッケージサイトを利用できます。ここでは環境変数の読み取りに envoy を、コマンドライン入力の読み取りに argv を使用します。次のコマンドを実行して、これらをパッケージに追加します。

gleam add envoy argv

gleam.toml ファイルを開くと、[dependencies] セクションに依存が追加されていることを確認できます。

name = "vars"
version = "1.0.0"

[dependencies]
gleam_stdlib = ">= 1.0.0 and < 2.0.0"
envoy = ">= 1.2.0 and < 2.0.0"
argv = ">= 1.1.0 and < 2.0.0"

[dev_dependencies]
gleeunit = ">= 1.0.0 and < 2.0.0"

>= 1.2.0 and < 2.0.0 というバージョン制約は、1.2.0 以上 2.0.0 未満の任意のバージョンを指定することを意味します。Hex のパッケージはセマンティックバージョニングに従っているため、この指定によって破壊的変更を避けつつ互換性を最大限に保つことができます。

さらに manifest.toml というファイルも生成され、すべての依存パッケージが特定のバージョンに固定されます。プロジェクトをダウンロードして実行する誰もが同じバージョンの依存を利用できるよう、このファイルはバージョン管理システムに含めることが推奨されています。なお、このマニフェストファイルは Hex にはアップロードされないため、他のプロジェクトがあなたのプロジェクトに依存する際には使用されません。

バージョン制約を満たす最新バージョンへ依存を更新したい場合は、gleam update コマンドを実行します。

また、Hex 経由ではなくローカルコンピュータ上のパッケージに依存するために、パス依存(path dependencies)を使用することもできます。

[dependencies]
my_other_package = { path = "../my_other_package" }

git 依存の場合も同様です。

[dependencies]
my_library = { git = "git@github.com:my-project/my-library", ref = "a8b3c5d82" }
gleam_stdlib = { git = "git@github.com:gleam-lang/stdlib", ref = "main" }

詳細については、gleam.toml のリファレンスを参照してください。

依存を使う

同名のパッケージに含まれる argv モジュールは、コマンドライン引数を読み取るための load という関数を公開しています。src/vars.gleam のコードを、この関数を使用するように書き換えます。

import argv
import envoy
import gleam/io
import gleam/result

pub fn main() {
  case argv.load().arguments {
    ["get", name] -> get(name)
    _ -> io.println("Usage: vars get <name>")
  }
}

fn get(name: String) -> Nil {
  let value = envoy.get(name) |> result.unwrap("")
  io.println(format_pair(name, value))
}

fn format_pair(name: String, value: String) -> String {
  name <> "=" <> value
}

ここではパターンマッチを使用して、コマンドライン引数に応じて get 関数を呼び出すか、あるいはヘルプメッセージを表示するかを分岐させています。

get 関数は、同名のパッケージに含まれる envoy モジュールを利用して環境変数を読み取り、その結果を表示するか、存在しない場合はメッセージを表示します。出力の整形には補助関数である format_pair を使用しています。

さっそく試してみましょう。ターミナルで gleam run get TERM を実行すると、再コンパイルが行われ、プログラムが動作します。

コードをテストする

このプログラムは非常に小規模であるため、実際にはテストを書く必要はないかもしれませんが、実演を兼ねて format_pair 関数のテストを作成してみましょう。

test/ ディレクトリのモジュールから format_pair 関数を呼び出すには、この関数を公開(public)にする必要があります。しかし、パッケージの公開 API の一部としては扱いたくないため、関数を内部モジュール(internal module)へ移動します。内部モジュールとは、デフォルトで packagename/internal や packagename/internal/* といった名前が付けられたモジュールを指します。

これらのモジュールに含まれる公開関数は他のモジュールから import できますが、あくまでパッケージの内部実装の一部とみなされるため、ドキュメント化されることはなく、公開 API の関数と同等の安定性も保証されません。

// src/vars.gleam にて
import argv
import envoy
import gleam/io
import gleam/result
import vars/internal

pub fn main() {
  // 簡潔にするため省略
}

fn get(name: String) -> Nil {
  let value = envoy.get(name) |> result.unwrap("")
  io.println(internal.format_pair(name, value))
}

// src/vars/internal.gleam にて
pub fn format_pair(name: String, value: String) -> String {
  name <> "=" <> value
}

test/vars_test.gleam ファイルを開き、format_pair 関数のテストを記述します。

// test/vars_test.gleam にて
import gleeunit
import vars/internal

pub fn main() {
  gleeunit.main()
}

pub fn format_pair_test() {
  let greeting = internal.format_pair("hello", "world")
  assert greeting == "hello=world"
}

gleam test を実行すると vars_test の main 関数が呼び出され、そこからテストが実行されます。

テストの main 関数では任意の処理を実行できますが、デフォルトでは、Gleam プロジェクトは簡素なテストランナーである gleeunit を使用するように生成されます。これを利用すると、test/ ディレクトリ内にある公開関数のうち、名前が _test で終わるものがテストとして実行されます。

プログラムを共有する

作成したプログラムがサーバ上で動作する Web アプリケーションであれば、Gleam ドキュメントのデプロイに関するセクションを参照するとよいでしょう。今回作成したのはコマンドラインプログラムであるため、代わりに、他の人と簡単に共有できるよう 1 つのファイルにまとめることにします。

ここでは Erlang ターゲットを使用しているため、Erlang ランタイムの一部である escript を利用してこれを行うことができます。Gleam はパッケージを escript ファイルとしてコンパイルでき、その結果は ./vars に書き出されます。

# プログラムを escript へコンパイルする
gleam export escript

# プログラムを実行する
./vars get USER
# または Windows では
escript ./vars get USER

この vars ファイルは、互換性のあるバージョンの Erlang がインストールされているコンピュータであればどこでも実行できます。通常は、escript をコンパイルしたコンピュータ上の Erlang バージョンから、メジャーバージョンで数世代以内の範囲であれば動作します。

以上で完了です。さあ、開発を楽しみましょう！また、Gleam の Discord サーバにもぜひ立ち寄って、質問をしたり、自分が取り組んでいるプロジェクトを共有したりしてみてください。