パッケージの使用方法

Dart エコシステムでは、ライブラリやツールなどの共有ソフトウェアを管理するためにパッケージを使用します。Dart パッケージを取得するには、pub パッケージマネージャーを使用します。公開されているパッケージは pub.dev サイトで見つけることもできますし、ローカルファイルシステムや Git リポジトリなど、他の場所からパッケージを読み込むこともできます。パッケージの取得元に関わらず、pub はバージョン依存関係を管理し、互いに、また SDK バージョンと互換性のあるパッケージバージョンを取得するのに役立ちます。

ほとんどの Dart 互換 IDE は、パッケージの作成、ダウンロード、更新、公開を含む pub の使用をサポートしています。または、コマンドラインで dart pub を使用することもできます。

最低限、Dart パッケージは pubspec ファイルを含むディレクトリです。pubspec には、パッケージに関するいくつかのメタデータが含まれています。さらに、パッケージには依存関係（pubspec にリストされている）、Dart ライブラリ、アプリ、リソース、テスト、画像、サンプルを含めることができます。

パッケージを使用するには、次の手順を実行します。

• pubspec を作成します（パッケージの依存関係をリストし、バージョン番号などのその他のメタデータを含む `pubspec.yaml` という名前のファイル）。
• dart pub get を使用して、パッケージの依存関係を取得します。
• Dart コードがパッケージ内のライブラリに依存している場合は、そのライブラリをインポートします。

`pubspec.yaml` という名前のファイルで、アプリケーションの最上位ディレクトリにあります。最も単純な pubspec は、パッケージ名のみをリストします。

name: my_app

これは、pub.dev サイトでホストされている 2 つのパッケージ（`intl` と `path`）への依存関係を宣言する pubspec の例です。

name: my_app

dependencies:
  intl: ^0.20.2
  path: ^1.9.1

手動で編集せずに `pubspec.yaml` ファイルを更新するには、`dart pub add` コマンドを実行できます。次の例では、`vector_math` への依存関係を追加します。

dart pub add vector_math
Resolving dependencies... 
+ vector_math 2.1.3
Downloading vector_math 2.1.3...
Changed 1 dependency!

pubspec の作成に関する詳細は、pubspec ドキュメントと、使用したいパッケージのドキュメントを参照してください。

pubspec を作成したら、アプリケーションの最上位ディレクトリから dart pub get を実行できます。

cd <path-to-my_app>
dart pub get

このプロセスは、依存関係の取得と呼ばれます。

dart pub get コマンドは、アプリが依存しているパッケージを決定し、それらを中央の システムキャッシュに配置します。アプリが公開されているパッケージに依存している場合、pub はそのパッケージを pub.dev サイトからダウンロードします。Git 依存関係の場合は、pub は Git リポジトリをクローンします。推移的な依存関係も含まれます。たとえば、`js` パッケージが `test` パッケージに依存している場合、`pub` は `js` パッケージと `test` パッケージの両方を取得します。

Pub は、アプリが依存している各パッケージ名をシステムキャッシュ内の対応するパッケージにマッピングする `package_config.json` ファイル（`.dart_tool/` ディレクトリの下）を作成します。

パッケージ内にあるライブラリをインポートするには、`package:` プレフィックスを使用します。

import 'package:js/js.dart' as js;
import 'package:intl/intl.dart';

Dart ランタイムは、`package:` の後のすべてを取得し、アプリの `package_config.json` ファイル内でそれを検索します。

このスタイルを使用して、独自のパッケージ内のライブラリをインポートすることもできます。`transmogrify` パッケージが次のようにレイアウトされているとします。

transmogrify/
  lib/
    transmogrify.dart
    parser.dart
  test/
    parser/
      parser_test.dart

`parser_test.dart` ファイルは、次のように `parser.dart` をインポートできます。

import 'package:transmogrify/parser.dart';

パッケージに新しい依存関係を最初に追加するとき、pub はそれを他の依存関係と互換性のある最新バージョンでダウンロードします。次に、ロックファイルを作成することで、パッケージが常にそのバージョンを使用するようにロックします。これは `pubspec.lock` という名前のファイルで、pub が作成して pubspec の隣に保存します。パッケージが使用する各依存関係（直接および推移的）の特定のバージョンをリストします。

