gleam.toml リファレンス
原文: gleam.toml reference ── © Louis Pilfold and the Gleam contributors, Apache-2.0。日本語訳 © 2026 Canonical。
すべての Gleam パッケージには gleam.toml 設定ファイルが必要です。これは toml 1.1 形式で書かれており、仕様のドキュメントは toml.io にあります。
新しい Gleam パッケージにおける既定の設定は、次のようになります。
name = "my_package"
version = "1.0.0"
[dependencies]
gleam_stdlib = ">= 0.44.0 and < 2.0.0"
[dev_dependencies]
gleeunit = ">= 1.0.0 and < 2.0.0"プロジェクトのメタデータ
name
name = "my_project"プロジェクトの名前を指定します。このキーは必須です。
version
version = "1.0.0"プロジェクトのバージョンを指定します。このキーは必須です。
licences
licences = ["Apache-2.0"]プロジェクトで採用するライセンスを SPDX 形式で指定します。このキーは省略可能ですが、パッケージを Hex パッケージマネージャに公開したい場合は必須です。
description
description = "A parser for the PureData file format"プロジェクトの短い説明文です。このキーは省略可能ですが、パッケージを Hex パッケージマネージャに公開したい場合は必須です。
依存の管理
dependencies
[dependencies]
gleam_stdlib = ">= 1.0.0 and < 2.0.0"
gleam_time = ">= 1.0.0 and < 2.0.0"このパッケージを動作させるために、Gleam のビルドツールがダウンロードしてコンパイルする必要のある依存パッケージを指定します。
バージョンの指定には Hex の要求形式の文字列を使います。また、名前は依存先パッケージの設定ファイルに書かれている名前と一致させる必要があります。
Erlang の rebar3 パッケージや Elixir の mix パッケージも、構文を変えることなく依存パッケージとして追加できます。
パス依存
my_other_project = { path = "../my_other_project" }ローカルファイルシステム上にある Gleam パッケージは、path フィールドを使って依存パッケージとして追加できます。
Git 依存
my_library = {
git = "https://github.com/my-project/my-library",
ref = "a8b3c5d82"
}git 経由で取得する Gleam パッケージは、git および ref フィールドを使って依存パッケージとして追加できます。ブランチやタグよりも、コミットの sha を指定することをおすすめします。これにより、意図したバージョンのコードを確実に取得でき、悪意のある攻撃を防ぐことができます。
省略可能な path フィールドを使うと、リポジトリ内のサブディレクトリを指定できます。これは複数の Gleam パッケージを含むモノレポで役立ちます。
my_library = {
git = "https://github.com/my-project/monorepo",
ref = "a8b3c5d82",
path = "packages/my_library"
}dev_dependencies
[dev_dependencies]
gleeunit = ">= 1.0.0 and < 2.0.0"開発中にのみ必要な依存パッケージを指定します。dependencies フィールドと同じ構文を使います。
ここで指定した依存パッケージは、パッケージを Hex に公開する際には含まれません。また、同一のパッケージを dependencies と dev_dependencies の両方に指定することはできません。
ドキュメント
repository
[repository]
type = "github"
user = "torvalds"
repo = "linux"プロジェクトのソースコードリポジトリを指定します。この情報は生成されるドキュメントで使われ、Hex 上にも表示されます。
このキーは省略可能ですが、パッケージを Hex パッケージマネージャに公開したい場合は必須です。
リポジトリの種別に bitbucket、codeberg、github、gitlab、sourcehut、tangled のいずれかを指定する場合は、user および repo フィールドも必要です。
[repository]
type = "tangled"
user = "my-username"
repo = "my-repo"リポジトリの種別に forgejo あるいは gitea を指定する場合は、host、user、repo の各フィールドが必要です。
[repository]
type = "gitea"
host = "https://example.com"
user = "my-username"
repo = "my-repo"他のコードホスティングサービスを使っている場合は、custom 種別を使えます。この場合は url フィールドが必要です。これを指定すると、生成される HTML ドキュメントにはリポジトリへのリンクが含まれますが、ソースコードにおける公開された型や値の定義へのリンクは含まれなくなります。
[repository]
type = "custom"
url = "https://example.com/my-project"custom 以外のすべての種別は、path および tag_prefix フィールドに対応しています。これらは、複数の Gleam パッケージを 1 つのリポジトリで管理している場合(モノレポなど)に使います。
path にはリポジトリのルートからパッケージを含むディレクトリまでのパスを指定し、tag_prefix にはパッケージのリリース用の git タグに付ける接頭辞を指定します。これは、複数のパッケージ間でタグ名が衝突するのを防ぐためです。
[repository]
type = "github"
user = "my-user"
repo = "package_one"
path = "packages/one"
tag_prefix = "one-"links
links = [
{ title = "Home page", href = "https://example.com" },
{ title = "Other site", href = "https://another.example.com" },
]関連するウェブサイトへのリンクを指定します。これらは生成されるドキュメントや Hex 上に表示されます。
documentation.pages
[[documentation.pages]]
title = "My Page"
path = "my-page.html"
source = "./path/to/my-page.md"生成される HTML ドキュメントに含めたい追加の Markdown ページを指定します。documentation テーブルは省略可能であり、その中の pages キーも省略可能です。
コンパイル
gleam
gleam = ">= 1.15.0"パッケージが必要とする Gleam コンパイラのバージョンを指定します。
パッケージのコンパイルに使われるコンパイラのバージョンがこの条件を満たさない場合はエラーとなり、プロジェクトが正しくコンパイルできないことをプログラマに通知します。
target
target = "erlang"Gleam のコードをコンパイルまたは実行する際に使われる、既定のコンパイルターゲットです。指定できる値は "erlang" または "javascript" です。指定しない場合は、既定値として "erlang" が使われます。
この値は、--target フラグを受け付ける CLI コマンドを実行する際に、同フラグで上書きできます。
internal_modules
internal_modules = ["my_app/internal", "my_app/internal/*"]内部モジュール(internal module)とは、パッケージの公開 API に含まれないモジュールのことです。技術的にはこれらを import して使うことも可能ですが、非公開扱いとなるため、安定性や動作の保証はありません。公開モジュールから呼び出される補助モジュールとして利用するとよいでしょう。
このフィールドには glob パターンのリストを指定します。いずれかのパターンに一致したモジュールは、内部モジュールとして扱われます。
指定しない場合、このフィールドの既定値は ["$PACKAGE_NAME/internal", "$PACKAGE_NAME/internal/*"] になります。たとえば wibble という名前のパッケージでは、wibble/internal や wibble/internal/wobble といったモジュールが内部モジュールになります。
Erlang のコンパイル
erlang.application_start_module
[erlang]
application_start_module = "my_application"プロジェクトの OTP アプリケーションモジュールの名前を指定します(存在する場合)。このキーは省略可能です。アプリケーションを開発する際には必要になることがありますが、ライブラリにおいて指定することはまずありません。指定する場合、対象のモジュールは OTP application ビヘイビアを実装している必要があります。
モジュール名は Erlang のアトム形式で指定するため、Gleam における my_project/application モジュールは my_project@application と書きます。
erlang.extra_applications
[erlang]
extra_applications = ["inets", "ssl"]プロジェクトの依存先が提供するアプリケーションに加えて、起動する必要のある OTP アプリケーションの名前を指定します。
JavaScript のコンパイル
javascript.source_maps
[javascript]
source_maps = trueコンパイルされた Gleam モジュールのソースマップファイルを生成するかどうかを指定します。このキーは省略可能で、既定値は false です。
javascript.typescript_declarations
[javascript]
typescript_declarations = trueコンパイルされた Gleam モジュールの TypeScript .d.ts ファイルを生成するかどうかを指定します。このキーは省略可能で、既定値は false です。
javascript.runtime
[javascript]
runtime = "node"gleam run や gleam test、および関連するコマンドで利用する JavaScript ランタイムを指定します。指定できる値は "node"、"deno"、"bun" のいずれかで、既定値は "node" です。
javascript.deno.allow_*
Deno ランタイムは IO 処理に権限システムを採用しているため、プログラムがこれらの動作を行うには明示的に許可を与える必要があります。このフィールドではその各権限を設定します。任意の組み合わせで指定でき、すべて省略することも可能です。
設定例は次のようになります。
[javascript.deno]
allow_hrtime = true
allow_net = ["example.com:443"]
allow_run = ["./bin/migrate.sh"]
allow_read = ["./database.sqlite"]
allow_write = ["./database.sqlite"]allow_all: Deno のすべての権限を与えるかどうかを指定します。これは、他のすべての権限フィールドをtrueに設定するのと同じ働きをします。allow_env: 環境変数へのアクセスを許可します。真偽値、またはアクセスを許可する環境変数名のリストを指定できます。allow_ffi: 外部関数インターフェース(FFI)へのアクセスを許可するかどうかを指定します。allow_hrtime: 高分解能時間 API の利用を許可するかどうかを指定します。allow_net: ネットワークアクセスを許可します。真偽値、またはアクセスを許可する IP アドレスやホスト名(必要に応じてポート番号を含む)のリストを指定できます。allow_read: ファイルシステムからの読み取りアクセスを許可します。真偽値、または読み取りを許可するパスのリストを指定できます。allow_run: 子プロセスの実行を許可します。真偽値、または実行を許可するパスのリストを指定できます。allow_sys: システム情報へのアクセスを許可するかどうかを指定します。allow_write: ファイルシステムへの書き込みアクセスを許可します。真偽値、または書き込みを許可するパスのリストを指定できます。
外部ツール
tools
[tools.my_tool]
enable = true
threads = 8ここには、外部ツール向けのデータや設定を記述できます。外部ツールの作者には、tools.<tool_name> の下に設定を置くことを推奨します。