パッケージの依存関係

pub パッケージマネージャー のコア コンセプトの 1 つが依存関係です。依存関係とは、パッケージの動作に必要な別のパッケージのことです。依存関係は、pubspec で指定します。直接依存関係のみをリストします。これは、パッケージが直接使用するソフトウェアのことです。Pub は推移的な依存関係を処理します。

このページには、依存関係の指定方法に関する詳細情報があります。末尾には、パッケージ依存関係のベスト プラクティスのリストがあります。

各依存関係について、依存しているパッケージの名前と、許可されるそのパッケージのバージョン範囲を指定します。また、ソースを指定することもできます。ソースは、Pub がパッケージを検出する方法を Pub に指示します。

例として、依存関係は次の形式で指定します。

dependencies:
  transmogrify: ^1.0.0

この YAML コードは、デフォルトのパッケージ リポジトリ (pub.dev) を使用し、1.0.0 から 2.0.0 (2.0.0 を除く) までの任意のバージョンを許可して、transmogrify パッケージへの依存関係を作成します。この構文については、バージョン制約をご覧ください。

pub.dev 以外のソースを指定するには、sdk、hosted、git、または path を使用します。たとえば、次の YAML コードでは path を使用して、Pub にローカル ディレクトリから transmogrify を取得するように指示します。

dependencies:
  transmogrify:
    path: /Users/me/transmogrify

次のセクションでは、各依存関係ソースの形式について説明します。

Pub は、パッケージを検出するために次のソースを使用できます。

• SDK
• ホストされているパッケージ
• Git パッケージ
• パス パッケージ

ホストされているパッケージとは、pub.dev サイト (または同じ API を使用する別の HTTP サーバー) からダウンロードできるパッケージです。ホストされているパッケージへの依存関係を宣言する例を次に示します。

dependencies:
  transmogrify: ^1.4.0

この例では、パッケージがホストされている transmogrify という名前のパッケージに依存しており、1.4.0 から 2.0.0 (2.0.0 自体を除く) までの任意のバージョンで動作することを示しています。

独自のパッケージ リポジトリを使用したい場合は、hosted を使用してその URL を指定できます。次の YAML コードは、hosted ソースを使用して transmogrify パッケージへの依存関係を作成します。

environment:
  sdk: '^2.19.0'

dependencies:
  transmogrify:
    hosted: https://some-package-server.com
    version: ^1.4.0

バージョン制約はオプションですが、推奨されます。バージョン制約が指定されていない場合は、any が想定されます。

ときに、まだ正式にリリースされていないパッケージを使用する必要がある場合があります。おそらく、あなたのパッケージ自体がまだ開発中であり、同時に開発されている他のパッケージを使用している場合です。これを容易にするために、Git リポジトリに保存されているパッケージに直接依存できます。

dependencies:
  kittens:
    git: https://github.com/munificent/kittens.git

ここでの git は、パッケージが Git を使用して見つかることを示しており、その後の URL はパッケージをクローンするために使用できる Git URL です。

パッケージ リポジトリがプライベートであっても、git セットアップを構成して、HTTPS アクセス キーまたはSSH キーペアを使用してリポジトリにアクセスできます。その後、対応する URL を使用してパッケージに依存できます。

dependencies:
  kittens:
    # SSH URL:
    git: git@github.com:munificent/kittens.git

dart pub コマンドは git clone をサブプロセスとして呼び出すため、提供する必要があるのは、git clone <url> が実行されたときに機能する <url> だけです。

特定のコミット、ブランチ、またはタグに依存したい場合は、説明に ref キーを追加します。

dependencies:
  kittens:
    git:
      url: git@github.com:munificent/kittens.git
      ref: some-branch

ref は、Git がコミットを識別するために許可するものであれば何でも構いません。

Pub は、パッケージが Git リポジトリのルートにあると想定します。リポジトリ内の別の場所を指定するには、リポジトリ ルートからの相対パスを指定します。

dependencies:
  kittens:
    git:
      url: git@github.com:munificent/cats.git
      path: path/to/kittens

