依存関係の使用

💡 お知らせ: このドキュメントはAIによって翻訳されています。表現に違和感がある場合は、原文（英語）を参照するか、翻訳にご協力ください。

Flix プロジェクトは 3 種類のものに依存できます。GitHub 上で公開されている Flix パッケージ、Maven 上で公開されている Java ライブラリ、そして URL からダウンロードする JAR ファイルです。この 3 つはいずれもマニフェストの中で宣言し、Flix がそれらをダウンロードします。

理想的には、Flix プロジェクトは Flix パッケージのみに依存するべきです。Flix パッケージはソースコードからコンパイルされ、できることを制限する security context(セキュリティコンテキスト) の中でビルドされ、私たちが書いているのと同じ言語で書かれています。Maven ライブラリ、そしてそれ以上に URL からの JAR ファイルは最後の手段です。まず Flix パッケージを探し、それが存在しない場合にのみ Java に頼るべきです。

依存関係を宣言する 2 つの方法

プロジェクトの依存関係とは、そのマニフェストが宣言しているものです。依存関係を変更する方法は 2 つあり、どちらも同じように有効です。flix.toml を自分で編集する方法と、代わりに編集してくれるコマンドを実行する方法です。

各コマンドは、install flix/museum-giftshop flix/museum-entrance のように、一度に複数のパッケージを指定できます。その場合、変更はすべてのパッケージに適用されるか、まったく適用されないかのどちらかです。

どちらの方法でも同じマニフェストが得られるため、好きなように組み合わせて使えます。以下のセクションでは両方の方法を並べて示し、2 つの方法の違い でその違いをまとめます。

Flix パッケージの追加

Flix パッケージへの依存関係は、マニフェストの [dependencies] セクションの項目です：

[dependencies]
"github:flix/museum-giftshop" = { version = "2.0.2", mount = "giftshop" }

キーはそのパッケージが公開されている GitHub リポジトリです。依存関係には 2 つの要素を宣言します。要求するバージョンである version と、そのパッケージにアクセスするための名前である mount(マウント) です。依存関係には、依存関係の信頼 で説明するように security context を宣言することもできます。

この項目は自分で書くこともできますし、install コマンドで Flix に書かせることもできます：

install flix/museum-giftshop

install コマンドは、本来であれば自分で行う選択を代わりに行ってくれます。バージョンを指定しない限り、install flix/museum-giftshop@2.0.2 のように名前を付けない限りは、そのパッケージの最新リリースを宣言します。そのリポジトリ名が有効な mount であればその名前でパッケージをマウントし、そうでなければ mount 名を尋ねてきます：

github:flix/museum-giftshop is reached through a mount, as in 'use MuseumGiftshop::greet'.
Mount [MuseumGiftshop]: giftshop

好きな mount 名を入力するか、Enter を押して角括弧内のものを採用します。--yes オプションを付けると、install は尋ねずに角括弧内のものをそのまま採用します。依存関係の解決が終わると、install は何を宣言したかを報告します：

Added 'flix/museum-giftshop' v2.0.2, mounted at 'giftshop'.

どちらの方法でも、Flix はそのパッケージと、それが依存するすべてのものをダウンロードします。install はすぐにそれを行い、自分で書いた項目については、Flix は次に check のようなコマンドを実行したときにそれを行います：

Found 'flix.toml'. Checking dependencies...
Resolving Flix dependencies...
  Downloading `flix.toml` from `flix/museum-giftshop` (v2.0.2)... OK.
  Downloading `flix.toml` from `flix/museum-clerk` (v2.1.2)... OK.
Downloading Flix dependencies...
  Downloading `package.fpkg` from `flix/museum-clerk` (v2.1.2)... OK.
  Downloading `package.fpkg` from `flix/museum-giftshop` (v2.0.2)... OK.
Resolving Maven dependencies...
  Running Maven dependency resolver.
Downloading external jar dependencies...
Dependency resolution completed.

要求したパッケージは 1 つですが、2 つダウンロードされました。Flix パッケージは自身の依存関係を一緒に連れてくるためであり、flix/museum-giftshop は flix/museum-clerk に依存しています。Flix が各パッケージのどのバージョンを選ぶかについては、バージョンとアップグレード で扱います。

マウントしたパッケージの使用

Flix パッケージは、私たち自身の名前空間の一部にはなりません。パッケージのモジュールはそれ自身の名前空間に存在し、use の中で :: の前に書く、そのパッケージの mount を通じてアクセスします：

use giftshop::Giftshop

def main(): Unit \ IO =
    Giftshop.buyGift()

mount はパッケージ自身ではなく私たち自身のマニフェストの中で宣言するため、2 つのプロジェクトが同じパッケージを別々の名前で参照することもできます。

