パッケージ用語集

パッケージ管理 および pubツール のドキュメントで使用される用語を以下に示します。

プログラムまたはアプリが含まれるパッケージで、メインのエントリーポイントがあります。コマンドラインまたはブラウザで直接実行することを目的としています。

アプリケーションパッケージは、他のパッケージへの依存関係を持つことがありますが、それ自体が依存されることはありません。通常のパッケージとは異なり、共有を目的としていません。

アプリケーションパッケージは、ロックファイルをソース管理にチェックインする必要があります。これにより、アプリケーションに取り組むすべての人と、アプリケーションがデプロイされるすべての場所で、一貫した依存関係セットが保証されます。依存関係はロックファイルによって制約されるため、アプリケーションパッケージは通常、依存関係のバージョン制約にanyを指定します。

pub.dev リポジトリは、ホストする各パッケージバージョンの sha256 ハッシュを保持しています。pub クライアントは、このハッシュを使用してダウンロードされたパッケージの整合性を検証し、リポジトリへの変更から保護することができます。

dart pub get がパッケージをダウンロードするとき、ダウンロードされたアーカイブのハッシュを計算します。ホストされている各依存関係のハッシュは、解決とともにロックファイルに格納されます。

pub クライアントは、このコンテンツハッシュを使用して、同じロックファイルを使用して dart pub get を再度実行した場合（異なるコンピューターでも）、まったく同じパッケージが使用されていることを検証します。

ロックされたハッシュが pub キャッシュ内の現在のものと一致しない場合、pub はアーカイブを再ダウンロードします。それでも一致しない場合、ロックファイルは更新され、警告が表示されます。例：

$ dart pub get
Resolving dependencies...
Cached version of foo-1.0.0 has wrong hash - redownloading.
 ~ foo 1.0.0 (was 1.0.0)
The existing content-hash from pubspec.lock doesn't match contents for:
 * foo-1.0.0 from "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 を使用します。これは、ロックファイルを更新せずに、同じハッシュを持つパッケージアーカイブが見つからない場合に解決を失敗させます。

$ dart pub get --enforce-lockfile
Resolving dependencies...
Cached version of foo-1.0.0 has wrong hash - redownloading.
~ foo 1.0.0 (was 1.0.0)
The existing content-hash from pubspec.lock doesn't match contents for:
 * foo-1.0.0 from "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`.

パッケージが依存する別のパッケージ。パッケージが他のパッケージからコードをインポートしたい場合、そのパッケージは依存関係である必要があります。依存関係は、パッケージの pubspec で指定され、パッケージの依存関係で説明されています。

パッケージが使用する依存関係を表示するには、pub deps を使用します。

Dart の一般的な文脈では、エントリーポイントとは、Dart 実装によって直接呼び出される Dart ライブラリのことです。<script> タグで Dart ライブラリを参照したり、スタンドアロン Dart VM のコマンドライン引数として渡したりする場合、そのライブラリがエントリーポイントになります。つまり、通常は main() を含む .dart ファイルです。

pub の文脈では、エントリーポイントパッケージまたはルートパッケージは、依存関係グラフのルートです。通常はアプリケーションになります。アプリを実行するとき、それがエントリーポイントパッケージです。それに依存する他のすべてのパッケージは、そのコンテキストではエントリーポイントではありません。

パッケージは、コンテキストによってはエントリーポイントになったり、ならなかったりします。たとえば、アプリがパッケージ A を使用しているとします。アプリを実行するとき、A はエントリーポイントパッケージではありません。しかし、A に移動してテストを実行する場合、そのコンテキストでは、アプリが関与していないため、エントリーポイントとなります。

パッケージ内で、Dart エントリーポイントを含むことができるディレクトリ。

pub はこれらのディレクトリのリストを持っています：benchmark、bin、example、test、tool、および web（および Flutter アプリの場合は lib）。これらのディレクトリの任意のサブディレクトリ（bin を除く）もエントリーポイントを含むことができます。

パッケージが直接使用する依存関係。pubspec にリストされている依存関係は、パッケージの直接依存関係です。他のすべての依存関係は推移的依存関係です。

ライブラリは単一のコンパイル単位であり、単一のプライマリファイルと任意の数のオプションのパートで構成されます。ライブラリには独自のプライベートスコープがあります。

パッケージが依存するすべての直接依存関係と推移的依存関係の具体的なバージョンとその他の識別情報を示す、pubspec.lock という名前のファイル。

pubspec が直接依存関係のみをリストし、バージョン範囲を許可するのとは異なり、ロックファイルは依存関係グラフ全体を特定のパッケージバージョンに包括的に固定します。ロックファイルにより、アプリケーションが使用するパッケージの正確な構成を再現できます。

ロックファイルは、pub get、pub upgrade、または pub downgrade を実行すると、pub によって自動的に生成されます。pub には、将来の解決中にチェックするための各パッケージのコンテンツハッシュが含まれています。