パスは Git リポジトリのルートからの相対パスです。

Git 依存関係は、pub.dev にアップロードされるパッケージの依存関係としては許可されません。

複数の関連パッケージを同時に作業することがあります。たとえば、フレームワークを作成しながら、それを使用するアプリをビルドしている場合などです。これらの場合、開発中は、ローカル ファイル システム上のそのパッケージのライブバージョンに依存したいと考えます。そうすれば、あるパッケージの変更は、それに依存するパッケージですぐに検出されます。

これを処理するために、Pub はパス依存関係をサポートしています。

dependencies:
  transmogrify:
    path: /Users/me/transmogrify

これは、transmogrify のルート ディレクトリが /Users/me/transmogrify であることを示しています。この依存関係について、Pub は参照されるパッケージ ディレクトリの lib ディレクトリへのシンボリック リンクを直接生成します。依存パッケージに対して行う変更はすぐに反映されます。依存パッケージを変更するたびに Pub を実行する必要はありません。

相対パスも許可されており、pubspec を含むディレクトリからの相対パスとして扱われます。

パス依存関係はローカル開発に役立ちますが、外部とコードを共有する際には機能しません。誰もがファイル システムにアクセスできるわけではありません。そのため、pubspec にパス依存関係があるパッケージを pub.dev サイトにアップロードすることはできません。

代わりに、一般的なワークフローは次のとおりです。

1. ローカルで pubspec を編集して、パス依存関係を使用します。
2. メイン パッケージとその依存関係にあるパッケージを操作します。
3. 両方が機能したら、依存パッケージを公開します。
4. pubspec を変更して、現在ホストされている依存関係のバージョンを指すようにします。
5. 必要に応じて、メイン パッケージも公開します。

SDK ソースは、パッケージと一緒に配布される SDK (それ自体が依存関係になる可能性があります) に使用されます。現在、Flutter が唯一サポートされている SDK です。

構文は次のようになります。

dependencies:
  flutter_driver:
    sdk: flutter

sdk: の後の識別子は、パッケージがどの SDK から取得されるかを示します。flutter の場合、依存関係は、次の場合に満たされます。

• Pub が flutter 実行可能ファイルのコンテキストで実行されている
• Flutter SDK に指定された名前のパッケージが含まれている

不明な識別子の場合は、依存関係は常に満たされないと見なされます。

パッケージ A がパッケージ B に依存しているとしましょう。パッケージ A の特定のバージョンと互換性のあるパッケージ B のバージョンを他の開発者にどのように伝えることができますか?

バージョン互換性を開発者に知らせるには、バージョン制約を指定します。パッケージのユーザーに柔軟性を持たせるために、可能な限り広いバージョン範囲を許可したいと考えます。範囲には、機能しないバージョンやテストされていないバージョンを含めるべきではありません。

Dart コミュニティはセマンティック バージョニング¹ を使用しています。

Dart 2.19 以降では、従来の構文またはキャレット構文のいずれかを使用してバージョン制約を表現できます。どちらの構文も、互換性のあるバージョンの範囲を指定します。

従来の構文は、'>=1.2.3 <2.0.0' のような明示的な範囲を提供します。キャレット構文は、^1.2.3 のような明示的な開始バージョンを提供します。

environment:
  # This package must use a 3.x version of the Dart SDK starting with 3.2.
  sdk: ^3.2.0

dependencies:
  transmogrify:
    hosted:
      name: transmogrify
      url: https://some-package-server.com
    # This package must use a 1.x version of transmogrify starting with 1.4.
    version: ^1.4.0

Pub のバージョン システムの詳細については、パッケージ バージョニング ページを参照してください。

従来の構文を使用したバージョン制約では、次のいずれかの値を使用できます。

バージョンの範囲が交差するため、任意のバージョン値の組み合わせを指定できます。たとえば、バージョン値を '>=1.2.3 <2.0.0' に設定した場合、これは両方の制限を組み合わせて、依存関係を 1.2.3 から 2.0.0 (2.0.0 を除く) の範囲の任意のバージョンにすることができます。