パッケージが アプリケーションパッケージの場合、このファイルをソース管理にチェックインする必要があります。これにより、アプリに取り組むすべての人が同じバージョンの依存関係を使用するようになります。ロックファイルをチェックインすると、デプロイされたアプリが同じバージョンのコードを使用することも保証されます。

依存関係を最新バージョンにアップグレードする準備ができたら、dart pub upgrade コマンドを使用します。

dart pub upgrade

dart pub upgrade コマンドは、パッケージの依存関係の最新バージョンを使用してロックファイルを再生成するように pub に指示します。1 つの依存関係のみをアップグレードしたい場合は、アップグレードするパッケージを指定できます。

dart pub upgrade transmogrify

このコマンドは `transmogrify` を最新バージョンにアップグレードしますが、他のすべてはそのままにします。

`dart pub upgrade` コマンドは、pubspec の依存関係の制約が競合するため、すべてのパッケージを最新バージョンにアップグレードできるとは限りません。pubspec の編集が必要な古いパッケージを特定するには、dart pub outdated を使用します。

状況によっては、`dart pub get` は `pubspec.lock` ファイルにロックされている正確なパッケージバージョンを取得しません。

• `pubspec.lock` ファイルが最後に更新された後に、新しい依存関係が `pubspec.yaml` に追加または削除された場合。
• ロックされたバージョンがパッケージリポジトリに存在しなくなった場合。
• Dart SDK のバージョンを変更し、一部のパッケージが新しいバージョンと互換性がなくなった場合。

これらの場合、`dart pub get` は次のようになります。

• 解決が可能になるように、ロックされた依存関係バージョンの十分なロックを解除します。
• 既存の `pubspec.lock` に対する依存関係の変更について通知します。

たとえば、依存関係に `retry: ^3.0.0` を追加した後。

dart pub get
Resolving dependencies... (1.0s)
Downloading packages... 
+ retry 3.1.2

また、公開されたパッケージバージョンのコンテンツハッシュが `pubspec.lock` ファイルのハッシュと異なる場合、pub は警告を表示し、公開されたバージョンを反映するようにロックファイルを更新します。

たとえば、`pubspec.lock` の `retry` のハッシュを手動で変更した場合。

dart pub get
Resolving dependencies... 
Downloading packages... 
~ retry 3.1.2 (was 3.1.2)
The existing content-hash from pubspec.lock doesn't match contents for:
 * retry-3.1.2 from "https://pub.dev"

This indicates one of:
 * The content has changed on the server since you created the pubspec.lock.
 * The pubspec.lock has been corrupted.

The content-hashes in pubspec.lock has been updated.

For more information see:
https://dart.dokyumento.jp/go/content-hashes
Changed 1 dependency!

プロジェクトを本番環境にデプロイするときは、`dart pub get --enforce-lockfile` を使用して依存関係を取得します。

プロジェクトの依存関係の制約が、`pubspec.lock` の正確なバージョンとコンテンツハッシュで満たせない場合、パッケージの取得とコマンドは失敗します。これにより、テストされていない依存関係や依存関係バージョンを本番環境にデプロイすることを回避できます。

dart pub get --enforce-lockfile
Resolving dependencies... 
Downloading packages... 
~ retry 3.1.2 (was 3.1.2)
The existing content-hash from pubspec.lock doesn't match contents for:
 * retry-3.1.2 from "https://pub.dev"

This indicates one of:
 * The content has changed on the server since you created the pubspec.lock.
 * The pubspec.lock has been corrupted.

For more information see:
https://dart.dokyumento.jp/go/content-hashes
Would change 1 dependency.
Unable to satisfy `pubspec.yaml` using `pubspec.lock`.

To update `pubspec.lock` run `dart pub get` without `--enforce-lockfile`.

次のページに、パッケージと pub パッケージマネージャーに関する詳細情報があります。

• パッケージの作成
• パッケージの公開
• Pub ワークスペース（モノレポサポート）

• Pub 依存関係
• Pub 環境変数
• Pub 用語集
• Pub パッケージレイアウト規約
• Pub バージョン管理の考え方
• Pubspec フォーマット

dart pub ツールは次のサブコマンドを提供します。

• 追加
• キャッシュ
• 依存関係
• ダウングレード
• 取得
• グローバル
• 古い
• 発行
• 削除
• トークン
• 解凍
• アップグレード

dart pub のすべてのサブコマンドの概要については、pub ツールのドキュメントを参照してください。

Pub のトラブルシューティングには、pub の使用中に発生する可能性のある問題の解決策が記載されています。