バージョンとアップグレード

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

マニフェストに書かれたバージョンは、ビルドに使用できる最低バージョンであり、実際に使われる正確なバージョンではありません。Flix は各パッケージについてビルドすべきバージョンを決定し、ダウンロードした内容を記録し、より新しいものがあれば教えてくれます。

Flix の依存関係解決の仕組み

Flix はプロジェクトの依存関係を 4 つのステップで解決します：

Flix は flix.toml を読み込み、依存関係を通じて到達可能なすべての Flix パッケージのマニフェストを、要求されているすべてのバージョンについてダウンロードします。
Flix は各パッケージについて、ビルドすべき単一のバージョンを決定します。
Flix は、選択された各パッケージのパッケージファイルをダウンロードします。
Flix は各パッケージの Maven の依存関係を調べ、それらをダウンロードします。

これらのステップが実際に働く様子は、flix/museum に依存するプロジェクトで確認できます：

[dependencies]
"github:flix/museum" = { version = "4.0.0", mount = "museum", security = "unrestricted" }

このパッケージは、自身の依存関係の 1 つを通じて Java に手を伸ばすため、依存関係の信頼で説明するように unrestricted と宣言しなければなりません。次のような依存関係ツリーを持っています：

flix/museum は以下に依存します：
- flix/museum-clerk（v2.1.3）
- flix/museum-entrance は以下に依存します：
  - flix/museum-clerk（v2.1.2）
- flix/museum-giftshop は以下に依存します：
  - flix/museum-clerk（v2.1.2）
- flix/museum-restaurant は以下に依存します：
  - org.apache.commons:commons-lang3

そして、1 つの依存関係から 5 つのパッケージが得られます：

Found 'flix.toml'. Checking dependencies...
Resolving Flix dependencies...
  Downloading `flix.toml` from `flix/museum` (v4.0.0)... OK.
  Downloading `flix.toml` from `flix/museum-clerk` (v2.1.3)... OK.
  Downloading `flix.toml` from `flix/museum-entrance` (v2.0.2)... OK.
  Downloading `flix.toml` from `flix/museum-giftshop` (v2.0.2)... OK.
  Downloading `flix.toml` from `flix/museum-restaurant` (v2.0.2)... OK.
  Downloading `flix.toml` from `flix/museum-clerk` (v2.1.2)... OK.
  Cached `flix.toml` from `flix/museum-clerk` (v2.1.2).
  Raised `flix/museum-clerk` (v2.1.2 -> v2.1.3), required by `flix/museum` (v4.0.0).
Downloading Flix dependencies...
  Downloading `package.fpkg` from `flix/museum-restaurant` (v2.0.2)... OK.
  Downloading `package.fpkg` from `flix/museum-giftshop` (v2.0.2)... OK.
  Downloading `package.fpkg` from `flix/museum-clerk` (v2.1.3)... OK.
  Downloading `package.fpkg` from `flix/museum` (v4.0.0)... OK.
  Downloading `package.fpkg` from `flix/museum-entrance` (v2.0.2)... OK.