キャレット構文は、バージョン制約をコンパクトに表現します。^version は指定されたバージョンと後方互換性があることが保証されているすべてのバージョンの範囲を意味します。この範囲には、破壊的変更が導入される次のメジャーバージョンまでのすべてのバージョンが含まれます。Dart はセマンティック バージョニングを使用するため、バージョン 1.0 以降のパッケージの場合は次のメジャー バージョン、バージョン 1.0 より前のパッケージの場合は次のマイナー バージョンになります。

次の例はキャレット構文を示しています。

dependencies:
  # Covers all versions from 1.3.0 to 1.y.z, not including 2.0.0
  path: ^1.3.0
  # Covers all versions from 1.1.0 to 1.y.z, not including 2.0.0
  collection: ^1.1.0
  # Covers all versions from 0.1.2 to 0.1.z, not including 0.2.0
  string_scanner: ^0.1.2

Pub は、通常の依存関係と開発依存関係の 2 種類をサポートしています。開発依存関係は、通常の依存関係とは異なり、依存するパッケージの開発依存関係は無視されます。例を次に示します。

transmogrify パッケージが、テストで test パッケージを使用しており、テストでのみ使用しているとします。transmogrify を使用したいだけのユーザー (ライブラリをインポートするだけ) は、実際には test を必要としません。この場合、test を開発依存関係として指定します。その pubspec には次のようなものが含まれるはずです。

dev_dependencies:
  test: ^1.25.0

Pub は、パッケージが依存するすべてのパッケージ、およびそれらが推移的に依存するすべてを取得します。また、パッケージの開発依存関係も取得しますが、依存するパッケージの開発依存関係は無視します。Pub はあなたのパッケージの開発依存関係のみを取得します。したがって、パッケージが transmogrify に依存している場合、transmogrify は取得しますが、test は取得しません。

通常の依存関係と開発依存関係を区別するルールは簡単です。依存関係が lib または bin ディレクトリ内のものからインポートされる場合、通常の依存関係である必要があります。test、example などからのみインポートされる場合は、開発依存関係にすることができます。

開発依存関係を使用すると、依存関係グラフが小さくなります。これにより、pub の実行が高速になり、すべての制約を満たすパッケージバージョンのセットを見つけやすくなります。

dependency_overrides を使用すると、依存関係へのすべての参照を一時的にオーバーライドできます。

たとえば、公開されているパッケージである transmogrify のローカル コピーを更新しているとします。Transmogrify は依存関係グラフ内の他のパッケージによって使用されていますが、各パッケージをローカルにクローンして、ローカル コピーの transmogrify をテストするために各 pubspec を変更したくありません。

この状況では、dependency_overrides を使用して依存関係をオーバーライドし、パッケージのローカル コピーを保持するディレクトリを指定できます。

pubspec は次のようなものになります。

name: my_app
dependencies:
  transmogrify: ^1.2.0
dependency_overrides:
  transmogrify:
    path: ../transmogrify_patch/

dart pub get または dart pub upgrade を実行すると、pubspec のロックファイルは依存関係の新しいパスを反映するように更新され、transmogrify が使用されている場所ではどこでも、Pub は代わりにローカル バージョンを使用します。

dependency_overrides を使用して、特定のバージョンのパッケージを指定することもできます。

name: my_app
dependencies:
  transmogrify: ^1.2.0
dependency_overrides:
  transmogrify: '3.2.1'

パッケージの解決中に考慮されるのは、パッケージ自体の pubspec の依存関係オーバーライドのみです。依存されているパッケージ内の依存関係オーバーライドは無視されます。

その結果、pub.dev にパッケージを公開する場合、パッケージの依存関係オーバーライドは、パッケージのすべてのユーザーによって無視されることに注意してください。

Pub ワークスペースを使用している場合、各ワークスペース パッケージに dependency_overrides を含めることができますが、単一のパッケージはワークスペース内で 1 回だけオーバーライドできます。