パッケージがアプリケーションパッケージの場合、通常はこれをソース管理にチェックインします。通常のパッケージでは、通常はチェックインしません。

ディレクトリの下にあるライブラリのコレクションで、そのディレクトリのルートにpubspec.yamlがあります。

パッケージは、他のパッケージへの依存関係を持つことができ、それ自体が依存関係となることもできます。パッケージの /lib ディレクトリには、他のパッケージがインポートして使用できる公開ライブラリが含まれています。直接実行されるスクリプトを含めることもできます。他のパッケージからの依存を意図しないパッケージは、アプリケーションパッケージです。共有パッケージは pub.dev に公開されますが、公開されていないパッケージもあります。

パッケージのロックファイルをソース管理にチェックインしないでください。ライブラリはさまざまな依存関係バージョンをサポートする必要があります。パッケージの直接依存関係のバージョン制約は、テストされたバージョンとの互換性を確保しながら、できるだけ広くする必要があります。

セマンティックバージョニングでは、下位互換性のない変更に対してライブラリがメジャーバージョン番号をインクリメントする必要があるため、パッケージは通常、テストされたバージョン以上で、次のメジャーバージョン未満の依存関係のバージョンを要求します。たとえば、ライブラリが（架空の）transmogrify パッケージに依存しており、バージョン 1.2.1 でテストした場合、バージョン制約は^1.2.1 になります。

パッケージがサポートすると宣言する Dart SDK 自体の宣言されたバージョン。SDK 制約は、通常のバージョン制約構文を使用して指定されますが、pubspec の特別な環境セクションにあります。。

pub がパッケージを取得できる場所の種類。ソースは、pub.dev サイトや特定の Git URL のような特定の場所ではありません。各ソースは、何らかの方法でパッケージにアクセスするための一般的な手順を記述します。たとえば、git は 1 つのソースです。git ソースは、Git URL が与えられた場合にパッケージをダウンロードする方法を知っています。いくつかの異なるサポートされているソースが利用可能です。

pub がリモートパッケージを取得すると、pub によって維持される単一のシステムキャッシュディレクトリにダウンロードされます。Mac および Linux では、このディレクトリのデフォルトは ~/.pub-cache です。Windows では、ディレクトリのデフォルトは %LOCALAPPDATA%\Pub\Cache ですが、その正確な場所は Windows のバージョンによって異なる場合があります。PUB_CACHE 環境変数を使用して別の場所を指定できます。

パッケージがシステムキャッシュに入ると、pub は package_config.json ファイルを作成し、アプリケーションで使用される各パッケージをキャッシュ内の対応するパッケージにマッピングします。

指定されたバージョンのパッケージは一度ダウンロードすればよく、好きなだけ多くのパッケージで再利用できます。--offline フラグを指定してキャッシュされたパッケージを使用するように指定した場合、ネットワークにアクセスせずに package_config.json ファイルを削除して再生成できます。

パッケージの依存関係の 1 つがそれを必要とするため、パッケージが間接的に使用する依存関係。パッケージが A に依存し、A が B に依存し、B が C に依存する場合、A は直接依存関係であり、B と C は推移的依存関係です。

パッケージの管理者権限を持つユーザー。パッケージアップローダーは、パッケージの新しいバージョンをアップロードでき、そのパッケージの他のアップローダーを追加および削除することもできます。

パッケージに検証済みパブリッシャーがいる場合、そのパブリッシャーのすべてのメンバーがパッケージをアップロードできます。

一連のパッケージを所有する 1 人以上のユーザー。各検証済みパブリッシャーは、dart.dev のような検証済みドメイン名によって識別されます。検証済みパブリッシャーに関する一般的な情報については、検証済みパブリッシャーページを参照してください。検証済みパブリッシャーの作成とパッケージの転送の詳細については、パッケージの公開のドキュメントを参照してください。

パッケージが互換性があると想定される依存関係のバージョンを指定する、パッケージの各依存関係に課される制約。これは単一のバージョン (0.3.0) またはバージョンの範囲 (^1.2.1) である可能性があります。any も許可されますが、パフォーマンス上の理由から推奨しません。

詳細については、バージョン制約を参照してください。

パッケージは常にすべての依存関係にバージョン制約を指定する必要があります。一方、アプリケーションパッケージは、ロックファイルを使用して依存関係バージョンを管理するため、通常は依存関係のすべてのバージョンを許可します。

詳細については、Pub バージョニングの哲学を参照してください。

共通の依存関係制約の解決とtogether 開発されるパッケージのコレクション。モノレポでの開発に便利です。

パッケージは、共通の pubspec.lock と .dart_tool/package_config.json を共有します。

ワークスペースの設定と開発の詳細については、Pub ワークスペースを参照してください。