パッケージの使い方

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

name: my_app

以下は、pub.dev サイトでホストされている 2 つのパッケージ (js と intl) への依存関係を宣言する pubspec の例です。

name: my_app

dependencies:
  js: ^0.6.0
  intl: ^0.17.0

手動で編集せずに 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 は他の依存関係と互換性のある最新バージョンをダウンロードします。次に、ロックファイルを作成することにより、そのバージョンを常に使用するようにパッケージをロックします。これは、pub が作成し、pubspec の横に保存する pubspec.lock という名前のファイルです。パッケージが使用する各依存関係 (直接および推移的) の特定のバージョンがリストされています。

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

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

$ dart pub upgrade

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

$ dart pub upgrade transmogrify

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

pubspec の競合するバージョン制約により、dart pub upgrade コマンドは必ずしもすべてのパッケージを最新バージョンにアップグレードできるとは限りません。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 バージョン管理の原則
• Pubspec 形式

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

• add
• cache
• deps
• downgrade
• get
• global
• outdated
• publish
• remove
• token
• unpack
• upgrade

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

Pub のトラブルシューティングでは、pub の使用中に発生する可能性のある問題の解決策を提供します。

特に明記されていない限り、このサイトのドキュメントは Dart 3.5.3 を反映しています。ページの最終更新日は 2024-10-03 です。 ソースを表示 または 問題を報告する。