Resolving Maven dependencies...
  Adding `org.apache.commons:commons-lang3' (v3.12.0).
  Running Maven dependency resolver.
Downloading external jar dependencies...
Dependency resolution completed.

flix/museum-clerk のマニフェストは、要求されている両方のバージョンでダウンロードされますが、ビルドされるのはそのうちの 1 つだけです。

Flix がバージョンを選ぶ仕組み

Flix は、依存関係グラフの中で何かが要求している最大のバージョンでパッケージをビルドします。これは、すべての依存先を満たす最小のバージョンでもあります。

言い換えると、依存関係グラフの 2 つの部分が同じパッケージの異なるバージョンを要求している場合、Flix はそのうちの新しい方を採用します。これがうまくいくのは、マニフェスト内のバージョンが下限だからです。より古いバージョンを要求する依存先は、メジャーバージョンさえ同じであれば、より新しいバージョンでビルドされても問題ありません。そのため、要求したものより古いバージョンのパッケージが使われることは決してなく、むしろ新しいバージョンが使われることがあります。

上の例では、flix/museum は flix/museum-clerk をバージョン 2.1.3 で要求していますが、flix/museum-entrance と flix/museum-giftshop はバージョン 2.1.2 で要求しています。Flix はこれを 2.1.3 でビルドし、次のように報告します：

  Raised `flix/museum-clerk` (v2.1.2 -> v2.1.3), required by `flix/museum` (v4.0.0).

パッケージは 1 つのバージョンでのみビルドされます。 プロジェクトが同じパッケージの異なるメジャーバージョンに推移的に依存している場合、どの単一バージョンもすべての依存先を満たすことができないため、Flix はエラーを報告します。例えば、flix/museum-giftshop が flix/museum-clerk をバージョン 1.1.0 で要求し、他の依存先がそれぞれ 2.1.2 と 2.1.3 で要求している場合：

Found incompatible versions of the same package in the dependency graph:
  The package 'github:flix/museum-clerk' is required at versions that do not share a major version:

    1.1.0 required by 'flix/museum-giftshop'
    2.1.2 required by 'flix/museum-entrance'
    2.1.3 required by 'flix/museum'

  A package is built at one version, which must satisfy every dependent: it must
  be at or above the version the dependent requires, and have the same major version.
  No version satisfies these, so one of the dependents must move across a major version.

この場合、どちらかの依存先がメジャーバージョンをまたいで移行する必要がありますが、それができるのはその作者だけです。

Flix のバージョン

各パッケージは、その flix フィールドの中で、そのパッケージをビルドできる最も古い Flix のバージョンを宣言します。Flix は依存関係グラフ内のすべてのパッケージのこのフィールドを確認し、現在実行中のバージョンよりも新しい Flix のバージョンを要求するパッケージのビルドを拒否します：

The package 'github:flix/museum' 4.0.0 requires Flix version 0.76.2, but the current version is 0.76.1.
Please upgrade to Flix 0.76.2 or newer.

ロックファイル

Flix はプロジェクトの依存関係を解決する際、flix.toml の隣に packages.lock ファイルを書き出します。上の例では、次のように始まります：

[lock]
version = 1

[packages."github:flix/museum"."4.0.0"]
toml    = "sha256:5be4c6f17203a0c62294612f2877f52c181e2029153d88c8c65789f64bdf1c5f"
fpkg    = "sha256:c6d22cf0cdb1a45208b175636830f8364308db9f3f7259a2e4960dfb536d1e3c"

[packages."github:flix/museum-clerk"."2.1.2"]
toml    = "sha256:8dc56b5b992d348ce09ace7b4faad00eb81b8803a02ffa2f18051bda93d800de"

[packages."github:flix/museum-clerk"."2.1.3"]
toml    = "sha256:6f34418fffc6c8d5614f32c1f904dbed385bc00e9ac7692e9cbe277fed54f66d"
fpkg    = "sha256:f7817d79093be36bcf9bf1ed66fa920d1e6eab6b1ac3759c1cc6581568b6ff8b"

ロックファイルには、依存関係解決が読み込んだすべてのファイルのダイジェストが記録されます。依存関係グラフが要求するすべてのバージョンにおける各パッケージの flix.toml、そしてビルドされる各パッケージのパッケージファイルです。ここでは、flix/museum-clerk のマニフェストは両方のバージョンで記録されますが、そのパッケージファイルはビルドされるバージョンである 2.1.3 のものだけが記録されます。次回のビルド時、Flix は各ファイルをインストールする際にロックファイルと照合し、以前と同じ内容でなくなった依存関係のコンパイルを拒否します。

ヒント: packages.lock ファイルはバージョン管理にコミットすべきです。

注意: ロックファイルが記録するのは Flix パッケージのみです。Maven ライブラリや URL からダウンロードした JAR ファイルはこれには含まれません。

注意: プロジェクトには effects.lock ファイルも存在する場合があります。これは、依存関係のファイルではなく、そのシグネチャを記録するものであり、詳しくはエフェクトのロックで説明しています。

古くなったパッケージの確認

outdated コマンドを使うと、使用している Flix パッケージに新しいリリースがあるかどうかを確認できます。例えば次のような依存関係を持つプロジェクトでは：

[dependencies]
"github:flix/museum"          = { version = "3.0.1", mount = "museum", security = "unrestricted" }
"github:flix/museum-giftshop" = { version = "2.0.1", mount = "giftshop" }

outdated コマンドは次のように報告します：

package                 declared    built    major    minor    patch
flix/museum             3.0.1       3.0.1    4.0.0             3.0.2
flix/museum-giftshop    2.0.1       2.0.2

パッケージ flix/museum には 2 つの更新が利用可能です。メジャーバージョンを変えずに 3.0.1 から 3.0.2 にアップグレードするか、メジャーバージョンをまたいで 4.0.0 にアップグレードするかです。

この表には 2 つのバージョン列があります：

declared は flix.toml に書かれているバージョンです。
built は、実際にそのパッケージがビルドされているバージョンで、これはより大きい場合があります。宣言されたバージョンは使用できる最低バージョンであり、別の依存先がより新しいバージョンを要求しているかもしれないからです。

パッケージは、実際にビルドされているバージョンで比較されます。ここでは、flix/museum は flix/museum-giftshop をその最新リリースである 2.0.2 で要求しているため、それ以上新しいバージョンに移行する必要はありません。それでも一覧に表示されるのは、実際にビルドされているバージョンよりも古いバージョンを宣言しているためです。代わりに 2.0.2 を宣言することもできます。何も古くなっていない場合、Flix は次のように報告します：

All dependencies are up to date

ヒント: outdated コマンドは、依存関係を一覧に表示する場合は終了ステータス 1 を返し、そうでない場合は 0 を返します。そのため、CI ビルドを失敗させるために利用できます。

注意: 一覧に表示されるのは Flix パッケージのみです。Maven の依存関係はチェックされません。

パッケージのアップグレード

パッケージをアップグレードするには、flix.toml 内のその項目の version を変更するか、upgrade コマンドを使います：

upgrade flix/museum

upgrade コマンドは、現在宣言しているものと同じメジャーバージョンを持つ最新リリースを宣言し、より新しいメジャーバージョンがある場合はそれを教えてくれます：

Upgraded 'flix/museum' v3.0.1 -> v3.0.2.

A newer major release is available, ask for it by name:
  flix upgrade flix/museum@4.0.0

新しいメジャーバージョンはコードを壊す可能性があるため、upgrade はそのバージョンを名指ししたときにのみそのバージョンへ移行します：

upgrade flix/museum@4.0.0

名指ししたバージョンはそのまま採用されるため、古いリリースを名指しして戻ることもできます。upgrade コマンドが変更するのはバージョンのみで、mount と security context は宣言したままになります。

複数のパッケージを名指しすることも、まったく名指ししないこともできます。何も名指ししない場合、upgrade はマニフェストが宣言しているすべての Flix パッケージを、それぞれのメジャーバージョン内でアップグレードし、変更したものだけを報告します。古くなったパッケージの確認のプロジェクトでは、次のように報告されます：

Upgraded 'flix/museum' v3.0.1 -> v3.0.2.
Upgraded 'flix/museum-giftshop' v2.0.1 -> v2.0.2.

A newer major release is available, ask for it by name:
  flix upgrade flix/museum@4.0.0

1 回のコマンドでアップグレードされるパッケージは、まとめて変更されるか、まったく変更されないかのどちらかです。あるパッケージの新しいメジャーバージョンが別のパッケージの新しいメジャーバージョンを要求しているために、2 つのパッケージを同時に新しいメジャーバージョンへ移行させなければならない場合は、flix.toml の 1 回の編集で両方を変更するか、1 回の upgrade コマンドで両方を名指しします。

Keyboard shortcuts