mount を宣言しない依存関係は、そのリポジトリの名前でマウントされます。したがって "github:flix/museum" = "4.0.0" はパッケージを museum としてマウントします。これがうまくいくのは、その名前が mount になれる場合、つまり文字の後に文字・数字・アンダースコアが続き、かつキーワードでない場合だけです。museum-giftshop のように名前にハイフンを含むリポジトリにはそのようなデフォルトがないため、mount を宣言するまで Flix はそのエントリを拒否します。これが install が mount を尋ねてくる理由でもあります。Flix が導き出すものと同じ mount であっても、明示的に書くべきです。それは私たちのコードがそのパッケージにアクセスする際の名前であり、マニフェストは読む人がその名前を探す場所だからです。

注意: アクセスできるのは、自分自身のマニフェストが宣言しているパッケージだけです。ここでの flix/museum-clerk のように、依存関係が持ち込むパッケージには、自分のマニフェストに mount がないため、Flix がそれをダウンロードしてビルドしても、自分のコードからはそれを use できません。アクセスするためには、[dependencies] に自分で独自のエントリを追加するか、install flix/museum-clerk を実行して自分でそれを宣言し、与えた mount を通じてアクセスします。

注意: :: を書けるのは use の中だけです。式の中で giftshop::Giftshop.buyGift() と書いたり、型の中で giftshop::Giftshop と書いたりすることはできません。

注意: パッケージの pub 宣言のみにアクセスできます。パッケージが pub と宣言していないモジュールは、そのパッケージ内でプライベートです。

Flix パッケージの削除

Flix パッケージは、[dependencies] からその項目を削除するか、remove コマンドで削除できます：

remove flix/museum-giftshop

これは次のように報告します：

Removed 'flix/museum-giftshop' v2.0.2, which was mounted at 'giftshop'.

どちらの方法でも、削除できるのは自分のマニフェストが宣言しているパッケージだけです。ここでの flix/museum-clerk のように、他の依存関係が持ち込むパッケージは、その依存関係によって宣言されているため、その依存関係と一緒になくなります。

削除されたパッケージのために Flix がダウンロードしたファイルは、lib ディレクトリ で説明するように、無視される状態のまま lib ディレクトリに残ります。

2 つの方法の違い

どちらの方法も同じ依存関係を宣言します。違うのは、誰が選択を行うか、そしていつ変更が反映されるかです：

バージョン・Mount・Security context の行は install について説明しています。upgrade コマンドはバージョンのみを変更し、バージョンとアップグレード で説明するように、別のものを指定しない限りは同じメジャーバージョン内にとどまります。

バージョンとアップグレード の flix/museum のように、plain 以外の security context で信頼させる必要があるパッケージは、そのためマニフェストを編集して宣言します。

Maven 依存関係の追加

[mvn-dependencies] セクションに、Maven 上で公開されている Java ライブラリへの依存関係を追加できます：

[mvn-dependencies]
"org.apache.commons:commons-lang3" = "3.12.0"

注意: Maven 依存関係や JAR 依存関係にはコマンドが存在しません。これらは flix.toml を編集して宣言します。

Flix はこのセクションを Maven の依存関係リゾルバに渡し、そのライブラリと、それが依存するライブラリを一緒にダウンロードします：

Resolving Maven dependencies...
  Adding `org.apache.commons:commons-lang3' (v3.12.0).
  Running Maven dependency resolver.

その後は、Java との相互運用 で説明するように、他の Java ライブラリと同じようにそのライブラリを使用します：

import org.apache.commons.lang3.StringUtils

def main(): Unit \ IO =
    println(StringUtils.reverse("Hello World!"))

URL からの JAR ファイルの追加

[jar-dependencies] セクションで、URL からダウンロードする JAR ファイルに依存できます。キーは JAR ファイルが保存されるファイル名で、.jar で終わる必要があります：

[jar-dependencies]
"commons-lang3.jar" = "url:https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.12.0/commons-lang3-3.12.0.jar"

Flix は依存関係を解決する際に、これをダウンロードします：

Downloading external jar dependencies...
  Downloading `commons-lang3.jar` from `https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.12.0/commons-lang3-3.12.0.jar`... OK.

警告: JAR 依存関係は、その URL がどこを指していようと、そこから配信されるものがそのまま使われます。外部の JAR 依存関係はできるだけ避けるべきです。Flix パッケージの方が優れており、Maven ライブラリの方が URL よりも優れています。

lib ディレクトリ

Flix はダウンロードしたものを lib ディレクトリに配置します。Flix パッケージは lib/github の下に、Maven ライブラリは lib/cache に、URL からダウンロードした JAR ファイルは lib/external に置かれます。各 Flix パッケージは、そのリポジトリとバージョンごとに保持されます：

lib
└── github
    └── flix
        ├── museum-clerk
        │   └── 2.1.2
        │       ├── museum-clerk-2.1.2.fpkg
        │       └── museum-clerk-2.1.2.toml
        └── museum-giftshop
            └── 2.0.2
                ├── museum-giftshop-2.0.2.fpkg
                └── museum-giftshop-2.0.2.toml

lib ディレクトリは Flix によって管理されるため、コミットすべきではありません。また、このディレクトリはスキャンされません。Flix は flix.toml が宣言する依存関係のみを読み込むため、手動で lib に配置したパッケージや JAR ファイルは無視され、削除されたパッケージが残していったものも同様に無視されます。