pubspec.yaml ファイルの特定の側面を解決方法の変更したいが、実際のファイルは変更したくない場合は、pubspec.yaml の隣に pubspec_overrides.yaml という名前のファイルを配置できます。

そのファイルからの属性は、pubspec.yaml からの属性をオーバーライドします。

オーバーライドできるプロパティは次のとおりです。

• dependency_overrides
• workspace
• resolution

これは、一時的なオーバーライドをバージョン管理に誤ってコミットすることを避けるのに役立ちます。また、スクリプトからオーバーライドを生成しやすくすることもできます。

Pub ワークスペースでは、各ワークスペース パッケージに pubspec_overrides.yaml ファイルを含めることができます。

依存関係の管理に積極的に取り組みましょう。可能な限り、パッケージが最新バージョンのパッケージに依存していることを確認してください。パッケージが古いパッケージに依存している場合、その古いパッケージは依存関係ツリー内の他の古いパッケージに依存している可能性があります。古いバージョンのパッケージは、アプリケーションの安定性、パフォーマンス、および品質に悪影響を与える可能性があります。

パッケージ依存関係のベスト プラクティスを次に示します。

キャレット構文を使用して依存関係を指定します。これにより、Pub ツールが利用可能になったときにパッケージの新しいバージョンを選択できるようになります。さらに、許可されるバージョンに上限を設定します。

dart pub upgrade を使用して、pubspec で許可されている最新のパッケージ バージョンに更新します。アプリまたはパッケージで最新の安定バージョンではない依存関係を特定するには、dart pub outdated を使用します。

開発依存関係は、開発中にのみ必要なパッケージを定義します。完成したアプリケーションではこれらのパッケージは必要ありません。これらのパッケージの例には、テストやコード生成ツールなどがあります。dev_dependencies のパッケージのバージョン制約は、パッケージが依存する最新バージョンを下限として設定します。

開発依存関係のバージョン制約を厳格化することは、次のようなものになります。

dev_dependencies:
  build_runner: ^2.4.15
  lints: ^5.1.1
  test: ^1.25.15

この YAML は、dev_dependencies を最新のパッチ バージョンに設定します。

pubspec を更新せずにdart pub upgrade を実行した場合、API は同じままでコードは以前のように実行されるはずですが、確認のためにテストしてください。pubspec を変更して新しいメジャー バージョンに更新すると、破壊的変更が発生する可能性があるため、さらに徹底的なテストが必要です。

公開用のパッケージを開発する場合、可能な限り広い依存関係制約を許可することが望ましい場合がよくあります。広い依存関係制約は、パッケージの消費者がバージョン解決の競合に直面する可能性を減らします。

たとえば、foo: ^1.2.3 への依存関係があり、foo のバージョン 1.3.0 がリリースされた場合、既存の依存関係制約 (^1.2.3) を維持することが合理的かもしれません。しかし、パッケージが 1.3.0 で追加された機能を使用し始めると、制約を ^1.3.0 に引き上げる必要が出てきます。

しかし、必要になったときに依存関係制約を引き上げるのを忘れるのは簡単です。したがって、公開前にパッケージをダウングレードされた依存関係に対してテストすることはベスト プラクティスです。

ダウングレードされた依存関係でテストするには、dart pub downgrade を実行し、パッケージがエラーなしで解析され、すべてのテストに合格することを確認してください。

dart pub downgrade
dart analyze
dart test

ダウングレードされた依存関係でのテストは、通常、最新の依存関係での通常のテストと並行して行う必要があります。依存関係制約を引き上げる必要がある場合は、自分で変更するか、dart pub upgrade --tighten を使用して依存関係を最新バージョンに更新します。

新しい依存関係を取得するときは、--enforce-lockfile オプションを使用して、抽出されたパッケージの内容が元のアーカイブの内容と一致することを確認します。ロックファイルを変更せずに、このフラグは、次の場合にのみ新しい依存関係を解決します。

• pubspec.yaml が満たされている
• pubspec.lock が欠落していない
• パッケージのコンテンツ ハッシュが一致する